Deployments

Deploy tasks to Airplane manually or with a GitHub integration.

A deployment contains one or more tasks that are deployed atomically. If the deployment succeeds, all tasks in the deployment are updated. If the deployment fails or is cancelled, none of the tasks in the deployment are updated.

How to deploy tasks to Airplane

Get started quickly by using the CLI to deploy tasks from your local machine via airplane deploy.

Once your tasks are up and running, we recommend using the GitHub integration to automatically deploy tasks whenever they change. If you're not using GitHub, you can always deploy from your own CI/CD system.

CLI

After installing the CLI, deploy tasks by running:

bash
Copied
1
airplane deploy ./your_task_file.py

Deploy multiple tasks in a single deployment by airplane deploying multiple files, a directory, or multiple directories. The CLI discovers Airplane tasks in any files or directories you provide.

GitHub integration

The GitHub integration automatically deploys Airplane tasks 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

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?

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?

Visit team settings and select Connect repositories under the GitHub integration header.

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

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

See the airplane-deploy README for full usage instructions.

yaml
Copied
1
# airplane.yml
2
name: airplane
3
on:
4
push:
5
branches:
6
# Or "master"
7
- main
8
jobs:
9
deploy:
10
runs-on: ubuntu-latest
11
steps:
12
- uses: actions/checkout@v3
13
- uses: airplanedev/airplane-deploy@v1
14
with:
15
# Generate a new API key from the CLI by running `airplane apikeys create <key name>`.
16
# Add your API key as a secret: https://docs.github.com/en/actions/security-guides/encrypted-secrets
17
api-key: ${{ secrets.AIRPLANE_API_KEY }}
18
# Find this at https://app.airplane.dev/settings/team
19
team-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

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

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

bash
Copied
1
export AP_API_KEY=<your_api_key>
2
export AP_TEAM_ID=<your_team_id>
3
airplane deploy ./path/to/tasks
  • 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

You can view a list of current and past deployments in the Airplane UI.

You can inspect the individual tasks in a deployment, including their status and build logs, by clicking on the deployment name.

Deployment failure

A deployment may fail for a few reasons:

  • A task in the deployment fails to build, perhaps due to malformed code.
  • A merge conflict is detected - A task changes after the deployment begins.
  • 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

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.