CLI reference

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.

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: true to .astro/config.yaml in your Astro project.
  • Add ASTRONOMER_SKIP_PARSE=true as an environment variable to your local environment or CI/CD pipeline.

Usage

1astro deploy <options>

Options

OptionDescriptionPossible Values
<deployment-id>Specifies the Deployment to deploy to and bypasses the Deployment selection promptAny valid Deployment ID
--build-secretsRun docker build --secret to mount a secret value to your Docker image.id=<your-secret-id>, src=<path-to-secret> . See Docker documentation.
--descriptionA description for your code deploy. Descriptions appear in the Astro UI in your Deployment’s Deploy HistoryNone
-d, --dagsDeploy only your dags directory. See dag-only deploysNone
-e, --envLocation of the file containing environment variables for pytests. By default, this is .env.Any valid filepath to an .env file
-f, --forceForce 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-nameThe 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 machineA valid name for a pre-built Docker image based on Astro Runtime
--imageIf 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 AstroNone
-n, --deployment-nameThe name of the Deployment to deploy to. Use as an alternative to <deployment-id>.Any valid Deployment name
-p, --promptForce the Deployment selection prompt even if a Deployment ID is specifiedNone
--pytestDeploy code to Astro only if the pytests are passed. By default the pytests are read from the tests directory.None
-s, --saveSave the current Deployment and working directory combination for future deploys.None
-t, --testThe filepath to an alternative pytest file or directory.Valid filepath within your Astro project
-w, --waitWait 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

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:

1export 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'