Using Branch Deployments with the dagster-cloud CLI#
This guide is applicable to Dagster Cloud.
In this guide, we'll walk you through setting up Branch Deployments with a general continuous integration (CI) or git platform, using the dagster-cloud CLI.
Using this approach to branch deployments may be a good fit if:
You don't use GitHub for version control
You use an alternate CI platform
You want full control over Branch Deployment configuration
While you can use your existing production agent, we recommend creating a dedicated branch deployment agent. This ensures that your production instance isn't negatively impacted by the workload associated with branch deployments.
AMAZON ECS AGENTS
Deploy an ECS agent to serve your branch deployments. Follow the ECS agent setup guide, making sure to set the Enable Branch Deployments parameter if using the CloudFormation template. If you are running an existing agent, follow the upgrade guide to ensure your template is up-to-date. Then, turn on the Enable Branch Deployments parameter.
Step 3: Create a branch deployment using the dagster-cloud CLI#
Next, you'll create a branch deployment using the dagster-cloud CLI. When the state of a branch or merge request is updated, Dagster Cloud first expects these steps to occur:
The new image is pushed to a Docker registry accessible to your agent. Note: The following examples assume the registry URL and image tag are stored in the LOCATION_REGISTRY_URL and IMAGE_TAG environment variables, respectively.
After the above has occurred:
Use the dagster-cloud CLI to create a branch deployment associated with the branch, as follows:
BRANCH_DEPLOYMENT_NAME=$(
dagster-cloud branch-deployment create-or-update \
--organization $ORGANIZATION_NAME \
--api-token $DAGSTER_CLOUD_API_TOKEN \# Agent token from Step 1
--git-repo-name $REPOSITORY_NAME \# Git repository name
--branch-name $BRANCH_NAME \# Git branch name
--commit-hash $COMMIT_SHA \# Latest commit SHA on the branch
--timestamp $TIMESTAMP # UTC unixtime timestamp of the latest commit)
One or more additional parameters can optionally be supplied to the create-or-update command to enhance the Branch Deployments UI in Dagster Cloud:
BRANCH_DEPLOYMENT_NAME=$(
dagster-cloud branch-deployment create-or-update \
--organization $ORGANIZATION_NAME \
--api-token $DAGSTER_CLOUD_API_TOKEN \
--git-repo-name $REPOSITORY_NAME \
--branch-name $BRANCH_NAME \
--commit-hash $COMMIT_SHA \
--timestamp $TIMESTAMP
--code-review-url $PR_URL \# URL to review the given changes, e.g.# Pull Request or Merge Request
--code-review-id $INPUT_PR \# Alphanumeric ID for the given set of changes
--pull-request-status $PR_STATUS \# A status, one of `OPEN`, `CLOSED`,# or `MERGED`, that describes the set of changes
--commit-message $MESSAGE \# The message associated with the latest commit
--author-name $NAME \# A display name for the latest commit's author
--author-email $EMAIL \# An email for the latest commit's author
--author-avatar-url $AVATAR_URL # An avatar URL for the latest commit's author)
If the command is being executed from the context of the git repository, you can alternatively pull this metadata from the repository itself: