astro deploy
The behavior and format of this command differs depending on what Astronomer product you're using. Use the following tabs to change between product contexts.
- Astro
- Software
Deploy code to a Deployment on Astro.
This command bundles all files in your Astro project and pushes them to Astro. Before completing the process, it tests your DAGs in your Astro project for parse errors. If this test fails, the deploy to Astro will also fail. This is the same test which runs locally with astro dev parse.
When you run astro deploy, the CLI prompts you to select from a list of all Deployments that you can access across Workspaces. To bypass this prompt, you can also specify a Deployment ID in the command. To retrieve a Deployment ID, open your Deployment in the Astro UI and copy the value in the ID section of the Deployment page. You can also run astro deployment list to find a Deployment ID or name.
For teams operating at scale, this command can be automated with a CI/CD pipeline by using Deployment API tokens in the request. When ASTRO_API_TOKEN is specified as OS-level environment variables on your local machine or in a CI tool, astro deploy <deployment-id> can be run without requiring user authentication.
To skip the parsing process before deploys, complete one of the following setups:
- Add
skip_parse: trueto.astro/config.yamlin your Astro project. - Add
ASTRONOMER_SKIP_PARSE=trueas an environment variable to your local environment or CI/CD pipeline.
Usage
astro deploy <options>
Options
| Option | Description | Possible Values |
|---|---|---|
<deployment-id> | Specifies the Deployment to deploy to and bypasses the Deployment selection prompt | Any valid Deployment ID |
--build-secrets | Run docker build --secret to mount a secret value to your Docker image. | id=<your-secret-id>, src=<path-to-secret> . See Docker documentation. |
--description | A description for your code deploy. Descriptions appear in the Astro UI in your Deployment's Deploy History | None |
-d, --dags | Deploy only your dags directory. See DAG-only deploys | None |
-e, --env | Location of the file containing environment variables for pytests. By default, this is .env. | Any valid filepath to an .env file |
-f, --force | Force deploy even if your project contains parse errors or uncommitted changes. Parse tests are defined in .astro/test_dag_integrity_default.py. | None |
-i, --image-name | The name of a pre-built custom Docker image to use with your project. The image must be available from a Docker registry hosted on your local machine | A valid name for a pre-built Docker image based on Astro Runtime |
--image | If you have DAGs-only deploys enabled, use this flag to deploy only your Astro project image. When you use this option, your dags folder is not deployed to Astro | None |
-n, --deployment-name | The name of the Deployment to deploy to. Use as an alternative to <deployment-id>. | Any valid Deployment name |
-p, --prompt | Force the Deployment selection prompt even if a Deployment ID is specified | None |
--pytest | Deploy code to Astro only if the pytests are passed. By default the pytests are read from the tests directory. | None |
-s, --save | Save the current Deployment and working directory combination for future deploys. | None |
-t, --test | The filepath to an alternative pytest file or directory. | Valid filepath within your Astro project |
-w, --wait | Wait for the Deployment to become healthy before completing the command. | None |
--workspace-id <string> | In the prompt to select a Deployment, only show Deployments within this Workspace. | Any valid Workspace ID |
Examples
To deploy directly to a specific Deployment:
astro deploy ckvvfp9tf509941drl4vela81n
To configure the Astro CLI to use a given Deployment and directory as a default for future deploys:
astro deploy ckvvfp9tf509941drl4vela81n --save
To use a custom Docker image from your local Docker registry to build your Astro project:
astro deploy --image-name your-custom-runtime-image
To deploy only DAGs from your Astro project to a specific Deployment:
astro deploy ckvvfp9tf509941drl4vela81n --dags
Deploy code to a Deployment on Astronomer Software.
This command bundles all files in your Astro project and pushes them to Astronomer Software.
When you run astro deploy, you'll be prompted to select from a list of all Deployments that you can access in all Workspaces. To bypass this prompt, you can specify a Deployment ID in the command. To retrieve a Deployment ID, go to your Deployment's information page in the Astro UI and copy the value after the last / in the URL. You can also run astro deployment list to retrieve a Deployment ID .
Options
| Option | Description | Possible Values |
|---|---|---|
--build-secrets | Run docker build --secret to mount a secret value to your Docker image. | id=<your-secret-id>, src=<path-to-secret> . See Docker documentation. |
--description <string> | Improve traceability by attaching a description to a code deploy. If you don't provide a description, the system automatically assigns a default description based on the deploy type. | Any string surrounded by quotations |
-d, --dags | Deploy only your dags directory. Works only if DAG-only deploys are enabled for the Deployment. | None |
<deployment-id> | Specifies the Deployment to deploy to and bypasses the Deployment selection prompt. Required for DAG only deploys. | Any valid Deployment ID |
-f,--force | Force deploy even if your project contains errors or uncommitted changes | None |
-i, --image-name | The name of a pre-built custom Docker image to use with your project. The image must be available on your local machine. If specified, building the image is skipped. | A valid name for a pre-built Docker image based on Astro Runtime |
--image | Use this flag to deploy only your Astro project image. When you use this option, your dags folder is not deployed to Astro. This flag only works for DAG-only, Git-sync-based and NFS-based Deployments. | None |
--no-cache | Do not use any images from the container engine's cache when building your project | None |
-p,--prompt | Force the Deployment selection prompt even if a Deployment ID is specified | None |
--remote | Directly point the deployment to the remote image and skip pushing the image, if --image-name is passed. | None |
--runtime-version | Specify Runtime version of your image, if --image-name is passed. | Valid Runtime version |
-s,--save | Save the current Deployment and working directory combination for future deploys | None |
--workspace-id <string> | In the prompt to select a Deployment, only show Deployments within this Workspace | Any valid Workspace ID |
Examples
# List of Deployments appears
$ astro deploy
# Deploy directly to a specific Deployment
$ astro deploy ckvvfp9tf509941drl4vela81n
# The CLI automatically selects this Deployment for your Astro project
$ astro deploy ckvvfp9tf509941drl4vela81n --save
# Deploy an image from my private registry without first building it/putting in on my local computer
$ astro deploy --image-name your-custom-runtime-image --remote --runtime-version=rt_version
The following error can sometimes occur when the CLI tries to build your Astro Runtime image using Podman:
WARN[0010] SHELL is not supported for OCI image format, [/bin/bash -o pipefail -e -u -x -c] will be ignored. Must use `docker` format
You can resolve this issue by exporting the BUILDAH_FORMAT environment variable to Podman:
export BUILDAH_FORMAT=docker
If you use Docker Desktop, ensure that the Use containerd for pulling and storing images setting is turned off. Otherwise, you might receive errors when you run astro deploy such as:
Push access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed
# or
Unable to find image 'barren-ionization-0185/airflow:latest' locally
Error response from daemon: pull access denied for barren-ionization-0185/airflow, repository does not exist or may require 'docker login'