Skip to main content

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


astro deploy <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<your-secret-id>, src=<path-to-secret> . See Docker documentation.
-d, --dagsDeploy only your dags directory. See DAG-only deploysNone
-n, --deployment-nameThe name of the Deployment to deploy to. Use as an alternative to <deployment-id>Any valid Deployment name
--descriptionA description for your code deploy. Descriptions appear in the Astro UI in your Deployment's Deploy HistoryNone
-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 errors or uncommitted changesNone
--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
-p,--promptForce the Deployment selection prompt even if a Deployment ID is specifiedNone
--pytestDeploy code to Astro only if the specified pytests are passedNone
-s,--saveSave the current Deployment and working directory combination for future deploysNone
-t,--testThe filepath to an alternative pytest file or directoryValid filepath within your Astro project
--workspace-id <string>In the prompt to select a Deployment, only show Deployments within this WorkspaceAny valid Workspace ID
-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
-w, --waitWait for the Deployment to become healthy before completing the commandNone


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:

export BUILDAH_FORMAT=docker

Was this page helpful?

Sign up for Developer Updates

Get a summary of new Astro features once a month.

You can unsubscribe at any time.
By proceeding you agree to our Privacy Policy, our Website Terms and to receive emails from Astronomer.