The Git Repo Source is used to pull content from a remote git repository e.g. github.
yarn add @jpmorganchase/mosaic-source-git-repo
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.
export MOSAIC_DOCS_CLONE_CREDENTIALS="<repo username>:<Personal Access Token (PAT) provided by your Repo OR password>",| Property | Description | Required |
|---|---|---|
| modulePath | The path to the installed module (@jpmorganchase/mosaic-source-git-repo) | Yes |
| namespace | The scope for this source. | Yes |
| disabled | When true, content from this source is not used | No |
| options.credentials | Collection of URLS to make requests | Yes |
| options.prefixDir | The root path used in the content URL | Yes |
| options.subfolder | The name of the folder within the cloned repo containing the docs | Yes |
| options.repo | The repo URL | Yes |
| options.branch | The branch or tag to clone | Yes |
| options.extensions | Collection of file extensions that the source will look for inside the subfolder | Yes |
| options.remote | The name of the git remote to use. Defaults to origin. | Yes |
{
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'
}
}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.
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.
- Generate a secret, for example with
openssl rand -hex 32, and set it asMOSAIC_BITBUCKET_WEBHOOK_SECRETon the CLI process. Without it the endpoint doesn't exist (404). - 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
- URL:
- 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).
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.
| Response | When |
|---|---|
200 | Bitbucket's Test connection (diagnostics:ping) |
202 | A push was received; sources lists the sources being refreshed (it may be empty) |
202 | Any other event; it is ignored |
400 | The push payload isn't valid |
401 | The X-Hub-Signature header is missing or doesn't match the body and the secret |
404 | MOSAIC_BITBUCKET_WEBHOOK_SECRET isn't set |
413 | The 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"- 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.