Skip to main content
Astronomer CI/CD templates are customizable, pre-built code samples that help you configure automated workflows with popular CI/CD tools, such as GitHub Actions or Jenkins. Use the templates to create a workflow that automates deploying code to Astro according to your team’s CI/CD requirements and strategy. Template types differ based on the deploy method they use and how many branches or environments they require. This document contains information about the following template types:
  • Dag deploy templates that use the dag-only deploy feature in Astro and either deploy dags or your entire Astro project depending on the files that you update.
  • dbt deploy templates that use the dbt deploy feature in Astro to push dbt code from your specified dbt project directory, by default /dbt, to make the code accessible in your Deployment.
  • Image deploy templates that build a Docker image and push it to Astro whenever you update any file in your Astro project, including your dag directory.
  • Preview Deployment templates that automatically create and delete Deployments when you create or delete a feature branch from your main Astro project branch.
Astronomer maintains a dedicated guide with templates for select CI/CD tools. Most guides include image based templates for a single-branch implementation. Astronomer recommends reconfiguring the templates to work with your own directory structures, tools, and processes. If you’re interested in documentation for a CI/CD tool or template type that does not exist, configure your own or contact Astronomer support. To learn more about single-branch and multiple-branch implementations and decide which template is right for you, see Choose a CI/CD strategy.

​
Implementation options

CI/CD templates support different implementations based on how many branches and Astro Deployments your team maintains. Choose the implementation that matches your branching strategy, then apply it with one of the deploy templates described in the following sections. For a detailed comparison of environment and repository strategies, see Develop a CI/CD workflow.

​
Single-branch implementation

A single-branch implementation uses one permanent branch, such as main, that deploys to a single Astro Deployment. Use this implementation when you have one Deployment and one environment on Astro. See Single environment.

​
Multiple-branch implementation

A multiple-branch implementation uses multiple permanent branches that each deploy to a separate Astro Deployment, such as a dev branch for development and a main branch for production. Use this implementation when you maintain multiple Deployments that support development and production environments. See Multiple environments.

​
Custom image implementation

A custom image implementation builds a custom Docker image and deploys it to Astro. Use this implementation when your team builds custom Docker images, for example to install additional dependencies or apply custom build logic. Build the image for the linux/amd64 platform. Astro rejects images built for any other platform when you deploy them.

​
Dag deploy templates

Dag deploy templates check the changes in your Astro project and trigger either a dag deploy or image deploy based on the files changed, allowing for faster deploys. This template deploys your dags when only the files in your dags folder are modified, and it deploys the rest of your Astro project as a Docker image when any other files or directories are modified. To learn more about the benefits of this workflow, see Deploy dags. CI/CD templates that use the dag deploy workflow:
  • Require that each Deployment have the dag-only deploy feature enabled. See Enable/disable dag-only deploys on a Deployment.
  • Use a Deployment API token, Workspace API token, or Organization API token. This value must be set using the ASTRO_API_TOKEN environment variable.
  • Install the latest version of the Astro CLI.
  • Trigger the following Astro CLI commands depending on which files were updated by the commit:
    • If only dag files in the dags folder have changed, run astro deploy --dags. This pushes your dags folder to your Deployment.
    • If any file not in the dags folder has changed, run astro deploy. This triggers two subprocesses. One that creates a Docker image for your Astro project, authenticates to Astro using your Deployment API token, and pushes the image to your Deployment. A second that pushes your dags folder to your Deployment.
If you stage multiple commits to dag files and push them all at once to your remote branch, the template only deploys dag code changes from the most recent commit. It will miss any code changes made in previous commits.To avoid this, either push commits individually or configure your repository to Squash commits for pull requests that merge multiple commits simultaneously.
This process is equivalent to the following shell script:

​
Image deploy templates

Image based templates build a Docker image and push it to Astro whenever you update any file in your Astro project. This type of template works well for development workflows that include complex Docker customization or logic. CI/CD templates that use image based workflows:
  • Use a Deployment API token, Workspace API token or Organization API token. This value must be set using the ASTRO_API_TOKEN environment variable.
  • Install the latest version of the Astro CLI.
  • Run the astro deploy command. This creates a Docker image for your Astro project, authenticates to Astro using your Deployment API token, and pushes the image to your Deployment.
This is equivalent to running the following shell script:

​
dbt deploy templates

dbt deploy templates use dbt deploy to deploy just your dbt code to your Astro project, allowing for faster deploys. Or, it uses the Deploy Action with GitHub Actions to deploy dbt code. These templates deploy your dbt code when only the files in your dbt project folder, by default /dbt, are modified. CI/CD templates that use image based workflows:
  • Use a Deployment API token, Workspace API token or Organization API token. This value must be set using the ASTRO_API_TOKEN environment variable.
  • Install the latest version of the Astro CLI.
  • Run the astro dbt deploy command from your dbt project directory. This bundles all files in your dbt project and pushes them to Astro, where they are mounted on your Airflow containers so that your dags can access them.
This is equivalent to running the following shell script from your dbt directory:

​
Preview Deployment templates

Preview Deployment templates automate creating and deleting Deployments based on feature branches in your Git repository. A CI/CD workflow creates a preview Deployment when you create a feature branch and deletes it when you delete the branch. Use preview Deployments to test a small set of dags on Astro before you promote them to a base, production Deployment.