Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 27 additions & 5 deletions STANDARDS.md
Original file line number Diff line number Diff line change
Expand Up @@ -203,11 +203,33 @@ shows in the changelog. `config-conventional`'s own default allows `build`,
OIDC trusted publishing to npm and PyPI. No stored tokens. Each publish job runs
in an environment (`npm-release`, `pypi`) limited to `main`, and sets the
environment's `url` to the version it published, so each deployment on the
environment's page links to its release on the registry. Where a service has no
OIDC (Cloudflare), the token is an environment secret limited to `main`, and the
deploy job cannot write to the repo. An optional deploy is switched on by a
repository variable, because a job-level `if:` can read `vars` but not
`secrets`.
environment's page links to its release on the registry.

No dependency install or build runs in a job that holds `id-token: write`. A
`build` job with `contents: read` builds and uploads the result as an artifact
(`python -m build`'s `dist/`, or the tarball from `npm ci` then `npm pack`), and
the publish job downloads it and only publishes, with no checkout. A
dependency's install script or a build backend then never runs where a registry
credential can be minted. `npm publish <tarball>` runs no package scripts, and
`npm pack` runs `prepack` and `prepare` but never `prepublishOnly`, so a
package's build belongs in `prepack`; a package that builds only in
`prepublishOnly` publishes without that build's output until it moves. The Node
template publishes one package from the repo root; a repo of npm workspaces
packs several tarballs, and the publish job refuses them. It also refuses a
tarball with any entry outside `package/` or more than one manifest, and one
whose `publishConfig` sets anything but `access`, `tag` or `provenance`, since
npm would apply a registry or TLS setting from it to the OIDC exchange. The
trusted publisher still sees the same workflow file and environment, since both
jobs are in the caller's file and only the publish job names the environment. A
failed publish job reruns from the same artifact, but only within GitHub's 30
day rerun window, and only while the artifact is kept (90 days by default, less
if the repo sets it lower). After that, the version can only be published by
hand.

Where a service has no OIDC (Cloudflare), the token is an environment secret
limited to `main`, and the deploy job cannot write to the repo. An optional
deploy is switched on by a repository variable, because a job-level `if:` can
read `vars` but not `secrets`.

## Dependabot

Expand Down
94 changes: 81 additions & 13 deletions template/node/.github/workflows/publish-prerelease.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,18 +21,16 @@ concurrency:
cancel-in-progress: false

jobs:
publish-prerelease:
name: publish prerelease to npm
# Installs, builds and packs in its own job, so no dependency's install
# script runs where an npm credential can be minted. `npm pack` runs the
# package's prepack and prepare scripts; prepublishOnly never runs, so a
# build kept there belongs in prepack.
build:
name: pack the prerelease
timeout-minutes: 10
runs-on: ubuntu-latest
# Scopes the OIDC token so npm's trusted publisher can require it. The url
# puts a link to the published version on the deployment.
environment:
name: npm-prerelease
url: ${{ steps.publish.outputs.url }}
permissions:
contents: read
id-token: write # OIDC for npm trusted publishing; provenance is automatic
env:
# Read through the environment rather than inlined into the run scripts,
# so a dispatch input can never be interpreted as shell.
Expand All @@ -55,18 +53,88 @@ jobs:
- uses: actions/setup-node@v7
with:
node-version: lts/*
registry-url: https://registry.npmjs.org
- run: npm ci
# Runner-local bump, never committed: main keeps its released version and
# the pending release-please PR keeps proposing a clean next version.
- run: npm version "$VERSION" --no-git-tag-version
- run: npm version "$VERSION" --no-git-tag-version --workspaces=false
# Outside the checkout: the package's own scripts may build into dist/.
- run: mkdir "$RUNNER_TEMP/pack" && npm pack --workspaces=false --pack-destination "$RUNNER_TEMP/pack"
- uses: actions/upload-artifact@v7
with:
name: package
path: ${{ runner.temp }}/pack/*.tgz
if-no-files-found: error

# Installs and builds nothing: it publishes the tarball the build job packed,
# and npm runs no package scripts when it publishes a tarball.
publish-prerelease:
name: publish prerelease to npm
needs: build
timeout-minutes: 10
runs-on: ubuntu-latest
# Scopes the OIDC token so npm's trusted publisher can require it. The url
# puts a link to the published version on the deployment.
environment:
name: npm-prerelease
url: ${{ steps.publish.outputs.url }}
permissions:
# OIDC for npm trusted publishing; provenance is automatic. Nothing
# else: there is no checkout, and the artifact downloads with the
# runner's own token.
id-token: write
env:
VERSION: ${{ inputs.version }}
DIST_TAG: ${{ inputs.dist_tag }}
steps:
- uses: actions/download-artifact@v8
with:
name: package
path: dist/
- uses: actions/setup-node@v7
with:
node-version: lts/*
registry-url: https://registry.npmjs.org
- name: Publish
id: publish
env:
# Only these publishConfig keys may come from the package.
CHECK_PUBLISH_CONFIG: >-
const manifest = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8").replace(/^\uFEFF/, ""));
const extra = Object.keys(manifest.publishConfig ?? {})
.filter((key) => !["access", "tag", "provenance"].includes(key));
if (extra.length) {
console.log(`::error::the packed package.json sets publishConfig ${extra.join(", ")}, which only this workflow may set`);
process.exit(1); }
run: |
npm publish --tag "$DIST_TAG"
set -- dist/*.tgz
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
# One package from the repo root: npm workspaces would pack several.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
if [ $# -ne 1 ] || [ ! -f "$1" ]; then
echo "::error::expected one tarball, found: $*. This workflow publishes a single package from the repo root, not npm workspaces"
exit 1
fi
# npm drops each entry's first path component when it reads the
# tarball, so an entry outside package/, or a second package.json,
# could be the manifest it uses rather than the one checked here.
entries=$(tar -tzf "$1")
if printf '%s\n' "$entries" | grep -v '^package/' >/dev/null ||
printf '%s\n' "$entries" | grep -E '//|(^|/)\.\.?(/|$)' >/dev/null ||
[ "$(printf '%s\n' "$entries" | grep -c '^package/package\.json$')" -ne 1 ]; then
echo "::error::$1 is not a plain npm pack tarball: an entry outside package/, or not exactly one package/package.json"
exit 1
fi
# A file, not an argument: a large exports map can pass the
# kernel's limit on one argument.
manifest=$RUNNER_TEMP/package.json
tar -xzOf "$1" package/package.json >"$manifest"
# npm applies the tarball's publishConfig, so a build step could
# point the OIDC exchange at another registry or switch off TLS
# checks. The registry and its trust settings come from this job.
node -e "$CHECK_PUBLISH_CONFIG" "$manifest"
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
npm publish "$1" --tag "$DIST_TAG"
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
# After the publish, so a failed one links nowhere.
name=$(node -p 'require("./package.json").name')
echo "url=https://www.npmjs.com/package/$name/v/$VERSION" >> "$GITHUB_OUTPUT"
name=$(node -p 'require(process.argv[1]).name' "$manifest")
version=$(node -p 'require(process.argv[1]).version.split("+")[0]' "$manifest")
echo "url=https://www.npmjs.com/package/$name/v/$version" >> "$GITHUB_OUTPUT"

tag-prerelease:
# Records which commit a beta was built from, so a report against
Expand Down
95 changes: 82 additions & 13 deletions template/node/.github/workflows/publish-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -47,12 +47,43 @@ jobs:
# release-triggered workflow would never fire and never report an error
# either.
#
# Installs, builds and packs in its own job, so no dependency's install
# script runs where an npm credential can be minted. `npm pack` runs the
# package's prepack and prepare scripts; prepublishOnly never runs, so a
# build kept there belongs in prepack.
build:
name: pack the package
needs: release-please
if: needs.release-please.outputs.release_created == 'true'
timeout-minutes: 10
runs-on: ubuntu-latest
permissions:
contents: read
steps:
- uses: actions/checkout@v7
with:
ref: ${{ needs.release-please.outputs.tag_name }}
persist-credentials: false
- uses: actions/setup-node@v7
with:
node-version: lts/*
- run: npm ci
# Outside the checkout: the package's own scripts may build into dist/.
- run: mkdir "$RUNNER_TEMP/pack" && npm pack --workspaces=false --pack-destination "$RUNNER_TEMP/pack"
- uses: actions/upload-artifact@v7
with:
name: package
path: ${{ runner.temp }}/pack/*.tgz
if-no-files-found: error

# In this file, not a reusable workflow: npm's trusted publisher names the
# workflow file that publishes, and that has to be the caller's.
#
# Installs and builds nothing: it publishes the tarball the build job packed,
# and npm runs no package scripts when it publishes a tarball.
publish:
name: publish to npm
needs: release-please
if: needs.release-please.outputs.release_created == 'true'
needs: build
timeout-minutes: 10
runs-on: ubuntu-latest
# Scopes the OIDC token so npm's trusted publisher can require it. The url
Expand All @@ -61,34 +92,72 @@ jobs:
name: npm-release
url: ${{ steps.publish.outputs.url }}
permissions:
contents: read
id-token: write # OIDC for npm trusted publishing; provenance is automatic
# OIDC for npm trusted publishing; provenance is automatic. Nothing
# else: there is no checkout, and the artifact downloads with the
# runner's own token.
id-token: write
steps:
- uses: actions/checkout@v7
- uses: actions/download-artifact@v8
with:
ref: ${{ needs.release-please.outputs.tag_name }}
persist-credentials: false
name: package
path: dist/
- uses: actions/setup-node@v7
with:
# trusted publishing needs npm >= 11.5.1, bundled with Node >= 24.5
node-version: lts/*
registry-url: https://registry.npmjs.org
- run: npm ci
# npm tags whatever it publishes 'latest' unless --tag is passed; it
# infers nothing from a prerelease suffix. A prerelease only reaches this
# job from a deliberate Release-As footer, so publish it under its own
# identifier (1.2.0-beta.1 -> beta) rather than moving latest.
# identifier (1.2.0-beta.1 -> beta) rather than moving latest. The name
# and version come from the packed package.json, which is what npm is
# sent.
- name: Publish
id: publish
env:
# Only these publishConfig keys may come from the package.
CHECK_PUBLISH_CONFIG: >-
const manifest = JSON.parse(require("fs").readFileSync(process.argv[1], "utf8").replace(/^\uFEFF/, ""));
const extra = Object.keys(manifest.publishConfig ?? {})
.filter((key) => !["access", "tag", "provenance"].includes(key));
if (extra.length) {
console.log(`::error::the packed package.json sets publishConfig ${extra.join(", ")}, which only this workflow may set`);
process.exit(1); }
run: |
name=$(node -p 'require("./package.json").name')
version=$(node -p 'require("./package.json").version')
set -- dist/*.tgz
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
# One package from the repo root: npm workspaces would pack several.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
if [ $# -ne 1 ] || [ ! -f "$1" ]; then
Comment thread
atdr marked this conversation as resolved.
Resolved
echo "::error::expected one tarball, found: $*. This workflow publishes a single package from the repo root, not npm workspaces"
exit 1
fi
# npm drops each entry's first path component when it reads the
# tarball, so an entry outside package/, or a second package.json,
# could be the manifest it uses rather than the one checked here.
entries=$(tar -tzf "$1")
if printf '%s\n' "$entries" | grep -v '^package/' >/dev/null ||
printf '%s\n' "$entries" | grep -E '//|(^|/)\.\.?(/|$)' >/dev/null ||
[ "$(printf '%s\n' "$entries" | grep -c '^package/package\.json$')" -ne 1 ]; then
echo "::error::$1 is not a plain npm pack tarball: an entry outside package/, or not exactly one package/package.json"
exit 1
fi
# A file, not an argument: a large exports map can pass the
# kernel's limit on one argument.
manifest=$RUNNER_TEMP/package.json
tar -xzOf "$1" package/package.json >"$manifest"
# npm applies the tarball's publishConfig, so a build step could
# point the OIDC exchange at another registry or switch off TLS
# checks. The registry and its trust settings come from this job.
node -e "$CHECK_PUBLISH_CONFIG" "$manifest"
Comment thread
atdr marked this conversation as resolved.
Resolved
name=$(node -p 'require(process.argv[1]).name' "$manifest")
# npm drops build metadata (1.2.3+abc is 1.2.3), so its hyphens never
# pick a dist-tag.
version=$(node -p 'require(process.argv[1]).version.split("+")[0]' "$manifest")
case "$version" in
*-*)
tag=$(node -p 'process.argv[1].match(/-([a-z]+)/i)?.[1] ?? "next"' "$version")
npm publish --tag "$tag"
npm publish "$1" --tag "$tag"
;;
*) npm publish ;;
*) npm publish "$1" ;;
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
esac
# After the publish, so a failed one links nowhere.
echo "url=https://www.npmjs.com/package/$name/v/$version" >> "$GITHUB_OUTPUT"
49 changes: 35 additions & 14 deletions template/python/.github/workflows/release-please.yml
Original file line number Diff line number Diff line change
Expand Up @@ -44,26 +44,16 @@ jobs:
# Gated on release-please's own output: a release made with GITHUB_TOKEN
# starts no `on: release` workflow.
#
# In this file, not a reusable workflow: PyPI's trusted publisher names the
# workflow file that publishes, and that has to be the caller's.
publish:
name: publish to PyPI
# Builds in its own job, so the build backend and everything it pulls in
# never run where a PyPI credential can be minted.
build:
name: build the distributions
needs: release-please
if: needs.release-please.outputs.release_created == 'true'
timeout-minutes: 10
runs-on: ubuntu-latest
# The url puts a link to the published version on the deployment, so the
# environment's page shows what each run released.
environment:
name: pypi
url: ${{ steps.published.outputs.url }}
permissions:
# A job-level block sets every unlisted scope to none, and checkout
# needs this one in a private repo.
contents: read
# No API token: PyPI trusts this workflow (owner/repo/environment) to
# mint its own short-lived credential via OIDC.
id-token: write
steps:
- uses: actions/checkout@v7
with:
Expand All @@ -76,6 +66,37 @@ jobs:
run: |
pip install build
python -m build
- uses: actions/upload-artifact@v7
with:
name: dist
path: dist/
if-no-files-found: error

# In this file, not a reusable workflow: PyPI's trusted publisher names the
# workflow file that publishes, and that has to be the caller's.
#
# Installs and builds nothing: it publishes the distributions the build job
# made, exactly as they were uploaded.
publish:
name: publish to PyPI
needs: build
timeout-minutes: 10
runs-on: ubuntu-latest
# The url puts a link to the published version on the deployment, so the
# environment's page shows what each run released.
environment:
name: pypi
url: ${{ steps.published.outputs.url }}
permissions:
# No API token: PyPI trusts this workflow (owner/repo/environment) to
# mint its own short-lived credential via OIDC. Nothing else: there is no
# checkout, and the artifact downloads with the runner's own token.
id-token: write
steps:
- uses: actions/download-artifact@v8
with:
name: dist
path: dist/
Comment thread
atdr marked this conversation as resolved.
Resolved
- uses: pypa/gh-action-pypi-publish@release/v1
# After the publish, so a failed one links nowhere. Read from the sdist,
# <name>-<version>.tar.gz, which is what PyPI was sent: a version holds
Expand Down
Loading
Loading