> ## Documentation Index
> Fetch the complete documentation index at: https://astronomer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Actions templates for deploying code to preview Deployments on 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](/docs/astro/deploy-github-integration) for setup steps.</Tip>

The Astronomer [deploy action](https://github.com/astronomer/deploy-action/blob/main/README.md#deployment-preview-templates) includes several sub-actions that can be used together to create a complete [Deployment preview](/docs/astro/ci-cd-templates/preview-deployments) pipeline, a configuration that allows you to test your code changes in an ephemeral development Deployment before promoting your changes to a production Astro Deployment.

The Deployment preview templates use GitHub secrets to manage the credentials needed for GitHub to authenticate to Astro. You can specify the credentials for your [secrets backend](/docs/astro/secrets-backend) so that preview Deployments have access to secret Airflow variables or connections during tests. See [Deployment preview template with secrets backend implementation](#deployment-preview-template-with-secrets-backend-implementation).

Deployment preview templates use Astronomer's [`deploy-action`](/docs/astro/ci-cd-templates/template-overview) to automates the deploy process, meaning it can selectively deploy parts of your project based on which files you changed. See [Standard deploy templates](/docs/astro/ci-cd-templates/template-overview) for more information about the `deploy-action`.

<Note>Each template installs the Astro CLI with [`setup-astro-cli`](https://github.com/astronomer/setup-astro-cli) before `deploy-action` runs. Astronomer recommends installing the CLI in a separate step so that you can pin or upgrade the CLI version independently of the action, including with Dependabot, and reuse a single installation across multiple deploy steps. To pin a version, set the `version` input, for example `version: "1.40.1"`. If you omit this step, `deploy-action` installs the latest version of the Astro CLI itself.</Note>

## Prerequisites

* An [Astro project](/docs/cli/v1.43/develop-project#create-an-astro-project) hosted in a GitHub repository.
* An [Astro Deployment](/docs/astro/create-deployment).
* A [Workspace API token](/docs/astro/workspace-api-tokens) or [Organization API token](/docs/astro/organization-api-tokens).
* Access to [GitHub Actions](https://github.com/features/actions).

Specific templates might have additional requirements.

<Warning>Creating preview Deployments for Deployments that use a private image registry is currently unsupported.</Warning>

<Warning>
  If you use a [self-hosted runner](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) 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.
  * 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.
</Warning>

## Deployment preview template

The standard Deployment preview template uses GitHub secrets and an Astro Workspace or Organization API token to create a preview Deployment whenever you create a new feature branch off of your main branch.

### Setup

1. Copy and save the Deployment ID for your Astro Deployment.

<Info>Replace `<main-deployment-id>` with this Deployment ID in all the scripts created in the following steps. Even though some scripts take action on the preview Deployment, the `<main-deployment-id>` should be same for each script.</Info>

2. Set the following [GitHub secret](https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository) in the repository hosting your Astro project:

* Key: `ASTRO_API_TOKEN`
* Secret: `<your-token>`

3. In your project repository, create a new YAML file in `.github/workflows` named `deploy-to-preview.yml` that includes the following configuration:

```yaml title="deploy-to-preview.yml" wrap theme={null}
name: Astronomer CI - Deploy code to preview

on:
  pull_request:
    branches:
      - main

env:
  ## Set your API token as a GitHub secret
  ASTRO_API_TOKEN: ${{ secrets.ASTRO_API_TOKEN }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Install Astro CLI
      uses: astronomer/setup-astro-cli@v0.0.1
    - name: Create preview Deployment
      uses: astronomer/deploy-action@v0.14.0
      continue-on-error: true  # Create action fails if deploy preview already exist, which is expected for subsequent commits in the PR
      with:
        action: create-deployment-preview
        deployment-id: <main-deployment-id>
        wait-time: 10m # Max wait time for the preview deployment to be completed by the deploy action. The workflow will fail if the deployment fails to create within give time period.
    - name: Deploy code to preview
      uses: astronomer/deploy-action@v0.14.0
      with:
        action: deploy-deployment-preview
        deployment-id: <main-deployment-id>
```

4. In the same folder, create a new YAML file named `delete-preview-deployment.yml` that includes the following configuration:

```yaml title="delete-preview-deployment.yml" wrap theme={null}
name: Astronomer CI - Delete Preview Deployment

on:
  delete:
    branches:
      - "**"
env:
  ## Set your API token as a GitHub secret
  ASTRO_API_TOKEN: ${{ secrets.ASTRO_API_TOKEN }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Install Astro CLI
      uses: astronomer/setup-astro-cli@v0.0.1
    - name: Delete preview Deployment
      uses: astronomer/deploy-action@v0.14.0
      with:
        action: delete-deployment-preview
        deployment-id: <main-deployment-id>
```

5. In the same folder, create a new YAML file named `deploy-to-main-deployment.yml` that includes the following configuration:

```yaml title="deploy-to-main-deployment.yml" wrap theme={null}
name: Astronomer CI - Deploy code to main Deployment

on:
  push:
    branches:
      - main

env:
  ## Set your API token as a GitHub secret
  ASTRO_API_TOKEN: ${{ secrets.ASTRO_API_TOKEN }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Install Astro CLI
      uses: astronomer/setup-astro-cli@v0.0.1
    - name: Deploy code to main Deployment
      uses: astronomer/deploy-action@v0.14.0
      with:
        deployment-id: <main-deployment-id>
```

6. (Optional) You can add [optional configurations](https://github.com/astronomer/deploy-action/blob/main/README.md#configuration-options) to customize your workflow.

All three workflow files must have the same Deployment ID specified. The actions use this Deployment ID to create and delete preview Deployments based on your main Deployment.

## Deployment preview template with secrets backend implementation

If you use a [secrets backend](/docs/astro/secrets-backend) to manage Airflow objects such as variables and connections, you can configure your action to grant preview Deployments access to your secrets backend. This means that dags in the preview Deployment can access your secret Airflow objects for testing purposes.

This template makes use of the `AIRFLOW__SECRETS__BACKEND_KWARGS` environment variable to store information and credentials for your secrets backend.

### Prerequisites

* A [secrets backend](/docs/astro/secrets-backend), such as Hashicorp Vault.

### Setup

1. Copy and save the Deployment ID for your Astro deployment.

<Info>Replace `<main-deployment-id>` with this Deployment ID in all the scripts created in the following steps. Even though some scripts take action on the preview Deployment, the `<main-deployment-id>` should be same for each script.</Info>

2. Set the following [GitHub secrets](https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository) in the repository hosting your Astro project. This includes your Astro API Token, so that GitHub has permissions to deploy code to your Deployments or Workspaces, and your secrets backend information stored in `AIRFLOW__SECRETS__BACKEND_KWARGS`. See [Configure a secrets backend](/docs/astro/secrets-backend) for more information about configuring your secrets backend as an environment variable.

* **Key 1**: `ASTRO_API_TOKEN`
* **Secret 1**: `<your-token>`
* **Key 2**: `AIRFLOW__SECRETS__BACKEND_KWARGS`
* **Secret 2**: `<your-kwargs>`

3. In your project repository, create a new YAML file in `.github/workflows` named `create-deployment-preview.yml` that includes the following configuration.

```yaml title="create-deployment-preview.yml" wrap theme={null}
name: Astronomer CI - Create preview Deployment with Secrets Backend

on:
  create:
    branches:
      - "**"

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

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Install Astro CLI
      uses: astronomer/setup-astro-cli@v0.0.1
    - name: Create Deployment Preview
      uses: astronomer/deploy-action@v0.14.0
      id: create-dep-prev
      with:
        action: create-deployment-preview
        deployment-name: "test"
    - name: Create Secret Variables
      run: |
        astro deployment variable update --deployment-id ${{ steps.create-dep-prev.outputs.preview-id }} AIRFLOW__SECRETS__BACKEND_KWARGS=${{ secrets.AIRFLOW__SECRETS__BACKEND_KWARGS }} --secret
```

4. In the same folder, create a new YAML file named `deploy-to-preview.yml` that includes the following configuration:

```yaml title="deploy-to-preview.yml" wrap theme={null}
name: Astronomer CI - Deploy code to preview

on:
  pull_request:
    branches:
      - main

env:
  ## Set your API token as a GitHub secret
  ASTRO_API_TOKEN: ${{ secrets.ASTRO_API_TOKEN }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Install Astro CLI
      uses: astronomer/setup-astro-cli@v0.0.1
    - name: Deploy code to preview
      uses: astronomer/deploy-action@v0.14.0
      with:
        action: deploy-deployment-preview
        deployment-id: <main-deployment-id>
```

5. In the same folder, create a new YAML file named `delete-preview-deployment.yml` that includes the following configuration:

```yaml title="delete-preview-deployment.yml" wrap theme={null}
name: Astronomer CI - Delete Preview Deployment

on:
  delete:
    branches:
      - "**"
env:
  ## Set your API token as a GitHub secret
  ASTRO_API_TOKEN: ${{ secrets.ASTRO_API_TOKEN }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Install Astro CLI
      uses: astronomer/setup-astro-cli@v0.0.1
    - name: Delete preview Deployment
      uses: astronomer/deploy-action@v0.14.0
      with:
        action: delete-deployment-preview
        deployment-id: <main-deployment-id>
```

6. In the same folder, create a new YAML file named `deploy-to-main-deployment.yml` that includes the following configuration:

```yaml title="deploy-to-main-deployment.yml" wrap theme={null}
name: Astronomer CI - Deploy code to main Deployment

on:
  push:
    branches:
      - main

env:
  ## Set your API token as a GitHub secret
  ASTRO_API_TOKEN: ${{ secrets.ASTRO_API_TOKEN }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - name: Install Astro CLI
      uses: astronomer/setup-astro-cli@v0.0.1
    - name: Deploy code to main Deployment
      uses: astronomer/deploy-action@v0.14.0
      with:
        deployment-id: <main-deployment-id>
```

All four workflow files must have the same Deployment ID specified. The actions use this Deployment ID to create and delete preview Deployments based on your main Deployment.