Skip to main content

GitHub Actions templates for deploying code to Astro


The Astro GitHub integration can automatically deploy code from a GitHub repository to Astro without you needing to configure a GitHub action. In addition, the Astro UI shows Git metadata for each deploy on your Deployment information screen. See Deploy code with the Astro GitHub integration for setup steps.

GitHub Action templates use the Astronomer-maintained deploy-action, which is available in the GitHub Marketplace. This action automates the deploy process and includes additional features for more complex automation workflows. Specifically, the action can automatically:

  • Choose a deploy type based on the files that were changed in a commit. This allows you to use the same template for DAG deploys and image deploys.
  • Test DAGs as part of the deploy process and prevent deploying if any of the tests fail. These tests are defined in the tests directory of your Astro project.
  • Create a preview Deployment to test your code before deploying to production. A Deployment preview is an Astro Deployment that mirrors the configuration of an existing Deployment.

This means that the deploy-action triggers both image deploys and DAG deploys depending on the type of file changes that you made. If you committed changes only to DAG files, the action triggers a DAG deploy. If you committed changes to any other file, the action triggers an image deploy. See the Deploy Action README to learn more about using and customizing this action.

Read the following sections to choose the right template for your use case. If you have one Deployment and one environment on Astro, use the single branch implementation. If you have multiple Deployments that support development and production environments, use the multiple branch implementation. If your team builds custom Docker images, use the custom image implementation. If you do not have access to Astronomer's deploy-action, use the private network templates.

To learn more about CI/CD on Astro, see Choose a CI/CD strategy.


If you use GitHub Enterprise and cannot access the Astronomer Deploy Action, see Private network templates.


Each CI/CD template implementation might have additional requirements.


If you use a self-hosted runner to execute jobs from GitHub Actions, the Astro CLI's config.yaml file, which stores default deploy details, might be shared across your organization and hence multiple CI/CD pipelines. To reduce the risk of accidentally deploying to the wrong Deployment, ensure the following:

  • Add ASTRO_API_TOKEN to your repository and include a check in your GitHub workflow to verify that it exists.
  • Use Deployment API tokens, which are scoped only to one Deployment, instead of Workspace or Organization API tokens.
  • Specify deployment-id or deployment-name in your action. For example, astro deploy <deployment-id> or astro deploy -n <deployment-name>.
  • Add the command astro logout at the end of your workflow to ensure that your authentication token is cleared from the config.yaml file.


To automate code deploys to a single Deployment using GitHub Actions, complete the following setup in a Git-based repository that hosts an Astro project:

  1. Set the following as a GitHub secret:

    • ASTRO_API_TOKEN: The value for your Workspace or Organization API token.
  2. In your project repository, create a new YAML file in .github/workflows that includes the following configuration:

    name: Astronomer CI - Deploy code

    - main

    ## Sets Deployment API credentials as environment variables

    runs-on: ubuntu-latest
    - name: Deploy to Astro
    uses: astronomer/deploy-action@v0.4
    deployment-id: <your-deployment-id>

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.

Was this page helpful?

Sign up for Developer Updates

Get a summary of new Astro features once a month.

You can unsubscribe at any time.
By proceeding you agree to our Privacy Policy, our Website Terms and to receive emails from Astronomer.