# Buildkite workflow

Use this guide to configure Buildkite build and deploy steps to manage releases in Aviator. To use Aviator Releases, we recommend having [<mark style="color:blue;">separate steps</mark>](https://docs.aviator.co/releases-beta/concepts/two-step-delivery) for the build and deploy workflows. You may still use it as a single step, in which case the creation of Release (the build part) will be a no-op.

## Authentication

Buildkite doesn’t have a concept of Apps or bot accounts. Because of this, we need to take an access token for a user.

**Step 1**: Go to “Personal Settings” from the top-right corner

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2FqBVXvG926BImFxKbdkUc%2FUntitled.png?alt=media&#x26;token=66fdf014-80bd-47c8-bed8-e610ee01f748" alt=""><figcaption></figcaption></figure>

**Step 2**: Click “API Access Tokens”

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2FOdDl2G8pkCq8aULhfTUy%2FUntitled%20(1).png?alt=media&#x26;token=b850b8e0-19ba-4f01-b942-c5e45bac69e4" alt=""><figcaption></figcaption></figure>

**Step 3**: Click “New API Access Token”

Name the token and pick your organization

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2FXr231RU4ntDQvGMN7aGm%2FUntitled%20(3).png?alt=media&#x26;token=33122ab3-e9a3-429f-9c96-3d442d9a0eb1" alt=""><figcaption></figcaption></figure>

Choose “**Read Builds**”, “**Write Builds**”, and “**Read Pipelines”**.

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2FX3FXHoiA3ZIwQLEua6WP%2FUntitled%20(4).png?alt=media&#x26;token=acc59a3f-30b0-4d97-b70d-3c1776668427" alt=""><figcaption></figcaption></figure>

Click “Create New API Access Token”

**Step 4**: Copy the created access token, and go to <https://app.aviator.co/settings/workspace/integrations>, paste the created access token to the Buildkite integration.

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2FfIUO13XofVDjzAzdKhO1%2FUntitled%20(5).png?alt=media&#x26;token=31e83d88-e18b-4008-889a-3e2908260363" alt=""><figcaption></figcaption></figure>

## 2. Setup Buildkite Webhook

Go to your Buildkite organization’s settings from the top bar.

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2FsXb8wFW8xU4UeKhiN8zA%2FUntitled%20(6).png?alt=media&#x26;token=31d67033-710b-4689-8af4-22b02d6d9b70" alt=""><figcaption></figcaption></figure>

Go to “Notification Services”

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2Fsg47R59iV7e16uUvoNqs%2FUntitled%20(7).png?alt=media&#x26;token=61325abb-13ec-40ff-bd88-13e722f103bd" alt=""><figcaption></figcaption></figure>

Add “Webhook”

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2FUBkAk3jPzI0VGkDU2SwE%2FUntitled%20(8).png?alt=media&#x26;token=9351413b-784c-4fa7-a2d5-518c4341577f" alt=""><figcaption></figcaption></figure>

Name this webhook and put [`https://app.aviator.co/api/buildkite/webhook`](https://app.aviator.co/api/buildkite/webhook) to the webhook URL.

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2FJIlCIaVXGdKQBq6y83iw%2FUntitled%20(9).png?alt=media&#x26;token=577a1123-1deb-4051-992c-d94f7fd81a3b" alt=""><figcaption></figcaption></figure>

Choose “build.schedules”, “build.running”, “build.failing”, and “build.finished”.

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2FApOHzg1xjA65CJIsCho2%2FUntitled%20(10).png?alt=media&#x26;token=d4742887-4601-4f5c-884d-909a461dd94a" alt=""><figcaption></figcaption></figure>

Click “Add Webhook Notification”.

## Build workflow

### Option A - Using Two-step workflow

#### Connecting with Aviator

On Buildkite pipeline page, copy the pipeline’s URL

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2FQYm2sioUVBXWhU42dRdB%2FUntitled%20(11).png?alt=media&#x26;token=80c2a7ad-9a7a-46e5-bc06-d74691bc767c" alt=""><figcaption></figcaption></figure>

Go to the release project config for the build pipeline configuration. Choose Buildkite and paste the organization and pipeline names as shown in the copied URL.

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2FcBFjlQH25ET8kcdwjHt7%2FScreenshot%202024-07-09%20at%2011.43.43%E2%80%AFAM%20(1).png?alt=media&#x26;token=483f08e4-62d4-416e-ae24-84fc7148b561" alt=""><figcaption><p>Buildkite Organization and Pipeline slug</p></figcaption></figure>

Click “SAVE”.

#### Using Environment variables

Aviator sends the following parameters to Buildkite as environment variables when triggering the workflow:

`AVIATOR_RELEASE_CUT_ID` - Aviator’s internal database ID associated with the Release.

`AVIATOR_RELEASE_CANDIDATE_VERSION` - A unique version string tied to the Release Candidate. This can be used to tag the built artifacts.

`AVIATOR_RELEASE_CUT_COMMIT_HASH` - commit SHA associated with the release candidate version. You should checkout this commit SHA in the build pipeline to trigger the workflow.

### Option B - Skipping build step

If you want to skip the Build step entirely, select “Not Configured” in the Build step:

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2FG8zryQa6UmyAVCJfSNYK%2FScreenshot%202024-07-08%20at%208.59.22%E2%80%AFAM%20(2).png?alt=media&#x26;token=ebdf73d5-08df-4917-af58-7eecf655179b" alt=""><figcaption><p>Skip the build step</p></figcaption></figure>

In this configuration mode, as soon as a Release is cut, the build is marked as completed. Then you can set up deployment as a separate step.

## Deploy workflow

#### Connecting with Aviator

Similar to the Build step, copy the Organization Slug and Pipeline slug in the Deploy environment configuration:

<figure><img src="https://273246003-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOAPqUQVbLbsfI5YESl32%2Fuploads%2Fz2fvaG0Qj4dg9wNTujW4%2FScreenshot%202024-07-09%20at%2011.52.06%E2%80%AFAM.png?alt=media&#x26;token=ff6a17f4-80f1-4b5e-a95b-376b547dc0aa" alt=""><figcaption><p>Deployment configuration for Buildkite</p></figcaption></figure>

#### Using Environment variables

Aviator sends the following parameters to Buildkite as environment variables when triggering the workflow:

`AVIATOR_DEPLOYMENT_ID` - Aviator’s internal database ID associated with the [<mark style="color:blue;">Deployment</mark>](https://docs.aviator.co/concepts/terminology#deployment).

`AVIATOR_RELEASE_CANDIDATE_VERSION` - A unique version string tied to the [<mark style="color:blue;">Release Candidate</mark>](https://docs.aviator.co/concepts/terminology#release-candidate). This can be used to tag the built artifacts.

`AVIATOR_RELEASE_CUT_COMMIT_HASH` - commit SHA associated with the release candidate version. You should checkout this commit SHA in the build pipeline to trigger the workflow.

Now you should be ready to use Aviator Release Management!