Deployments
Deploy tasks and views to Airplane manually or with a GitHub integration.
A deployment contains one or more tasks or views that are deployed atomically. If the deployment
succeeds, all entities in the deployment are updated. If the deployment fails or is cancelled, none
of the entities in the deployment are updated.
How to deploy to Airplane
How to deploy to Airplane
Get started quickly by using the CLI to deploy tasks and views
from your local machine via
airplane deploy
.Once your tasks are up and running, we recommend using the
GitHub integration to automatically deploy tasks
and views whenever they change. If you're not using GitHub, you can always deploy
from your own CI/CD system.
CLI
CLI
After installing the CLI, deploy tasks by running:
bashCopied1airplane deploy
This command discovers and deploys all Airplane tasks in the current directory as well as all child
directories.
Alternatively, you can deploy a specific task or view by running:
bashCopied1airplane deploy ./your_task_file.py
You can
airplane deploy
multiple files, a directory, or multiple directories. The CLI discovers
Airplane tasks in any files or directories you provide.airplane deploy
is equivalent to airplane deploy .
.Local deploys
Local deploys
By default, all deploys run in Airplane infrastructure, and all generated images are stored in
Airplane-hosted repositories. The
airplane deploy
CLI has some flags that change this behavior:Flags | Effect(s) |
---|---|
--local | Run the deployment locally and push the resulting image(s) to Airplane repositories. |
--local --dest=REPOSITORY_URI | Run the deployment locally and push the resulting image(s) to a repository controlled by your team. The tool will use whatever docker registry credentials are in your environment. |
--local --dest=REPOSITORY_URI --no-push | Run the deployment locally without automatically pushing. After verifying the images and pushing them via your own tooling, you'll need to run airplane builds approve with the correct build ID(s) to mark the deployment as complete in the Airplane API (the output of airplane deploy will have more details). This allows for security scans of images before using them in Airplane, among other use cases. |
Adding a
--output-meta=OUTPUT_FILE
flag to any of the above will write a metadata file in JSON
format that can be used for automating any custom, follow-up steps.Deploying with the
--dest
option requires that your agents and tasks are configured to pull images
from the associated repository. See the Private Docker images page for more
details.Run
airplane deploy --help
for more information on these and other options.If running on macOS, You may need to
allow the default Docker socket to be used
in order to use the
--local
option. This can be configured in the advanced settings of the Docker
Desktop app.GitHub integration
GitHub integration
The GitHub integration automatically deploys Airplane tasks and views when they are pushed to
GitHub.
Set up the GitHub integration by connecting GitHub repositories to Airplane. Once connected, pushes
to a configured branch will automatically deploy any modified Airplane tasks.
We only support GitHub at this time. Let us know if there are any other Git providers you'd like to
use with Airplane!
Setup
Setup
Visit Git repositories within Developer settings and
select
Connect repositories
.
Select
Continue with GitHub
to open a popup window that prompts you to authenticate with GitHub.Once authenticated, select
Add an account
to install the Airplane GitHub integration in your
personal account or organization. In the popup window, choose an account and select any repositories
(or all repositories) that you want to connect to Airplane.
Once you have installed the Airplane app, return to Airplane. You should see all of the repositories
that you granted the Airplane app access to in the previous step.

Select
Connect
next to a repository. Complete the connection configuration:Default Branch
:git push
to this branch to trigger a deployment. This will often be the same as your default branch in GitHub or your production branch if you have one.Directory
: Airplane tasks in this directory and subdirectories will be automatically deployed./
indicates that Airplane tasks may live anywhere in the repository.

Select
Connect
to finalize the connection. Once setup is complete, you should see your connected
repositories.
That's it! The next push to the configured branch of the repository will deploy Airplane tasks.
Why are some of my repositories not showing up?
Why are some of my repositories not showing up?
If you are not seeing all of your repositories for the selected personal account or organization,
you need to grant the Airplane GitHub access to more repositories.
A GitHub organization admin should visit the
GitHub installation settings, choose the
Airplane.dev
app, and add repositories (or select All repositories
) under Repository access
.How do I switch to a different GitHub account?
How do I switch to a different GitHub account?

