Skip to main content
Set up Capsules so that every branch you push gets its own copy of your app, with its own URL, created and removed by GitHub Actions. See Capsules for how they work.

​
Before you start

  • The project deploys cleanly to a normal cluster. Capsules run the same MANIFEST, so a template that doesn’t deploy won’t deploy as a capsule either. See Deploy an existing app.
  • The workspace is bound to a project in an organization. Personal projects aren’t supported yet.
  • The repository is on GitHub, and you are on the Pro plan or above.
  • You have the default branch checked out. Setup treats the current branch as the base and never gives it a capsule, so running setup from a feature branch leaves that branch out.

​
Prepare the project

Ask Monk to get the project ready first:
Your coding agent checks the templates for anything that two branches would share and builds those names from the branch instead. Managed databases, buckets, queues and DNS records created outside the cluster are the usual cases. It also adds a health endpoint if the app has none, so a preview can be checked rather than assumed. You review the changes like any other edit to your Monk config. See What is shared between branches.

​
Ask Monk

Choose where capsules run:
  • Own cluster per branch (cloud mode, the default). Each branch gets a new cluster in the cloud, region and machine type you pick, on AWS, GCP, Azure or DigitalOcean. Use this for anything with a web front end.
  • Shared cluster (cluster mode). Capsules run on a pool of nodes in a cluster you already have. Only one branch’s web service is reachable at a time, so this suits workers and internal APIs.
To leave out more branches than the defaults (main, master and the branch you are on):

​
What you review

  1. Credentials. If Monk doesn’t have them yet, forms open in the local dashboard: GitHub, and in cloud mode your cloud account. The GitHub token needs write access to Actions, Secrets, Variables, Environments and Administration on the repository, and read access to Contents and Metadata.
  2. Missing secrets. If your MANIFEST lists secrets Monk doesn’t hold yet, Monk asks for them first, through the local dashboard.
  3. The setup plan. It shows the mode and where capsules run, the repository, the project API key that will be created (valid for 365 days), the name of every GitHub secret it will store, the workflow file and any warnings. Nothing is created or pushed until you approve.

​
Commit and push the workflow

Setup writes .github/workflows/dynenv.yml into your working copy. Commit and push it to the default branch. Capsules start with the next push to any other branch. If the setup result says it couldn’t allow GitHub Actions to create pull requests, turn on Allow GitHub Actions to create and approve pull requests in the repository’s Actions settings yourself. Without it, the [capsule] pull request isn’t opened and closing a branch won’t remove its capsule.

​
What you get

  • .github/workflows/dynenv.yml, built on monk-io/monk-actions
  • A GitHub environment, monk-capsules by default, holding the project API key, the cloud credentials and your MANIFEST secrets
  • For every branch you push: a capsule, a [capsule] <branch> pull request, and a preview URL on the GitHub deployment
The first push of a branch creates its infrastructure, which takes minutes in cloud mode. Later pushes update the same capsule. Follow a run in the repository’s Actions tab, then:
Previews also appear in the web dashboard under the project’s Previews tab.

​
Next