Git Repo Source

The Git Repo Source is used to pull content from a remote git repository e.g. github.

Installation

yarn add @jpmorganchase/mosaic-source-git-repo

Credentials and Access tokens

To successfully clone the git repo, the source definition must include credentials that have sufficient permissions to clone the repository.

We recommend storing a personal access token in an environment variable and using the environment variable in the source definition.

This keeps credentials out of code where they may be accidentally exposed to third parties.

Example

export MOSAIC_DOCS_CLONE_CREDENTIALS="<repo username>:<Personal Access Token (PAT) provided by your Repo OR password>",

Configuration

PropertyDescriptionRequired
modulePathThe path to the installed module (@jpmorganchase/mosaic-source-git-repo)Yes
namespaceThe scope for this source.Yes
disabledWhen true, content from this source is not usedNo
options.credentialsCollection of URLS to make requestsYes
options.prefixDirThe root path used in the content URLYes
options.subfolderThe name of the folder within the cloned repo containing the docsYes
options.repoThe repo URLYes
options.branchThe branch or tag to cloneYes
options.extensionsCollection of file extensions that the source will look for inside the subfolderYes
options.remoteThe name of the git remote to use. Defaults to origin.Yes

Example Git Repo Source Definition


 {
      modulePath: '@jpmorganchase/mosaic-source-git-repo',
      namespace: 'mosaic',
      options: {
        credentials: process.env.MOSAIC_DOCS_CLONE_CREDENTIALS,
        prefixDir: 'mosaic',
        subfolder: 'docs',
        repo: 'https://github.com/jpmorganchase/mosaic.git',
        branch: 'main',
        extensions: ['.mdx'],
        remote: 'origin'
      }
    }

Editor commit messages

Set the save workflow's commitMessage option on each source to choose its default. Both GitHubPullRequestWorkflow and BitbucketPullRequestWorkflow accept a string or a callback:

import { applyWorkflowOptions, GitHubPullRequestWorkflow } from '@jpmorganchase/mosaic-workflows';

const source = {
  modulePath: '@jpmorganchase/mosaic-source-git-repo',
  namespace: 'handbook',
  options: {
    // Your repository, credentials, branch, subfolder and prefixDir settings.
  },
  workflows: [
    applyWorkflowOptions(GitHubPullRequestWorkflow, {
      commitMessage: (filePath, { action, targetRoute }) =>
        `docs(handbook): ${action} ${filePath}${targetRoute ? ` to ${targetRoute}` : ''}`,
      titlePrefix: 'Handbook'
    })
  ]
};

The callback runs on the server. Its first argument remains the backing virtual filesystem path, so existing one-argument callbacks still work. The second argument contains action (create, update or rename) and, when supplied, targetRoute. The source selected for the page supplies the default; the browser cannot select a different source. New pages follow the same ownership rules as saving a new page.

The reference editor shows this default in Commit message, where the author can enter a summary and optional body. Reset to default restores the current suggestion. A rename updates the suggestion until the author edits it. Author text survives a failed save and closing/reopening the dialog for the same document; it resets after a successful save or a document change. Editing only the message does not enable saving an otherwise unchanged page.

The submitted message takes precedence over the source default. With neither configured nor submitted, the built-in messages are docs: update <filePath>, docs: create <filePath> and docs: rename <filePath> to <targetRoute>. These replace the old ticket-specific fallback. Configured and submitted text is never rewritten for create or rename operations.

Messages must contain non-whitespace text, fit within 8 KiB of UTF-8, and contain no control characters other than line endings. CRLF is normalized to LF; other text is preserved, with Git adding a terminal newline when the message has none. Explicitly blank messages are errors, while omitting the override keeps the configured default.

Both providers use the first nonempty message line, trimmed, as the pull request summary. A nonempty titlePrefix is prepended as <titlePrefix> - <summary>; set it to '' to use the summary alone. Long pull request titles are shortened to fit provider limits, including the prefix. The full commit message is preserved. The default prefix remains Mosaic Docs. The commit receives the full message, including its body. The final squash message is controlled by repository settings and the reviewer.

