2  Security practices

Note

This guidebook is written following the diátaxis “how-to guide” style. And because this document reflects how we work in the Seedcase Project, it is living and constantly evolving. It won’t ever be in a state of “done”.

2.1 Using GitHub Apps to generate tokens

GitHub Apps are a way to integrate with GitHub and perform actions on behalf of a user or organization. For instance, they can be used to generate tokens with specific permissions to use in GitHub Action workflows. Rather than creating a personal access token (PAT) that works for the organisation and then having to regularly regenerate them, if you create a GitHub App, it can create a token when it is needed, e.g. whenever a specific workflow runs. As soon as the workflow is done, the token is deleted. That way, you can limit the exposure of the token, minimising security risks.

You can make a GitHub App to create a token following these steps:

  1. Go to the organization’s settings and click the “GitHub Apps” link under “Developer Settings” at the bottom of the settings sidebar, e.g. seedcase-project.
  2. Click “New GitHub App” to create a new app.
    • Fill in the app name with a descriptive name, e.g. “generate-auto-release-token”.
    • Fill in the description on what the app does.
    • For the homepage URL, use the format: https://github.com/apps/APP-NAME, e.g. https://github.com/apps/generate-auto-release-token.
    • Uncheck all the checkboxes in the other sections.
    • Select the permissions you want the app to have under “Permissions”.
    • Select “Only on this account” under “Where can this GitHub App be installed?”.
    • Click “Create GitHub App” to create the app.
  3. In the newly created app, scroll to the bottom and click “Generate a private key” to create a private key for the app.
    • Save the private key to your computer, as it will be used to generate the token.
  4. On the sidebar, click the “Install App” link and in the new page, click “Install” on the organisation you want it in.
    • Give it access to the repositories you want it to have access to by clicking “All repositories” or “Only select repositories” and selecting the repositories you want it to have access to.
  5. Go to the organisation’s settings under “Security” and “Secrets and variables”, click the “Actions” link.
  6. Click the “Variables” tab and then “Create new organisation variable” (or edit an existing one).
    • Write a new name for the variable, being descriptive enough to know what it is for.
    • Paste the “App ID” of the app you created, which is found in the app’s settings page at the top.
  7. Click the “Secrets” tab and then “New organisation secret” (or edit an existing one).
    • Write a new name for the secret, being descriptive enough to know what it is for.
    • Go to your computer and using a text editor, open the private key you saved earlier. Copy the contents of the file and paste it into the secret’s value field.

To make use of the app and it’s generated token in workflows, you can use the actions/create-github-app-token. In your workflow file, add this action:

- uses: actions/create-github-app-token@v2
  id: app-token
  with:
    app-id: ${{ vars.APP_ID }}
    private-key: ${{ secrets.APP_PRIVATE_KEY }}

Then, in any other action that needs a token, use:

with:
  token: ${{ steps.app-token.outputs.token }}

For example, if you want to use the token in a checkout action, you can do:

- name: Checkout
  uses: actions/checkout@v4
  with:
    token: ${{ steps.app-token.outputs.token }}

If you have branch rulesets or branch protections set up, you will need to add the app to the bypass list, if it is necessary to do things that are against the ruleset or protection.

If you need to set the app as a “user” in the workflow, use the name github-actions[bot] and the email 41898282+github-actions[bot]@users.noreply.github.com