Select
Disconnect GitHub
to disconnect your GitHub account from Airplane.
Sign out of GitHub and then log back in with the GitHub account you
want to switch to.
Return to the Airplane UI and select
Continue with GitHub
to authenticate your new GitHub account.GitHub Action
GitHub Action
Although we recommend using the GitHub integration,
we also support a GitHub Action. This can
be useful if you need to run other actions before or after deploying.
Usage
Usage
See the
airplane-deploy
README for full
usage instructions.yamlCopied1# airplane.yml2name: airplane3on:4push:5branches:6# Or "master"7- main8jobs:9deploy:10runs-on: ubuntu-latest11steps:12- uses: actions/checkout@v313- uses: airplanedev/airplane-deploy@v114with:15# Generate a new API key for a service account at https://app.airplane.dev/settings/service-accounts16# Add your API key as a secret: https://docs.github.com/en/actions/security-guides/encrypted-secrets17api-key: ${{ secrets.AIRPLANE_API_KEY }}18# Find this at https://app.airplane.dev/settings/team19team-id: <your_team_id>
Once
airplane.yml
is merged into the main
branch, subsequent pushes to main
will deploy all
Airplane tasks in the repo.Deploying from another CI/CD system
Deploying from another CI/CD system
If you're using GitHub, we suggest using the
GitHub integration or
GitHub Action to automatically deploy Airplane tasks.
You can also deploy Airplane tasks from your existing CI system like Jenkins or CircleCI.
Install the CLI
Install the CLI
Follow the instructions for installing the CLI inside your build
environment.
The installer installs the CLI to
$HOME/.airplane/bin/airplane
. You can execute airplane
from
there or move it to an executable location.Run airplane deploy
Run
airplane deploy
bashCopied1export AP_API_KEY=<your_api_key>2export AP_TEAM_ID=<your_team_id>3airplane deploy ./path/to/tasks --yes
- Set an environment variable
AP_API_KEY
equal to your Airplane API key. - Set an environment variable
AP_TEAM_ID
equal to your Airplane team ID. - Deploy your Airplane tasks.
Airplane automatically detects git metadata like the current git branch and commit. You can specify
two additional environment variables -
AP_GIT_REPO
and AP_GIT_USER
- to indicate the git
repository and which user triggered the deploy respectively.Managing deployments
Managing deployments
You can view a list of current and past deployments
in the Airplane UI.
Each deployment consists of one or more project builds. Every
project (which itself may contain multiple tasks or
views) in the deployment is built separately. If a project contains tasks and views of different
types, multiple builds may spawn for that project.
For example, if you deploy the following projects:
Copied1📦airplane2┣ 📂sales ⭐ PROJECT ROOT3┃ ┣ 📜airplane.yaml4┃ ┣ 📜my_task.airplane.ts5┃ ┣ 📜my_task_airplane.py6┃ ┣ 📜my_view.airplane.tsx7┃ ┣ 📜package.json8┃ ┣ 📜requirements.txt9┃ ┗ 📜restTask.task.yaml10┗ 📂support ⭐ PROJECT ROOT11┃ ┣ 📜airplane.yaml12┃ ┣ 📜package.json13┃ ┗ 📜mySalesTask.airplane.ts
they will be deployed in 5 separate builds:
- sales project. Build for JavaScript
- sales project. Build for Python
- sales project. Build for View
- sales project. Build for REST
- support project. Build for JavaScript
Some builds may even end up discovering no tasks or views, for example if a file with a
.airplane.ts
extension does not contain any exported Airplane tasks.Deployment failure
Deployment failure
A deployment may fail for a few reasons:
- A task or view in the deployment fails to build, perhaps due to malformed code.
- The deployment is cancelled by a user.
When a deployment fails, none of the tasks in the deployment are updated—even those that build
successfully.
Git metadata
Git metadata
A deployment includes git metadata if it was created by the GitHub integration, the
airplane-deploy
GitHub Action, or through the CLI (if the CLI is run inside a git repository).The git metadata tells you:
- Who created the deployment.
- What repository the deployed tasks live in.
- The latest commit at the time of the deployment.
In addition, each deployed task stores the path to the task's entrypoint in the git repository,
allowing you to deep link a task to its code.