feat: ✨ guide to make GitHub Apps to make tokens

_quarto.yml

@@ -22,6 +22,9 @@ book:
     :::
   chapters:
     - index.qmd
+    - part: "Operations"
+      chapters:
+        - operations/security.qmd
   page-footer:
     center:
       - text: "License: CC BY 4.0 {{< fa brands creative-commons >}} {{< fa brands creative-commons-by >}}"

operations/security.qmd

@@ -0,0 +1,96 @@
+# Security practices
+
+## Using GitHub Apps to generate tokens
+
+[GitHub Apps](https://docs.github.com/en/apps/overview) 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`](https://github.com/organizations/seedcase-project/settings/apps).
+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`](https://github.com/actions/create-github-app-token).
+In your workflow file, add this action:
+
+``` yaml
+- 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:
+
+``` yaml
+with:
+  token: ${{ steps.app-token.outputs.token }}
+```
+
+For example, if you want to use the token in a checkout action, you can
+do:
+
+``` yaml
+- 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`