> ## 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.

# Astro CI/CD templates for GitLab

Use the following CI/CD templates to automate deploys to Astro from a [GitLab](https://gitlab.com/) repository.

Read the following sections to choose the right template for your project. The templates for GitLab include the image deploy templates and dag deploy templates.

If you have one Deployment and one environment on Astro, use the [single branch implementation](#single-branch). If you have multiple Deployments that support development and production environments, use the [multiple branch implementation](#multiple-branch). If you want your CI/CD process to automatically decide which deploy strategy to choose, see [Dag deploy templates](#dag-deploy-templates).

To learn more about CI/CD on Astro, see [Choose a CI/CD strategy](/docs/astro/set-up-ci-cd).

## Prerequisites

* An [Astro project](/docs/cli/v1.43/develop-project#create-an-astro-project) hosted in a GitLab repository.
* An [Astro Deployment](/docs/astro/create-deployment).
* A [Deployment API token](/docs/astro/deployment-api-tokens), [Workspace API token](/docs/astro/workspace-api-tokens), or [Organization API token](/docs/astro/organization-api-tokens).

Each CI/CD template implementation might have additional requirements.

## Image deploy templates

<Tabs>
  <Tab title="Single branch" id="single-branch">
    Use this template to push code from a GitLab repository to Astro.

    1. Set the following [environment variables](https://docs.gitlab.com/ee/ci/variables/#for-a-project) in your GitLab project:

    * `ASTRO_API_TOKEN`: The value for your Workspace or Organization API token.
    * `DEPLOYMENT_ID`: The ID of your Astro Deployment. You can copy the **ID** from your Deployment's home page in the Astro UI.

    Astronomer recommends that you always [mask](https://docs.gitlab.com/ee/ci/variables/#mask-a-cicd-variable) your API token to prevent it from being accessible in plain text. You can also set the API token as an [external secret](https://docs.gitlab.com/ee/ci/secrets/index.html) for an extra layer of security.

    2. Go to **Build** > **Pipeline Editor** and commit the following:

    ```yaml title=".gitlab-ci.yml" wrap theme={null}
    astro_deploy:
      stage: deploy
      image: docker:latest
      services:
        - docker:dind

      variables:
        ASTRO_API_TOKEN: ${ASTRO_API_TOKEN}
        DEPLOYMENT_ID: ${DEPLOYMENT_ID}

      before_script:
        - apk add --update curl && rm -rf /var/cache/apk/*
        - apk add bash
      script:
        - (curl -sSL install.astronomer.io | bash -s)
        - astro deploy -f $DEPLOYMENT_ID
      only:
        - main
    ```
  </Tab>

  <Tab title="Multiple branch" id="multiple-branch">
    Use this template to push code to a development and a production Deployment in Astro based on your GitLab project's branch name.

    1. Set the following [environment variables](https://docs.gitlab.com/ee/ci/variables/#for-a-project) in your GitLab project:

    * `PROD_ASTRO_API_TOKEN`: The value of your production Workspace or Organization API token.
    * `PROD_DEPLOYMENT_ID`: The ID of your Astro Deployment. You can copy the **ID** from your production Deployment's page in the Astro UI.
    * `DEV_ASTRO_API_TOKEN`: The value of your development Workspace or Organization API token.
    * `DEV_DEPLOYMENT_ID`: The ID of your Astro Deployment. You can copy the **ID** from your development Deployment's page in the Astro UI.

    Astronomer recommends that you always [mask](https://docs.gitlab.com/ee/ci/variables/#mask-a-cicd-variable) your API token to prevent it from being accessible in plain text. You can also set the API token as an [external secret](https://docs.gitlab.com/ee/ci/secrets/index.html) for an extra layer of security.

    <Tip>When you create a CI/CD variable that will be used in multiple branches, you might want to [protect the variable](https://docs.gitlab.com/ee/ci/variables/#protect-a-cicd-variable) so that it can only be accessed from the relevant branches.</Tip>

    2. Go to the **Editor** option in your project's CI/CD section and commit the following:

    ```yaml title=".gitlab-ci.yml" expandable wrap theme={null}
    astro_deploy_dev:
      stage: deploy
      image: docker:latest
      services:
        - docker:dind
      variables:
        ASTRO_API_TOKEN: ${DEV_ASTRO_API_TOKEN}
        DEPLOYMENT_ID: ${DEV_DEPLOYMENT_ID}
      before_script:
        - apk add --update curl && rm -rf /var/cache/apk/*
        - apk add bash
      script:
        - (curl -sSL install.astronomer.io | bash -s)
        - astro deploy -f $DEPLOYMENT_ID
      only:
        - dev

    astro_deploy_prod:
      stage: deploy
      image: docker:latest
      services:
        - docker:dind
      variables:
        ASTRO_API_TOKEN: ${PROD_ASTRO_API_TOKEN}
        DEPLOYMENT_ID: ${PROD_DEPLOYMENT_ID}
      before_script:
        - apk add --update curl && rm -rf /var/cache/apk/*
        - apk add bash
        - apk add jq
      script:
        - (curl -sSL install.astronomer.io | bash -s)
        - astro deploy -f $DEPLOYMENT_ID
      only:
        - main
    ```
  </Tab>
</Tabs>

## Dag deploy templates

The dag deploy template uses the `--dags` flag in the Astro CLI to push dag changes to Astro. These CI/CD pipelines deploy your dags only when files in your `dags` folder are modified, and they deploy the rest of your Astro project as a Docker image when other files or directories are modified. For more information about the benefits of this workflow, see [Deploy dags only](/docs/astro/deploy-code).

<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.
</Info>

### Single branch implementation

Use this template to push code from a GitLab repository to Astro.

1. Set the following [environment variables](https://docs.gitlab.com/ee/ci/variables/#for-a-project) in your GitLab project:

* `ASTRO_API_TOKEN`: The value for your Workspace or Organization API token.
* `DEPLOYMENT_ID`: The ID of your Astro Deployment. You can copy the **ID** from your Deployment's page in the Astro UI.

Astronomer recommends that you always [mask](https://docs.gitlab.com/ee/ci/variables/#mask-a-cicd-variable) your API token to prevent it from being accessible in plain text. You can also set the API token as an [external secret](https://docs.gitlab.com/ee/ci/secrets/index.html) for an extra layer of security.

2. Go to the **Editor** option in your project's CI/CD section and commit the following:

```yaml title=".gitlab-ci.yml" expandable wrap theme={null}
astro_smart_deploy:
  stage: deploy
  image: docker:latest
  services:
    - docker:dind
  variables:
    ASTRO_API_TOKEN: ${ASTRO_API_TOKEN}
    DAG_FOLDER: "dags"
    DEPLOYMENT_ID: ${DEPLOYMENT_ID}
  before_script:
    - apk add --update curl && rm -rf /var/cache/apk/*
    - apk add git
    - apk add bash
  script:
    - (curl -sSL install.astronomer.io | bash -s)
    - files=$(git diff --name-only $(git rev-parse HEAD~1) -- .)
    - dags_only=1
    - echo "$DAG_FOLDER"
    - echo "$files"
    - for file in $files; do
    -   echo "$file"
    -   if [[ "$file" != "$DAG_FOLDER"* ]]; then
    -     echo "$file is not a dag, triggering a full image build"
    -     dags_only=0
    -     break
    -   else
    -     echo "just a dag"
    -   fi
    - done
    - if [[ $dags_only == 1 ]]; then
    -   echo "doing dag-only deploy"
    -   astro deploy --dags $DEPLOYMENT_ID
    - elif [[ $dags_only == 0 ]]; then
    -   echo "doing image deploy"
    -   astro deploy -f $DEPLOYMENT_ID
    - fi
  only:
    - main
```