Custom editor hosts opt in by passing loadSaveDefaults to Editor and forwarding the optional commitMessage in their persist handler. Hosts without that loader retain their existing save flow and show no message control. A custom workflow can expose a side-effect-free prepare hook returning { supportsCommitMessage: true, commitMessage: '...' }; it must also honor and validate submitted messages in its action. Without the hook, defaults report { supportsCommitMessage: false } and the editor uses the existing save flow.

Refresh on push (Bitbucket webhooks)

A git repo source checks its repository for new commits every checkIntervalMins (30 minutes by default, see Schedules). Bitbucket Data Center can tell the Mosaic CLI about a push instead, so merged changes appear within seconds.

Set up

  1. Generate a secret, for example with openssl rand -hex 32, and set it as MOSAIC_BITBUCKET_WEBHOOK_SECRET on the CLI process. Without it the endpoint doesn't exist (404).
  2. In Bitbucket, open the repository's Repository settings → Webhooks and create a webhook:
    • URL: https://<your Mosaic CLI host>/_mosaic_/webhooks/bitbucket
    • Secret: the value of MOSAIC_BITBUCKET_WEBHOOK_SECRET
    • Events: Repository → Push
  3. Select Test connection. The CLI answers 200.

Bitbucket must be able to reach the CLI over HTTP(S), so open any firewall or proxy in between for this path. The endpoint doesn't use MOSAIC_ADMIN_SECRET: it only accepts requests signed with the webhook secret (the X-Hub-Signature header).

What happens on a push

The CLI looks for running git repo sources whose options.repo is the pushed repository and whose options.branch was pushed. Repositories match on project key and repository slug, ignoring case and credentials, so the https://host/scm/PROJ/repo.git, ssh://git@host:7999/proj/repo.git and https://host/projects/PROJ/repos/repo forms all work.

The CLI replies 202 straight away, with the names of the matching sources, and refreshes them in the background. Pushes that reach the same source within 5 seconds are combined into one refresh. A refresh does what a scheduled check does: it fetches, resets the clone to the new commit and re-reads the changed pages, while the source keeps serving its current pages. If MOSAIC_REVALIDATE_URL is set, the site is then told to revalidate as for any other update.

ResponseWhen
200Bitbucket's Test connection (diagnostics:ping)
202A push was received; sources lists the sources being refreshed (it may be empty)
202Any other event; it is ignored
400The push payload isn't valid
401The X-Hub-Signature header is missing or doesn't match the body and the secret
404MOSAIC_BITBUCKET_WEBHOOK_SECRET isn't set
413The body is larger than 1 MB

To test the endpoint by hand, sign the body with the secret:

body='{"test":true}'
signature=$(printf '%s' "$body" | openssl dgst -sha256 -hmac "$MOSAIC_BITBUCKET_WEBHOOK_SECRET" | sed 's/^.* //')
curl -X POST http://localhost:8080/_mosaic_/webhooks/bitbucket \
  -H 'Content-Type: application/json' \
  -H 'X-Event-Key: diagnostics:ping' \
  -H "X-Hub-Signature: sha256=$signature" \
  -d "$body"

Things to know

  • Polling stays on. A delivery the CLI misses (it was restarting, or the network dropped it) is picked up at the next scheduled check. With webhooks in place you can make that check less frequent, for example schedule: { checkIntervalMins: 240, initialDelayMs: 1000 } on the source (see Schedules).
  • Several CLI instances each check on their own schedule, but only the instance that receives the webhook refreshes straight away. If the webhook URL points at a load balancer, the other instances catch up at their next check; add a webhook per instance if they must all update at once.
  • Snapshot and static deployments have no running CLI to call. Trigger a rebuild from your CI pipeline on push instead.
  • Only Bitbucket Data Center push events are supported. Bitbucket Cloud and GitHub webhooks are not.
Mosaic BETA

Coming soon