# 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](https://doc.flow.swiss/products/ci-engine/how-to/change-image-of-integration) 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.