# Setup Buildkite Integration

To integrate Buildkite with your CI-Engine subscription, follow the steps below:

1. Navigate to CI-Engine > [Integrations](https://my.flow.swiss/#/ci-engine/integrations).
2. Click on the **(+) Plus** sign.
3. Choose the **subscription** for which you create the integration.
4. Choose **Buildkite** as the CI-provider of the integration.
5. Choose a global or custom image for your runners to use.
   1. You can always [change the image of the integration](/products/ci-engine/how-to/change-image-of-integration.md) later.
6. Configure the runners to connect to your repository.
   1. Setup an [**Agent Token** at Buildkite](#agent-token-configuration)
   2. Define a runner timeout, after which a runner without an active build job will be terminated.
7. Give your integration a name.
8. Configure a [**webhook** at Buildkite](#webhook-configuration)
9. Add the displayed public [SSH key to your repository](#ssh-configuration).

Once you finished the steps above you are ready to build! Simply trigger the Workflow you just updated to run on CI-Engine and check the state of your runners on the detail page of your subscription.

#### Agent Token Configuration

The [agent token](https://buildkite.com/docs/agent/v3/tokens#create-a-token-using-the-buildkite-interface) is used to authenticate and connect the agent on each new runner to your pipeline. We support both clustered and unclustered tokens. However we strongly suggest the usage of a clustered agent token as this is the new default for Buildkite agent tokens. You can find out more about unclustered Buildkite agent tokens [here](https://buildkite.com/docs/agent/v3/unclustered-tokens).

#### Webhook Configuration

To spawn the runners on demand you need to setup Webhooks in your Buildkite pipeline:

1. In your Buildkite dashboard, go to **Settings > Notification Services** and click on the **Add**-Button for webhooks.
2. Configure the **Webhook URL** and the **Token** that are provided in the Wizard-Step. Alternatively you can find this information on the details page of your integration by clicking on **(**•••**) More** button and **View Webhook Config**.
3. Configure the **Webhook Notifications** by selecting the Events **job.scheduled** and **job.finished**. These Events are **required** for the runners to spawn correctly.

#### SSH Configuration

To give the runner access to clone your repository during the jobs you need to add the SSH public key that is provided on this step to your git provider. Most providers support a **deploy key** that can be used for this purpose. For more instructions you can follow the official documentation of your provider:

* [GitLab](https://docs.gitlab.com/ee/user/project/deploy_keys/#create-a-project-deploy-key)
* [GitHub](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys#set-up-deploy-keys)
* [BitBucket](https://confluence.atlassian.com/bitbucketserver/ssh-access-keys-for-system-use-776639781.html#SSHaccesskeysforsystemuse-AddanSSHaccesskeytoeitheraprojectorrepository)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.flow.swiss/products/ci-engine/how-to/setup-buildkite-integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.