# Setup GitHub Actions Integration

To integrate GitHub Actions 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 **GitHub Actions** as the CI-provider.
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 a [**PAT** at GitHub](#personal-access-token-configuration).
   2. Provide the **full repository name** which you’re creating the integration for and you have given the PAT access to. Make sure the repository name is formatted as follows: `<repository-owner>/<repository-name>`.
   3. 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 GitHub**](#webhook-configuration).
9. [Update the **runs-on** label](#workflow-configuration) in your GitHub Actions Workflow YAML to the string displayed in the wizard, which has the form `flow-runner-<random string>.`

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.

#### Personal Access Token Configuration

For the runners to authenticate themselves, a [fine-grained Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) needs to be provided. Create a new fine-grained PAT in your GitHub Developer settings and make sure to configure the token as follows:

1. Set the “Expiration” to **No expiration**
2. Under “Repository Access” select **Only selected repositories** and add the Repository which you’re creating the integration for.
3. Under “Permissions" add the repository permissions **Administration** and **Actions** and change "Access" to **Read and Write**. Note: This access will also enforce **Read** access for **Metadata**.

#### Webhook Configuration

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

1. In your GitHub repository, go to **Settings > Webhooks** and click on the **Add Webhook**-Button
2. Configure the **Payload URL** and the **Secret** 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. Under **Which events would you like to trigger this webhook?** select **Let me select individual events** and enable **Workflow jobs**. This event webhook is **required** for the runners to spawn correctly.

#### Workflow Configuration

In order for GitHub to know which runner can pick up a job you need to specify [runs-on](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) label in your GitHub Actions Workflow. This string needs to be set to the **Runner Label** provided in the Wizard-Step. Alternatively you can find this information on the details page of your integration. Make sure that all jobs have only this Runner Label configured on the [runs-on](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on) label or else it cannot be guaranteed that the job gets correctly picked up by the runner.


---

# 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-github-actions-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.