> ## 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 Jenkins
Use the following CI/CD templates to automate deploying Apache Airflow dags from a Git repository to Astro with [Jenkins](https://www.jenkins.io/).
The following templates for Jenkins are available:
* [Image deploy templates](/docs/astro/ci-cd-templates/template-overview#image-deploy-templates)
* [dag deploy templates](/docs/astro/ci-cd-templates/template-overview#dag-deploy-templates)
Each template type supports multiple implementations. If you have one Deployment and one environment on Astro, use the [single branch implementation](/docs/astro/ci-cd-templates/template-overview#single-branch-implementation). If you have multiple Deployments that support development and production environments, use the [multiple branch implementation](/docs/astro/ci-cd-templates/template-overview#multiple-branch-implementation). If your team builds custom Docker images, use the [custom image implementation](/docs/astro/ci-cd-templates/template-overview#custom-image-implementation).
For more information on each template or to configure your own, see [Template overview](/docs/astro/ci-cd-templates/template-overview). 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 Git repository that Jenkins can access.
* 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).
* Access to [Jenkins](https://www.jenkins.io/).
Each CI/CD template implementation might have additional requirements.
## Image deploy templates
To automate code deploys to a single Deployment using [Jenkins](https://www.jenkins.io/), complete the following setup in a Git-based repository hosting an Astro project:
1. In your Jenkins pipeline configuration, add the following environment variables:
* `ASTRO_API_TOKEN`: The value for your Workspace or Organization API token.
* `ASTRONOMER_DEPLOYMENT_ID`: The Deployment ID of your production deployment
To set environment variables in Jenkins, on the Jenkins Dashboard go to **Manage Jenkins** > **Configure System** > **Global Properties** > **Environment Variables** > **Add**. To see Jenkins documentation on environment variables click [here](https://www.jenkins.io/doc/pipeline/tour/environment/)
Be sure to set the value for your API token as secret.
2. At the root of your Astro Git repository, add a [Jenkinsfile](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/) that includes the following script:
```groovy title="Jenkinsfile" wrap theme={null}
pipeline {
agent any
stages {
stage('Deploy to Astronomer') {
when {
expression {
return env.GIT_BRANCH == "origin/main"
}
}
steps {
checkout scm
sh '''
curl -LJO https://github.com/astronomer/astro-cli/releases/download/v1.38.0/astro_1.38.0_linux_amd64.tar.gz
tar -zxvf astro_1.38.0_linux_amd64.tar.gz astro && rm astro_1.38.0_linux_amd64.tar.gz
./astro deploy env.ASTRONOMER_DEPLOYMENT_ID
'''
}
}
}
post {
always {
cleanWs()
}
}
}
```
This `Jenkinsfile` triggers a code push to Astro every time a commit or pull request is merged to the `main` branch of your repository.
To automate code deploys across multiple Deployments using [Jenkins](https://www.jenkins.io/), complete the following setup in a Git-based repository hosting an Astro project:
1. In Jenkins, add the following environment variables:
* `PROD_ASTRO_API_TOKEN`: The value for your production Workspace or Organization API token.
* `PROD_DEPLOYMENT_ID`: The Deployment ID of your production Deployment
* `DEV_ASTRO_API_TOKEN`: The value for your development Workspace or Organization API token.
* `DEV_DEPLOYMENT_ID`: The Deployment ID of your development Deployment
To set environment variables in Jenkins, on the Jenkins Dashboard go to **Manage Jenkins** > **Configure System** > **Global Properties** > **Environment Variables** > **Add**. To see Jenkins documentation on environment variables click [here](https://www.jenkins.io/doc/pipeline/tour/environment/)
Be sure to set the values for your API credentials as secret.
2. At the root of your Git repository, add a [`Jenkinsfile`](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/) that includes the following script:
```groovy title="Jenkinsfile" expandable wrap theme={null}
pipeline {
agent any
stages {
stage('Set Environment Variables') {
steps {
script {
if (env.GIT_BRANCH == 'main') {
echo "The git branch is ${env.GIT_BRANCH}";
env.ASTRO_API_TOKEN = env.PROD_ASTRO_API_TOKEN;
env.ASTRONOMER_DEPLOYMENT_ID = env.PROD_DEPLOYMENT_ID;
} else if (env.GIT_BRANCH == 'dev') {
echo "The git branch is ${env.GIT_BRANCH}";
env.ASTRO_API_TOKEN = env.DEV_ASTRO_API_TOKEN;
env.ASTRONOMER_DEPLOYMENT_ID = env.DEV_DEPLOYMENT_ID;
} else {
echo "This git branch ${env.GIT_BRANCH} is not configured in this pipeline."
}
}
}
}
stage('Deploy to Astronomer') {
steps {
checkout scm
sh '''
curl -LJO https://github.com/astronomer/astro-cli/releases/download/v1.38.0/astro_1.38.0_linux_amd64.tar.gz
tar -zxvf astro_1.38.0_linux_amd64.tar.gz astro && rm astro_1.38.0_linux_amd64.tar.gz
./astro deploy env.ASTRONOMER_DEPLOYMENT_ID
'''
}
}
}
post {
always {
cleanWs()
}
}
}
```
This `Jenkinsfile` triggers a code push to an Astro Deployment every time a commit or pull request is merged to the `dev` or `main` branch of your repository.
If your Astro project requires additional build-time arguments to build an image, you need to define these build arguments using Docker's [`build-push-action`](https://github.com/docker/build-push-action).
#### Configuration requirements
* An Astro project that requires additional build-time arguments to build the Runtime image.
1. In your Jenkins pipeline configuration, add the following environment variables:
* `ASTRO_API_TOKEN`: The value for your Workspace or Organization API token.
* `ASTRONOMER_DEPLOYMENT_ID`: The Deployment ID of your production deployment
To set environment variables in Jenkins, on the Jenkins Dashboard go to **Manage Jenkins** > **Configure System** > **Global Properties** > **Environment Variables** > **Add**. To see Jenkins documentation on environment variables click [here](https://www.jenkins.io/doc/pipeline/tour/environment/)
Be sure to set the value for your API token as secret.
2. At the root of your Astro Git repository, add a [Jenkinsfile](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/) that includes the following script:
```groovy title="Jenkinsfile" wrap theme={null}
pipeline {
agent any
stages {
stage('Deploy to Astronomer') {
when {
expression {
return env.GIT_BRANCH == "origin/main"
}
}
steps {
checkout scm
sh '''
export astro_id=$(date +%Y%m%d%H%M%S)
docker build -f Dockerfile --progress=plain --build-arg -t $astro_id .
curl -LJO https://github.com/astronomer/astro-cli/releases/download/v1.37.0/astro_1.37.0_linux_amd64.tar.gz
tar -zxvf astro_1.37.0_linux_amd64.tar.gz astro && rm astro_1.37.0_linux_amd64.tar.gz
./astro deploy env.ASTRONOMER_DEPLOYMENT_ID --image-name $astro_id
'''
}
}
}
post {
always {
cleanWs()
}
}
}
```
This `Jenkinsfile` triggers a code push to Astro every time a commit or pull request is merged to the `main` branch of your repository.
## 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-dags).
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.
### Single branch implementation
Use the following template to implement dag-only deploys to a single Deployment using Jenkins.
1. In your Jenkins pipeline configuration, add the following parameters:
* `ASTRO_API_TOKEN`: The value for your Workspace or Organization API token.
* `ASTRONOMER_DEPLOYMENT_ID`: The Deployment ID of your production deployment
Be sure to set the values for your API token as secret.
2. At the root of your Git repository, add a [`Jenkinsfile`](https://www.jenkins.io/doc/book/pipeline/jenkinsfile/) that includes the following script:
```groovy title="Jenkinsfile" expandable wrap theme={null}
pipeline {
agent any
stages {
stage('Dag Only Deploy to Astronomer') {
when {
expression {
return env.GIT_BRANCH == "origin/main"
}
}
steps {
checkout scm
sh '''
curl -LJO https://github.com/astronomer/astro-cli/releases/download/v1.38.0/astro_1.38.0_linux_amd64.tar.gz
tar -zxvf astro_1.38.0_linux_amd64.tar.gz astro && rm astro_1.38.0_linux_amd64.tar.gz
files=($(git diff-tree HEAD --name-only --no-commit-id))
find="dags"
if [[ ${files[*]} =~ (^|[[:space:]])"$find"($|[[:space:]]) && ${#files[@]} -eq 1 ]]; then
./astro deploy env.ASTRONOMER_DEPLOYMENT_ID --dags;
else
./astro deploy env.ASTRONOMER_DEPLOYMENT_ID;
fi
'''
}
}
}
post {
always {
cleanWs()
}
}
}
```