Skip to main content
Monk organizes deployments into projects and environments. Capsules add preview environments per branch on top of that.

​
Projects, workspaces and environments

  • A project is an app as Monk’s platform knows it. It belongs to your personal account or to an organization.
  • A workspace is a folder on someone’s computer, usually a checkout of the repository, bound to a project. Several people can have workspaces for the same project. The web dashboard lists them under the project’s Workspaces tab.
  • An environment is a named deployment of the project, such as dev, staging or production. Each environment is linked to a cluster, and several environments can share one cluster.
When you deploy to an environment, the environment decides which MANIFEST entry and which images are used, and which cluster receives the deploy. Secrets can be scoped to a project or environment, so staging and production get different values. See Security.
Monk can list the environments for your workspace, select one, and delete one. Deleting asks for approval. A project can only be deleted once it has no environments left. To link a cluster to an environment, Monk binds the cluster. See Clusters and clouds. Environments and projects can carry instructions: guidance your coding agent reads before it works there, such as “use the smallest instance type in staging”. They are guidance, not enforcement. See Teams and access.

​
Capsules (preview environments)

Capsules give each branch its own app environment. When you push a branch, a GitHub Actions workflow deploys that branch. When its pull request closes, the workflow removes the environment.

​
Two modes

The plan you review at setup decides what each capsule creates and what it shares. Production data isn’t copied into capsules.

​
What setup does

Setup needs a configured project (a MANIFEST), a workspace bound to a project, and GitHub credentials entered through the local form. Cloud mode also needs cloud credentials. Monk then:
  1. writes .github/workflows/dynenv.yml, using Monk’s GitHub Actions
  2. creates a scoped API key, valid for 365 days
  3. stores the secrets and variables the workflow needs in a GitHub environment (default monk-capsules)
You review the full plan in the local dashboard before anything is created or pushed. Then commit and push the workflow.

​
Lifecycle

  • Push to a branch: the workflow deploys that branch, creating the capsule if it doesn’t exist yet. main, master and the branch you were on at setup are excluded by default.
  • Pull request closed: the capsule is removed.
  • Manual runs: the workflow can be started from the GitHub Actions tab with provision_deploy, deploy, deprovision or destroy.
The web dashboard lists capsules under the project’s Previews tab, with the branch, pull request, schedule and last deploy.

​
Schedules

A schedule sets when capsules are up or down, for example only on weekday working hours. It has a timezone, rules for date ranges or windows, and a default state outside the rules. The project’s schedule applies to all capsules, and one capsule can override it or go back to the project’s schedule. The workflow checks the schedule every hour. Schedule changes are approved in the dashboard.

​
Capsule secrets

  • Local puts the MANIFEST secrets into the currently selected capsule only.
  • Global pushes them to GitHub and updates the workflow, so all future capsules get them. It can also refresh the cloud credentials stored in GitHub.

Preview environments

Set up Capsules step by step

CI/CD

Deploy one branch to a fixed cluster

Clusters and clouds

Clusters, node tags and binding

Teams and access

Who can deploy where