Skip to main content

Branch previews

This section contains details about the branch previews feature, its purpose, and importance.

The branch previews feature makes development and collaboration easier by creating a new endpoint to reach the application for each branch in development. The branch name is appended to the base url for the app to generate a new app and preview link. In addition, when a branch is deleted, it deletes the app automatically.

When you toggle the "Enable branch previews" on, you're prompted to select your default branch. A delete.yaml file is generated and placed in the .github/workflows folder of the default branch. The delete event will only be triggered for development branches .

Raise a PR

When you choose to raise a PR, a new branch containing the configurations for the application to be deployed is created. The new branch name is created as <branch>-arg-<uniqueId>. At this point, three config files are generated and committed.

  • One .art/art.yaml file
  • Two .github/workflows files for managing the build and deploy, as well as deletion of apps

a. <organization>-<environment>-<appName>.yaml

b. <organization>-<environment>-<appName>-delete.yaml

The .art/art.yaml is the file where your app configurations are seen and can be edited. Learn more about it here.

The .github/workflows files are the files that carry out specific jobs as defined in them. That is, the Build and deploy job and also the delete job. Read more about the workflows files.

The contents of the newly created branch is then automatically deployed.

Merge PR

When the PR raised has been approved and merged, the generated config files are also merged (in the case of a new app) or replace the contents of their corresponding existing files. This triggers a deployment.

Create a new branch

If a new branch, dev is created off an already existing branch, main in your repo, the workflow automatically gets triggered which deploys the content of dev (with the new branch name as suffix).

Delete branch

Deleting the branch triggers the .github/workflows/argonaut-<environment>-<appName>-delete.yaml action on github. This deletes the app deployment instance corresponding to that branch.

Commit to repo

A direct commit to your repo generates the three config files which then triggers the deployment workflow. Your app is deployed with the branch name suffix.

Disable branch previews

Only the chosen branch will be deployed and available at the base URL (no suffixes).


All the instances are provisioned with the same CPU and memory resources. If the branches cannot be provisioned within the scaling limits of the cluster, creation of new applications maybe limited. This leads to timeouts during deployment.


Here's a quick 5 minute video walkthrough of the branch preview feature.