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

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

After installing the CLI, deploy tasks by running:

bash
Copied
1
airplane 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:

bash
Copied
1
airplane 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

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

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

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 for a service account at https://app.airplane.dev/settings/service-accounts
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 --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

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:


Copied
1
📦airplane
2
 ┣ 📂sales ⭐ PROJECT ROOT
3
 ┃ ┣ 📜airplane.yaml
4
 ┃ ┣ 📜my_task.airplane.ts
5
 ┃ ┣ 📜my_task_airplane.py
6
 ┃ ┣ 📜my_view.airplane.tsx
7
 ┃ ┣ 📜package.json
8
 ┃ ┣ 📜requirements.txt
9
 ┃ ┗ 📜restTask.task.yaml
10
 ┗ 📂support ⭐ PROJECT ROOT
11
 ┃ ┣ 📜airplane.yaml
12
 ┃ ┣ 📜package.json
13
 ┃ ┗ 📜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

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

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.