Working with a Monorepo
Canvas manages plugin code as one git repository per plugin. Canvas Platform hosts that repository, canvas init creates its local copy with origin pointing at Canvas Platform, and canvas deploy pushes your commits to it, so the repository you work in and the plugin’s repository on Canvas Platform share one history.
That works well for a team that develops each plugin on its own. Other teams keep many plugins in one repository, often a monorepo beside shared code and services, and review and release them through that repository. A plain canvas deploy refuses a package inside such a repository, because it would push the whole repository as the plugin and point the repository’s origin at Canvas Platform.
canvas deploy --snapshot is for that case. It publishes each plugin from where it sits, and your repository stays the source of truth. Canvas Platform still keeps one repository per plugin: each snapshot of a changed package adds one commit to that plugin’s main holding the package folder as committed in your repository, and a snapshot of an unchanged package pushes nothing.
Lay out each plugin #
Each plugin’s package folder, the folder holding CANVAS_MANIFEST.json, can sit anywhere in your repository. Give it the same name as the manifest name. Existing plugins keep the names they have. Signed in with canvas login, canvas init names a new plugin with your organization’s prefix, <org prefix>__<package>:
your-repo/
├── plugins/
│ ├── acme__intake/ # package folder: this is what a snapshot ships
│ │ ├── CANVAS_MANIFEST.json
│ │ └── handlers/
│ └── referrals/
│ ├── acme__referrals/ # package folder
│ └── tests/ # stays in your repository
└── services/ # stays in your repository
A snapshot ships only the package folder. Tests, other plugins and the rest of your repository never reach Canvas Platform. The manifest name decides which Canvas Platform repository a snapshot goes to, so every checkout and pipeline that deploys a plugin deploys to the same place.
Deploy from your machine #
Sign in once with canvas login, commit your changes, and pass the path to the package folder:
$ canvas deploy plugins/acme__intake --snapshot --instance acme-staging
deploy builds one commit on top of the plugin’s main on Canvas Platform, pushes it from a temporary repository, and deploys it. Your repository’s origin, git config and index are never changed. Uncommitted changes in the package are refused rather than committed. Add --push-only to publish the code and its catalog listing without deploying to an instance.
Deploy from CI #
A pipeline signs in as a service account: create one on the Credentials page in Canvas Platform, store its token as a CI secret, and expose it as CANVAS_PLATFORM_TOKEN. A snapshot needs no git identity on the runner. Check out full history without file contents, as below: the check that stops a deploy from rolling the plugin back needs the commit main was last deployed from, and a shallow checkout usually lacks it, so deploy skips that check there and says so. This GitHub Actions workflow deploys one plugin whenever a change to it merges:
on:
push:
branches: [main]
paths: ["plugins/acme__intake/**"]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
filter: blob:none
- run: pip install canvas
- run: canvas deploy plugins/acme__intake --snapshot --instance acme-staging
env:
CANVAS_PLATFORM_TOKEN: ${{ secrets.CANVAS_PLATFORM_TOKEN }}
The commit on Canvas Platform is authored as the service account, and its message names the commit and path it came from (Monorepo-Commit and Monorepo-Path). Give each plugin its own job, or loop over the plugins a merge changed.
With Canvas Studio and gated release #
When your organization builds plugins in Canvas Studio with gated release pointed at your repository, Studio’s work reaches your release instances only through your repository’s review:
- Build and test. Studio users build the plugin and test it on the Studio test instance. Studio keeps this work in progress on the
canvas-studiobranch of the plugin’s Canvas Platform repository. - Pull request. Promoting from Studio’s Final Review opens a pull request in your repository (on GitLab, a merge request) that writes the plugin into its folder there. Studio writes the plugin’s
mainon Canvas Platform only to create it, with a base commit and no project code, when a project starts. Project code reachesmainonly through review and action by someone at your organization. Studio doesn’t push to a pull request after opening it, and keeps one open per plugin. While it’s open, Studio refuses to promote the plugin again. After it merges, Studio refuses to promote the plugin until the snapshot from step 4 is on Canvas Platform’smain. If you close it without merging, the next promotion opens a new one. - Review and merge. Your engineers review it like any other change. They can approve it as it is, push edits to its branch, or change the plugin after merging. While the pull request is open, and after it is merged, a change to its branch or to the plugin on
main, in your repository or on Canvas Platform, keeps the project in Promoted. Studio updates the Testing Checklist to the new code and redeploys it to the Studio test instance through the usual test deploy and its checks. When the change came in through a Studio user’s own action (opening the project, or Publish), Studio redeploys it for that user. When it came in on its own, such as Studio’s check after your engineers push, Studio asks a Studio user before that deploy. The plugin reaches production only after your engineers merge the pull request and deploy the snapshot in step 4. If it is closed without merging, a change sends the project back to Test & Iterate. Once it is merged, Studio users’ further changes go into the next iteration, which starts from the merged snapshot. Edits on the branch that conflict with the project also send it back to Test & Iterate, where they can be merged and tested. - Snapshot. Once it merges, CI or an engineer runs
canvas deploy <package folder> --snapshot. The package folder is the one holdingCANVAS_MANIFEST.jsoninside the folder Studio’s pull request writes. Canvas Platform’smaingets one commit with the plugin exactly as merged, and it deploys to the instances you name. - Studio brings it in. When a Studio project opens, and before any deploy from it, Studio brings in new commits on Canvas Platform’s
mainandcanvas-studiothat it has not synced yet. Your engineers’ edits become the starting point of the next iteration within Studio, and are never overwritten by it.
To review the pull request with the same checks as Studio’s Final Review, run Canvas Plugin Assistant (CPA) on the branch with /cpa:security-review, /cpa:database-performance-review, /cpa:coverage, and /cpa:wrap-up.
Because Studio reads both branches, your engineers can work with Studio users directly on iterative changes: push work in progress to canvas-studio with canvas deploy <package folder> --snapshot --branch canvas-studio, and the Studio project brings it in the same way. Like any commit not on main, it deploys only to your organization’s test instances. When Studio has pushed to canvas-studio since your last snapshot there, deploy lists the files the snapshot would replace, as described in When a snapshot stops.
For the same flow as Studio users see it, share the Canvas help center’s Gated release: from Promote to Production and When code changes outside Studio.
When a snapshot stops #
deploy --snapshot exits non-zero without pushing when:
- The package has uncommitted changes, or holds a git submodule, a symbolic link, or a file stored through a git filter such as Git LFS or git-crypt. Commit the changes, or replace those entries with regular files.
- HEAD lacks changes
mainwas last deployed with.deploylists the package files that the last deployed commit changed and HEAD does not, since deploying would roll them back. Update the checkout, for example withgit pull, and deploy again. A branch that was deployed and then squash- or rebase-merged does not stop here, because HEAD carries its changes. mainon Canvas Platform has changes the snapshot would replace, such as an edit to the plugin’s catalog listing made in Canvas Platform.deploylists the files. To keep the changes,canvas clonethe plugin, copy its versions of those files into your repository, commit them, and deploy again. To replace them, run the deploy at a terminal and confirm.
A commit on main tagged snapshot-baseline/<sha> counts as the last snapshot. Canvas Studio tags the commit it starts a plugin’s main from this way. That commit names no source commit, so there is nothing to roll back, and only package files changed on main since it count as changes the snapshot would replace. The first CI snapshot onto such a main needs canvas 0.263.0 or later, which reads these tags: an older CLI treats every package file on main as changed by pushes that were not snapshots, and stops.
The canvas deploy reference covers each case in full.