Ask AI

Using Branch Deployments with Gitlab CI/CD#

This guide is applicable to Dagster+.

In this guide, we'll walk you through setting up Branch Deployments with Gitlab CI/CD.

Using this approach to branch deployments may be a good fit if:

  • You use Gitlab for version control
  • You want Dagster to fully automate Branch Deployments

If you don't use Gitlab for version control or want full control over your setup, check out the Branch deployments with the dagster-cloud CLI guide.


To complete the steps in this guide, you'll need:

  • Organization Admin permissions in Dagster+
  • The ability to run a new agent in your infrastructure. This isn't required if you're using Serverless deployment.
  • The ability to configure Gitlab CI/CD for your project. This isn't required if you used the Dagster+ Gitlab app to connect your project as a code location.

Step 1: Generate a Dagster+ agent token#

In this step, you'll generate a token for the Dagster+ agent. The Dagster+ agent will use this to authenticate to the agent API.

  1. Sign in to your Dagster+ instance.
  2. Click the user menu (your icon) > Organization Settings.
  3. In the Organization Settings page, click the Tokens tab.
  4. Click the + Create agent token button.
  5. After the token has been created, click Reveal token.

Keep the token somewhere handy - you'll need it to complete the setup.

Step 2: Create and configure an agent#

If using Serverless deployment, this step isn't required.

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.

Using the tabs, select your agent type to view instructions.

Step 3: Add Gitlab CI/CD script to your project#

If you used the Gitlab app to add the project as a code location, this step isn't required. Skip to the next step.

In this step, you'll add the required Gitlab CI config file to your Gitlab project. The file can be found in our CI/CD workflow repository or Serverless quickstart repository, depending on the agent you are using.

Copy the following files to your project (the linked files are shown for Hybrid repos, there are equivalents for Serverless repos).

In the next step, you'll modify these files to work with your Dagster+ setup.

Step 4: Configure the Gitlab project#

In this section, you'll:

  1. Add the agent registry to dagster_cloud.yaml
  2. Configure Gitlab CI/CD variables
  3. Update Gitlab CI/CD script
  4. Verify CI/CD pipeline runs

Step 4.1: Add the agent registry to dagster_cloud.yaml#

If you're using Serverless deployment, this step isn't required. Skip to the next step.

In the dagster_cloud.yaml file, replace build.registry with the registry used by the agent you created in Step 2.

For example:

# dagster_cloud.yaml

  - location_name: example_location
      directory: ./example_location

Step 4.2: Configure Gitlab CI/CD variables#

If you used the Gitlab app to add the project as a code location, this step isn't required.

Want to use secrets in your Dagster code? Check out the Dagster+ environment variables and secrets guide for more info.
  1. In your project, click the Settings tab.
  2. In the CI/CD section of the sidebar, expand Variables.
  3. Click Add variable.
  4. In the Key field, enter the name of the variable. For example, API_TOKEN
  5. In the Value field, paste the value of the variable.
  6. Click Add variable.

For Hybrid deployments, repeat steps 3-6 for each of the secrets required for your registry type:

  • DAGSTER_CLOUD_API_TOKEN - The Dagster+ agent token you created in Step 1
  • DAGSTER_CLOUD_URL - Your Dagster+ base URL (e.g.

Step 4.3: Update Gitlab CI/CD script#

If you're using Serverless deployment, this step isn't required. Skip to the next step.

In this step, you'll update the Gitlab CI/CD config to set up Docker registry access.

In the .gitlab-ci.yml file, uncomment the step associated with your registry. For example, for the Gitlab container registry, you'd uncomment the following portion of the .gitlab-ci.yml file:

    # For Gitlab Container Registry
    - echo $CI_JOB_TOKEN | docker login --username $CI_REGISTRY_USER --password-stdin $REGISTRY_URL

Save and commit the files to the project.

Step 4.4: Verify pipeline runs#

The last step is to verify that the Gitlab pipeline runs successfully.

  1. On the project page, click the CI/CD tab.

  2. In the list of pipelines, locate the latest branch deployment run. For example:

    A successful run for a Branch Deployment Action

If the run finished successfully, that's it!

Step 5: Access the branch deployment#

Now that Branch Deployments are configured, you can check out the preview in Dagster+, by accessing the branch deployment from the deployment switcher:

Highlighted branch deployment in the Dagster+ deployment switcher