Configure GitHub¶

This documentation includes workflows for automatically updating dependencies. To make them work, you need to allow the automated creation and approval of pull requests in GitHub, configure auto-merge, and set up automated checks. The workflows authenticate as a GitHub App, so that the created pull requests trigger subsequent workflows (which the default GITHUB_TOKEN cannot do) and commits are authored by the bot account.

Allow automated PRs¶

In your GitHub repository:

1. Go to Settings, Actions, General. Scroll to the bottom.

2. Set:

   • Allow GitHub Actions to create and approve pull requests: yes

3. Click Save.

Require status checks¶

This requires status checks to succeed, before (automated or manual) PRs are auto-merged.

In your GitHub repository:

1. Go to Settings, Branches.
2. Click Add classic branch protection rule to create a new branch protection rule.

3. Set:

   • Branch name pattern: main
   • Protect matching branches
     • Require status checks to pass before merging: yes
       • Require branches to be up to date before merging: yes
       • Status checks that are required: Build Documentation

4. Click Save changes.

Enable auto-merge¶

In your GitHub repository:

1. Go to Settings, General. Scroll down to the Pull Requests section.

2. Set:

   • Allow auto-merge: yes

Create a GitHub App¶

By design, workflows that use the GITHUB_TOKEN will not trigger new workflow runs, to avoid recursive workflow runs. This means that the status checks will not automatically run for the PRs created by the workflow. To fix this, the workflows authenticate as a GitHub App instead of using the GITHUB_TOKEN. Commits and PRs created by the App show up as authored by the bot account, and the App's commits are signed by GitHub and show as Verified.

1. In your GitHub profile, go to Settings, Developer settings, GitHub Apps (or click here).

2. Click New GitHub App. Give the following values:

   • GitHub App name: Virtlink Bot
   • Homepage URL: https://pelsmaeker.net/
   • Webhook
     • Active: disabled
   • Repository permissions
     • Contents: Read and write
     • Pull requests: Read and write
     • Issues: Read and write
     • Metadata: Read-only (required)
     • Workflows: Read and write
   • Where can this GitHub App be installed? Only on this account

   Workflow permission

   The Workflows permission is required because the Update GitHub Actions workflow uses Renovate to update the versions of the GitHub Actions referenced in the workflow files themselves. Without this permission, GitHub rejects any push that modifies files under .github/workflows/.

3. Click Create GitHub App.

4. Under Private keys, click Generate a private key and download the .pem file. Keep it safe, as you will not be able to download it again.
5. Determine the App ID (found at the top under About).

Install the GitHub App¶

In the GitHub App settings, click Install App and click the Install button next to the account to install the bot to. You can restrict the App to specific repositories.

Configure the repository to use the GitHub App¶

In the GitHub repository:

1. Go to Settings, Secrets and variables, Actions.
2. On the Secrets tab, under Repository secrets, click New repository secret.

3. Add the following secret:

   • Name: APP_ID
   • Secret: the App ID of the GitHub App

4. Click Add secret.

5. Click New repository secret again, and add:

   • Name: APP_PRIVATE_KEY
   • Secret: the entire contents of the .pem file (the App's private key)

   The private key is a multi-line string. Make sure to copy the entire contents of the .pem file. For example:

   -----BEGIN RSA PRIVATE KEY-----
   MIIEpgIBAAKCAQEAm9KB2dFRW9iRaRpdaUCWwPxRzlI3hmZxGWX60ump49NuJ4XM
   ...
   RR5z3JpJfVU4pfu8rOeEURBgLuUM4JMho2qU769I8VVlDTjRpRaaITp1
   -----END RSA PRIVATE KEY-----
   

6. Click Add secret.

The workflows already use the APP_ID and APP_PRIVATE_KEY secrets to generate an App token, so no further changes to the workflows are needed.