From 8648ce9cb794384e85b654a581ceba77a53efffa Mon Sep 17 00:00:00 2001 From: Roberto Tyley Date: Fri, 26 Apr 2024 16:58:00 +0100 Subject: [PATCH] Tweak docs --- docs/configuration.md | 31 +++++++++++++++++-------------- docs/github-app.md | 5 +++-- 2 files changed, 20 insertions(+), 16 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index b4b76a9..3d7506f 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -11,16 +11,22 @@ The release workflow needs a `release.yml` GitHub workflow in your repo, and spe ## Repo settings * Ensure [your GitHub App](github-app.md) has access to your repo. **Guardian developers:** click - `Configure` on the [gu-scala-library-release](https://github.com/apps/gu-scala-library-release) app, + `Configure` on the [gu-scala-library-release](https://github.com/apps/gu-scala-library-release) app - so long as you have admin permissions on your repo, you should be able to add your repo to the list - of select repositories the app has access to. -* Disable [branch protection **rules**](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) - on any branch the workflow will be pushing to (ie the default branch). Note that PR #26 means that you can use rulesets to protect your default branch, so long as you allow your GitHub App to bypass those restrictions. -* **Guardian developers:** - * Comply with the repository requirements of - [`guardian/github-secret-access`](https://github.com/guardian/github-secret-access?tab=readme-ov-file#how-does-it-work), - i.e. ensure the repository has a `production` Topic label - * [Re-enable branch protection via rulesets](https://github.com/guardian/recommendations/blob/main/github-rulesets.md). + of selected repositories. +* **Guardian developers:** Comply with the repository requirements of [`guardian/github-secret-access`](https://github.com/guardian/github-secret-access?tab=readme-ov-file#how-does-it-work), + i.e. ensure the repository has a `production` Topic label. + +### Branch protection + +Your [GitHub App](github-app.md) will need to push to directly to your default branch as part of the +release, bypassing any branch protection. GitHub provides two different methods of branch protection: +* [Branch protection **rules**](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) - + there is no mechanism to allow a GitHub App to bypass branch protection **rules**, so you'll + need to **remove any rules that apply to the default branch**. +* [Branch protection **rulesets**](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets) - + rulesets _can_ be configured to allow specified GitHub Apps (e.g. _your_ GitHub app) to bypass branch protection - + update your rulesets accordingly. **Guardian developers:** see [recommended branch protection rulesets](https://github.com/guardian/recommendations/blob/main/github-rulesets.md). ## GitHub workflow @@ -121,11 +127,8 @@ or `sonatype.sbt` (`sonatype.sbt` can generally be deleted entirely): ## Examples -GitHub pull requests on repos updating for `gha-scala-library-release-workflow`: - -* https://github.com/guardian/facia-scala-client/pull/299 _(most recent fully-commented example)_ -* https://github.com/guardian/play-secret-rotation/pull/416 -* https://github.com/guardian/play-googleauth/pull/208 +You can see a long list of example PRs updating repos to use `gha-scala-library-release-workflow` +[here](https://github.com/guardian/gha-scala-library-release-workflow/issues/20). See also [_all repos_](https://github.com/search?q=%22guardian%2Fgha-scala-library-release-workflow%22++NOT+is%3Aarchived+NOT+repo%3Aguardian%2Fgha-scala-library-release-workflow+language%3AYAML&type=code&l=YAML) using Scala Library Release Workflow. diff --git a/docs/github-app.md b/docs/github-app.md index b8533df..ea2fd19 100644 --- a/docs/github-app.md +++ b/docs/github-app.md @@ -6,8 +6,9 @@ making PR comments. Each organisation that uses the release workflow will need to create their _own_ GitHub App. If `gha-scala-library-release-workflow` had its own server infrastructure, we could probably follow the more common model of a single GitHub App being used by many organisations, but instead we take advantage of all those -free GitHub Actions minutes, so we need to pass the workflow the private key of the GitHub App so that it can -authenticate as the GitHub App... therefore we must each have our own GitHub App, so that we don't share private keys. +free GitHub Actions minutes, so we operate as a GitHub Actions workflow, and need to pass the workflow the private +key of the GitHub App so that it can authenticate as the GitHub App... therefore we must each have our own GitHub App, +so that we don't share private keys. ## 1. Create the GitHub App