jku · Oct 7, 2026 · Oct 6, 2026
@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+* Support GitHub App authentication instead of long-lived token `TUF_ON_CI_TOKEN`
+  (this is purely a documentation & template workflow change)
+
+Updating a repository from 0.21 does not require changes in GitHub workflow files.
+However, users are adviced to switch to the new GitHub App authentication mechanism
+by integrating workflow changes from
+[tuf-on-ci-template](https://github.com/theupdateframework/tuf-on-ci-template) and
+configuring a GitHub App as documented in [GITHUB-APP-SETUP.md](GITHUB-APP-SETUP.md).
+
 ## v0.21.0
 
 * Support Tillitis TKey (ML-DSA) hardware tokens (#815)

@@ -38,8 +38,7 @@ This feature is still experimental, and also there are some known issues
   GitHub Action token, automated signing may be required to be
   dispatched manually.
 
-  A solution to this can be to use a different token, such as a PAT or
-  an OAuth application.
+  A solution to this is to configure a [GitHub App](GITHUB-APP-SETUP.md).
 
 * **Number of signers**: Currently only a single online signer can be
   configured for a delegation. This also means that there can not be a
@@ -84,10 +83,17 @@ jobs:
     name: TUF-on-CI Foo Delegate sign
     runs-on: ubuntu-latest
     permissions:
-      contents: write # for making commits in signing event and for modifying draft state
-      pull-requests: write # for modifying signing event pull requests
-      actions: write # for dispatching another signing-event workflow
+      contents: write # for making commits in signing event (not needed if using GitHub App)
+      actions: write # for dispatching another signing-event workflow (not needed if using GitHub App)
     steps:
+      - name: Create GitHub App token
+        id: app-token
+        if: vars.TUF_ON_CI_APP_ID != ''
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          client-id: ${{ vars.TUF_ON_CI_APP_ID }}
+          private-key: ${{ secrets.TUF_ON_CI_APP_PRIVATE_KEY }}
+          permission-contents: write
 
       - name: Sign delegation
         uses: theupdateframework/tuf-on-ci/actions/online-sign-targets@main
@@ -96,7 +102,7 @@ jobs:
           azure_tenant_id: secrets.AZURE_TENANT_ID
           azure_subscription_id: secrets.AZURE_SUBSCRIPTION_ID
           targets_to_sign: foo-delegate
-          token: ${{ secrets.TUF_ON_CI_TOKEN || secrets.GITHUB_TOKEN }}
+          token: ${{ steps.app-token.outputs.token || secrets.GITHUB_TOKEN }}
 ```
 
 The steps to work with automated delegation signing would thus be:

@@ -0,0 +1,59 @@
+# GitHub App Authentication in TUF-on-CI
+
+By default, TUF-on-CI workflows authenticate using the built-in `GITHUB_TOKEN`. While this
+works out of the box, configuring a GitHub App is recommended for production repositories
+to avoid long-lived Personal Access Tokens (PATs).
+
+Using a GitHub App allows you to:
+* Avoid long lived bearer tokens in repository secrets
+* Enable branch protection on `main` with only GitHub App in the bypass list for periodic
+  online signing commits
+* Uncheck _Allow GitHub Actions to create and approve pull requests_
+  so that arbitrary workflows using `GITHUB_TOKEN` cannot open or approve pull requests.
+
+## Security model
+
+* **Short-lived, downscoped tokens**: Instead of storing a long-lived token, workflows
+  use `actions/create-github-app-token` to mint a short lived token. Each workflow
+  requests only the permissions it needs on the current repository:
+  * `online-sign`: `contents: write`, `actions: write`
+  * `create-signing-events`: `contents: write`
+  * `signing-event`: `contents: write`, `pull-requests: write`
+* **Private key isolation**: The GitHub App private key (`TUF_ON_CI_APP_PRIVATE_KEY`) is
+  only passed to `actions/create-github-app-token` in the caller workflow. The `tuf-on-ci`
+  actions only ever see the short-lived token.
+* **Workflow modification protection**: The GitHub App is blocked from modifying
+  `.github/workflows/*` files, even when the App is allowed to bypass branch protection on `main`.
+
+## Setup instructions
+
+1. **Create the GitHub App** in your organization or personal account (_Organization Settings_
+   or _Settings -> Developer settings -> GitHub Apps -> New GitHub App_):
+   * **GitHub App name**: e.g. `<repo-name>-tuf-on-ci`. Visible in PR and issue comments
+   * **Homepage URL**: the repository URL
+   * **Callback URL, Setup URL, and OAuth options**: leave at defaults
+   * **Webhook**: uncheck _Active_
+   * **Repository permissions**:
+     * `Actions`: _Read and write_ (to dispatch `publish.yml` after online signing)
+     * `Contents`: _Read and write_ (to push online signing commits, `publish` branch updates, and signing event branches/commits)
+     * `Pull requests`: _Read and write_ (to create, update, and comment on signing event pull requests)
+   * **Where can this GitHub App be installed?**: _Only on this account_
+1. **Generate credentials**:
+   * On the App settings page, copy the **Client ID**
+   * Under **Private keys**, click **Generate a private key** to download the `.pem` file.
+1. **Install the GitHub App**:
+   * In the App settings sidebar, select **Install App** and **Only select repositories**
+     -> your TUF-on-CI repository.
+1. **Configure the repository**:
+   * Create a _Repository Variable_ (_Settings -> Secrets and variables -> Actions -> Variables_)
+     `TUF_ON_CI_APP_ID` with the App's Client ID
+   * Create a _Repository Secret_ (_Settings -> Secrets and variables -> Actions -> Secrets_)
+     `TUF_ON_CI_APP_PRIVATE_KEY` with the contents of the downloaded `.pem` file.
+     The local private key copy should be destroyed at this point.
+1. **Tighten repository settings**:
+   * Uncheck _Settings -> Actions -> General -> Allow GitHub Actions to create and approve pull requests_.
+   * In _Settings -> Rules -> Rulesets_ for `main`, enable
+     _Require a pull request before merging_ and add the GitHub App to the bypass list
+   * Optionally, you can also remove the job `permissions:` entries marked
+     `# ... (not needed if using GitHub App)` in `online-sign.yml`, `create-signing-events.yml`,
+     and `signing-event.yml` so the default `GITHUB_TOKEN` has no write permissions in those jobs.
@@ -5,18 +5,32 @@ ongoing maintenance.
 
 ## New Repository Setup
 
+### Setup decisions
+
+Before initializing the repository, decide on two configuration choices (both can also be
+changed later):
+* **Online signing method**: Automated signing of `timestamp` and `snapshot` roles supports
+  Google Cloud KMS, Azure Key Vault, AWS KMS, and Sigstore (experimental). See
+  [ONLINE-SIGNING-SETUP.md](ONLINE-SIGNING-SETUP.md) for details.
+* **GitHub workflow authentication**: Workflows use the default `GITHUB_TOKEN` out of the
+  box, or can use a **GitHub App** to allow stricter repository security settings (such as
+  branch protection on `main` and disabling pull request creation for `GITHUB_TOKEN`)
+  without maintaining long-lived Personal Access Tokens. See
+  [GITHUB-APP-SETUP.md](GITHUB-APP-SETUP.md) for details.
+
+### Setup steps
+
 1. [Create new repository](https://github.com/new?template_name=tuf-on-ci-template&template_owner=theupdateframework)
    using the tuf-on-ci template: the created repository contains all the required workflows.
 1. Configure the new repository:
    * set _Settings->Pages->Source_ to `GitHub Actions`
    * Change _Settings->Environments->github-pages_ deployment branch from `main` to
      `publish`
-   * Check _Settings->Actions->General->Allow GitHub Actions to create and approve pull requests_
-     (not required if you are using a custom token, see below)
+   * Either [configure a GitHub App](GITHUB-APP-SETUP.md) or check
+     _Settings->Actions->General->Allow GitHub Actions to create and approve pull requests_
+     (to use the default `GITHUB_TOKEN`)
 1. Clone the repository locally and [configure your local signing tool](SIGNER-SETUP.md)
-1. Choose your online signing method and [configure it](ONLINE-SIGNING-SETUP.md):
-   * Google Cloud KMS, Azure Key Vault, and AWS KMS are fully supported
-   * Sigstore requires no configuration (but is experimental)
+1. [Configure your chosen online signing method](ONLINE-SIGNING-SETUP.md)
 1. Run `tuf-on-ci-delegate sign/init` to configure the repository and to start the
    first signing event
    * The tool prompts for various repository details and finally prompts to
@@ -103,40 +117,17 @@ upgrade mechanism is to copy the modified workflows from tuf-on-ci-template.
 Supported ways to configure and modify tuf-on-ci workflows:
 * online signing is configured using signing method specific _Repository Variables_,
   see [ONLINE-SIGNING-SETUP.md](ONLINE-SIGNING-SETUP.md) for details
-* A custom GitHub token can be optionally configured with _Repository Secret_
-  `TUF_ON_CI_TOKEN`, see details below
+* A GitHub App can be optionally configured with _Repository Variable_
+  `TUF_ON_CI_APP_ID` and _Repository Secret_ `TUF_ON_CI_APP_PRIVATE_KEY`, see
+  [GITHUB-APP-SETUP.md](GITHUB-APP-SETUP.md) for details
 * Workflow failure messages can be configured with `.github/TUF_ON_CI_TEMPLATE/failure.md`:
   Contents of this file will be included in issues that are opened if workflows fail. This is
-  useful to e.g. notify the maintenance team with @-mentions.
+  useful to e.g. notify the maintenance team with individual `@username` mentions (note that
+  `@org/team` mentions are not supported because failure issues are opened using the default
+  `GITHUB_TOKEN`).
 * Signing pull request templates can be configured with
   `.github/PULL_REQUEST_TEMPLATE/signing_event.md`. Contents of this file will be included in
   the pull request message when non-maintainer signers contribute to signing events. This is
   useful to e.g. notify the maintenance team with @-mentions.
 * The `publish` workflow can be customized to publish to a destination that is not
   the default GitHub Pages
-
-### Custom GitHub token
-
-tuf-on-ci uses GITHUB_TOKEN by default but supports using a custom fine-grained Github
-token. This allows the project to limit the default GITHUB_TOKEN permissions
-(in practice this means other workflows in the repository can operate with this lower
-permission default token while tuf-on-ci workflows still have higher permissions).
-
-The custom token needs the following repository permissions:
-* `Actions: write` to dispatch other workflows when needed
-* `Contents: write` to create online signing commits, and to create targets metadata
-  change commits in signing event
-* `Issues: write` to create issues on workflow failures
-* `Pull requests: write` to create and modify signing event pull requests
-
-To use a custom token, define a _repository secret_ `TUF_ON_CI_TOKEN` with a fine grained
-token as the secrets value. No workflow changes are needed. Note that all automated comments
-in signing event pull requests will be seemingly made by the account that created the custom
-token: Creating the token on a "bot" account is sensible for this reason.
-
-When a custom token is used, some repository security settings can be tightened:
-* _Settings->Actions->General->Allow GitHub Actions to create and approve pull requests_
-  can be disabled
-* Custom token owner (bot) can be added to _Allow specified actors to bypass required
-  pull requests_ list in GitHub branch protection settings, and _Settings->Branches->
-  main->Require a pull request before merging_ can then be enabled