From 19b7a4fa78839b4594a8755022688b03e16add5f Mon Sep 17 00:00:00 2001 From: Jussi Kukkonen Date: Wed, 14 Feb 2024 16:58:55 +0200 Subject: [PATCH 1/2] Update docs on PR permissions This updates the docs to match current requirements. This is written with the assumption that custom token users do not need the "Allow GHA to create PRs" check: we will see fit this is correct. --- docs/CHANGELOG.md | 4 +++- docs/REPOSITORY-MAINTENANCE.md | 12 ++++++++++-- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index e5842ef4..c45b3c36 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -16,7 +16,9 @@ but instead requires `pull-requests: write` * Custom token users need to create a new token with an additional permission `Pull requests: write` - +* _Settings->Actions->General->Allow GitHub Actions to create and + approve pull requests_ needs to be enabled in repository settings + (not required if a custom token is used) ## v0.5.0 diff --git a/docs/REPOSITORY-MAINTENANCE.md b/docs/REPOSITORY-MAINTENANCE.md index 89a9f8f6..af43af8d 100644 --- a/docs/REPOSITORY-MAINTENANCE.md +++ b/docs/REPOSITORY-MAINTENANCE.md @@ -6,10 +6,12 @@ ongoing maintenance. ## New Repository Setup 1. Fork the [template](https://github.com/theupdateframework/tuf-on-ci-template). -1. To enable repository publishing to GitHub Pages: +1. Configure the 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) 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 @@ -108,7 +110,7 @@ Supported ways to configure and modify tuf-on-ci workflows: ### Custom GitHub token tuf-on-ci uses GITHUB_TOKEN by default but supports using a custom fine-grained Github -token. This allows the GitHub organization to limit the default GITHUB_TOKEN permissions +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). @@ -123,3 +125,9 @@ To use a custom token, define a _repository secret_ `TUF_ON_CI_TOKEN` with a fin 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. + +Custom token users can also add the bot user to the _Allow specified actors to bypass required +pull requests_ list in GitHub branch protection settings. The benefits of this are: +* _Settings->Actions->General->Allow GitHub Actions to create and approve pull requests_ + can be disabled +* _Settings->Branches->main->Require a pull request before merging_ can be enabled From a894bf5acc8cf5bb58c83137586f2946c611def7 Mon Sep 17 00:00:00 2001 From: Jussi Kukkonen Date: Thu, 15 Feb 2024 10:31:33 +0200 Subject: [PATCH 2/2] docs: clarify the security settings --- docs/REPOSITORY-MAINTENANCE.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/REPOSITORY-MAINTENANCE.md b/docs/REPOSITORY-MAINTENANCE.md index af43af8d..72ddd97c 100644 --- a/docs/REPOSITORY-MAINTENANCE.md +++ b/docs/REPOSITORY-MAINTENANCE.md @@ -115,19 +115,20 @@ token. This allows the project to limit the default GITHUB_TOKEN permissions 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 -* `Actions: write` to dispatch other workflows when needed 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. -Custom token users can also add the bot user to the _Allow specified actors to bypass required -pull requests_ list in GitHub branch protection settings. The benefits of this are: +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 -* _Settings->Branches->main->Require a pull request before merging_ can be enabled +* 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