From a9f3fb80df63bf837c643577a21a73ee3787a5a9 Mon Sep 17 00:00:00 2001 From: Jack Berg <34418638+jack-berg@users.noreply.github.com> Date: Thu, 28 May 2026 09:32:56 -0500 Subject: [PATCH 1/2] Add recommendation to use environment secrets instead of repository secrets --- docs/recommendations.md | 52 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/docs/recommendations.md b/docs/recommendations.md index e8df2dc..8c5b382 100644 --- a/docs/recommendations.md +++ b/docs/recommendations.md @@ -44,6 +44,58 @@ Resources: - [Immutable releases](https://docs.github.com/en/code-security/concepts/supply-chain-security/immutable-releases) - [Verifying the integrity of a release](https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/verifying-the-integrity-of-a-release) +## GitHub environment secrets + +GitHub [environment secrets](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-an-environment) +provide an additional layer of protection for sensitive secrets used in +publishing, signing, and other privileged workflows. + +With **repository secrets**, any workflow running in the repository can access +them — including workflows triggered on non-protected branches. This means +anyone with write access could push a non-protected branch containing secret +exfiltration code and trigger a workflow without going through a PR review. + +With **environment secrets**, access is restricted to workflows running in the +context of a named environment, and that environment can be configured to only +allow deployments from specific branches. This means even a contributor with +write access cannot access the secrets without their code successfully passing +all branch protection criteria — i.e., an approved and merged PR. + +Recommendation: migrate publishing, signing, and other privileged secrets from +repository secrets to an environment with a deployment branch policy restricting +access to `main` and `release/**` branches. + +Steps: + +1. Create an environment (e.g., `protected`) in the repository settings. +2. Configure a deployment branch policy on the environment, allowing only + `main` and `release/**` (adjust to match your branching strategy). +3. Add your publishing and signing secrets to the environment. +4. Remove the corresponding repository-level secrets. If both exist, the + repository-level secret remains accessible from any branch, defeating the + purpose. +5. Update release workflows to run in the context of the environment: + + ```yaml + jobs: + release: + environment: protected + steps: + ... + ``` + +Caveats: + +- Repository admin permission is required to create environments and manage + environment secrets. See [Request Repository Admin Permissions](https://github.com/open-telemetry/community/blob/main/guides/maintainer/github-admin-processes.md#request-repository-admin-permissions) + if you need to request access. + +Resources: + +- [Using environments for deployment](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment) +- [Creating secrets for an environment](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets#creating-secrets-for-an-environment) +- [Example migration in opentelemetry-java](https://github.com/open-telemetry/opentelemetry-java/pull/8432/changes#diff-bae0feaab53d9bdd636360014c03f3456cd796c65e3984b5373443e92fdb5efeR17) + ## Binding to Network Interfaces Always bind to localhost rather than to 0.0.0.0 or any interface, unless there From 9fe482ba576c5dff60887e69c3dfb7fbdbc3ce0c Mon Sep 17 00:00:00 2001 From: Jack Berg <34418638+jack-berg@users.noreply.github.com> Date: Thu, 28 May 2026 09:43:34 -0500 Subject: [PATCH 2/2] ascii chars --- docs/recommendations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/recommendations.md b/docs/recommendations.md index 8c5b382..1a463d6 100644 --- a/docs/recommendations.md +++ b/docs/recommendations.md @@ -51,7 +51,7 @@ provide an additional layer of protection for sensitive secrets used in publishing, signing, and other privileged workflows. With **repository secrets**, any workflow running in the repository can access -them — including workflows triggered on non-protected branches. This means +them, including workflows triggered on non-protected branches. This means anyone with write access could push a non-protected branch containing secret exfiltration code and trigger a workflow without going through a PR review. @@ -59,7 +59,7 @@ With **environment secrets**, access is restricted to workflows running in the context of a named environment, and that environment can be configured to only allow deployments from specific branches. This means even a contributor with write access cannot access the secrets without their code successfully passing -all branch protection criteria — i.e., an approved and merged PR. +all branch protection criteria (i.e. an approved and merged PR). Recommendation: migrate publishing, signing, and other privileged secrets from repository secrets to an environment with a deployment branch policy restricting