Skip to main content

GitHub Actions templates for deploying code to Astro

tip

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.
  • Allows you to choose the type of code deploys used by the automation:
    • (Default) infer
    • image-and-dags
    • dags-only
    • dbt

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.

info

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

Deploy options​

The deploy-action includes several options for you to choose a specific type of code deploy for your CI/CD processes.

info

See the Deploy Action README to learn more about using and customizing this action, like creating a GitHub action that can support DAG and dbt deploys.

(Default) infer​

By default, the deploy-action uses infer, which allows it to determine the type of code deploy to use based on the types of files changed in a commit: DAG or Astro project. 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, or image-and-dags. This setting does not include dbt deploy types.

image-and-dags​

The image-and-dags option enables the Deploy Action to make a full project deploy, which includes both images and DAGs.

dags-only​

The dags-only deploy option enables the deploy action to deploy only the DAGs in your Astro project's dags directory to your Deployment.

dbt​

The dbt deploy option enables the Deploy Action to deploy dbt projects to Astro, when you provide the path to a directory in your GitHub repo that contains your dbt project.

Prerequisites​

Each CI/CD template implementation might have additional requirements.

warning

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.

Default deploy action​

By default, the deploy action uses the infer deploy type, which enables the action to determine whether to use either a dags-only deploy or an image-and-dags deploy, depending on the files you change.

info

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.

Setup​

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

    on:
      push:
        branches:
          - main

    env:
      ## Sets Deployment API credentials as environment variables
      ASTRO_API_TOKEN: ${{ secrets.ASTRO_API_TOKEN }}

    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
        - name: Deploy to Astro
          uses: astronomer/deploy-action@v0.9.0
          with:
            deployment-id: <your-deployment-id>

  3. (Optional) You can add optional configurations to customize your workflow. For example, if you add wake-on-deploy to your configuration, the Deploy Action wakes a hibernating Deployment before deploying code to it.

warning

Using wake-on-deploy takes precedence over any existing Deployment hibernation overrides that you configured through the Astro UI or config.yaml file.

dbt code deploys​

If you have a dbt project that you want to use with the deploy action for a GitHub action, you can choose to use either the dbt deploy on its own, or you can create GitHub actions that combine the infer action with a dbt deploy.

Setup​

Prerequisites​

  • The root folder name for the directory that contains your dbt project.

Implementation​

To automate code deploys to a single Deployment using GitHub Actions for a dbt project, 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 dbt code

    on:
      push:
        branches:
          - main

    env:
      ## Sets Deployment API credentials as environment variables
      ASTRO_API_TOKEN: ${{ secrets.ASTRO_API_TOKEN }}

    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
        - name: Deploy to Astro
          uses: astronomer/deploy-action@v0.9.0
          with:
                deployment-id: <deployment id>
                deploy-type: dbt
                root-folder: <dbt-root-folder>

  3. (Optional) You can add optional configurations to customize your workflow. For example, if you add wake-on-deploy to your configuration, the Deploy Action wakes a hibernating Deployment before deploying code to it.

warning

Using wake-on-deploy takes precedence over any existing Deployment hibernation overrides that you configured through the Astro UI or config.yaml file.

Was this page helpful?