From 7ee576ae962d43bc6190ee43dac51be6ba8ec347 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesus=20Manuel=20Pi=C3=B1eiro=20Cid?= Date: Wed, 11 Nov 2026 13:41:17 +0100 Subject: [PATCH 1/2] chore: initial commit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Jesus Manuel Piñeiro Cid From f49d416e79398296cd2442454e40fd63ff9ca541 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jesus=20Manuel=20Pi=C3=B1eiro=20Cid?= Date: Wed, 11 Nov 2026 13:52:25 +0100 Subject: [PATCH 2/2] fix(release): don't narrow the App token in the release job MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A narrowed installation token loses the App's ruleset bypass, so the Bump release descriptor push to a protected release branch is rejected (GH013). Drop owner, repositories and permission-contents from the release job's Git app token. sync-prerelease and publish keep theirs. Closes #298 Signed-off-by: Jesus Manuel Piñeiro Cid --- .github/workflows/docouture-release.yml | 13 ++++---- .../templates/workflows/docouture-release.yml | 13 ++++---- .../guides-releasing-a-documentation.adoc | 15 ++++++++++ .../.openspec.yaml | 2 ++ .../design.md | 21 +++++++++++++ .../proposal.md | 28 +++++++++++++++++ .../specs/docs-release-app-token/spec.md | 26 ++++++++++++++++ .../tasks.md | 19 ++++++++++++ openspec/specs/docs-release-app-token/spec.md | 30 +++++++++++++++++++ 9 files changed, 157 insertions(+), 10 deletions(-) create mode 100644 openspec/changes/archive/2026-11-11-release-bump-unnarrowed-app-token/.openspec.yaml create mode 100644 openspec/changes/archive/2026-11-11-release-bump-unnarrowed-app-token/design.md create mode 100644 openspec/changes/archive/2026-11-11-release-bump-unnarrowed-app-token/proposal.md create mode 100644 openspec/changes/archive/2026-11-11-release-bump-unnarrowed-app-token/specs/docs-release-app-token/spec.md create mode 100644 openspec/changes/archive/2026-11-11-release-bump-unnarrowed-app-token/tasks.md create mode 100644 openspec/specs/docs-release-app-token/spec.md diff --git a/.github/workflows/docouture-release.yml b/.github/workflows/docouture-release.yml index 0b8c04ec..4c9164cf 100644 --- a/.github/workflows/docouture-release.yml +++ b/.github/workflows/docouture-release.yml @@ -78,8 +78,11 @@ name: docouture-release # Docouture hardening, on top of the docouture scaffold: # - GITHUB_TOKEN is read-only. Every push (the release tag, the versioned # descriptor bump) already authenticates with the App token configured in -# "Git app credentials", and that token is narrowed to this repository -# and to contents: write. +# "Git app credentials". That token is deliberately NOT narrowed in the +# release job: a narrowed installation token loses the App's ruleset +# bypass and the descriptor bump is rejected (GH013) on a protected +# release branch (InditexTech/docouture#298). The sync-prerelease job, +# which never pushes to the release branch, still narrows its token. # - Every action is pinned to a full-length commit SHA. # - No dependency or Kroki image cache is restored: this job cuts a release, # and a cache another run wrote is a poisoning vector for anything that @@ -238,15 +241,15 @@ jobs: # `APP_CLIENT_ID` (a variable) and `APP_PRIVATE_KEY` (a secret) are # organization-level in InditexTech — set both at the org or repo # level for whichever GitHub App is bypass-listed on this site's rules. + # Deliberately not narrowed with owner/repositories/permission-*: a + # narrowed token is rejected (GH013) on the descriptor bump even + # though the App is bypass-listed — see issue #298. - name: Git app token id: app-token uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0 with: client-id: ${{ vars.APP_CLIENT_ID }} private-key: ${{ secrets.APP_PRIVATE_KEY }} - owner: ${{ github.repository_owner }} - repositories: ${{ github.event.repository.name }} - permission-contents: write - name: Git app credentials env: diff --git a/code/packages/cli/templates/workflows/docouture-release.yml b/code/packages/cli/templates/workflows/docouture-release.yml index 793cd0a8..e0b5b9f6 100644 --- a/code/packages/cli/templates/workflows/docouture-release.yml +++ b/code/packages/cli/templates/workflows/docouture-release.yml @@ -78,8 +78,11 @@ name: docouture-release # Docouture hardening, on top of the docouture scaffold: # - GITHUB_TOKEN is read-only. Every push (the release tag, the versioned # descriptor bump) already authenticates with the App token configured in -# "Git app credentials", and that token is narrowed to this repository -# and to contents: write. +# "Git app credentials". That token is deliberately NOT narrowed in the +# release job: a narrowed installation token loses the App's ruleset +# bypass and the descriptor bump is rejected (GH013) on a protected +# release branch (InditexTech/docouture#298). The sync-prerelease job, +# which never pushes to the release branch, still narrows its token. # - Every action is pinned to a full-length commit SHA. # - No dependency or Kroki image cache is restored: this job cuts a release, # and a cache another run wrote is a poisoning vector for anything that @@ -234,15 +237,15 @@ jobs: # `APP_CLIENT_ID` (a variable) and `APP_PRIVATE_KEY` (a secret) are # organization-level in InditexTech — set both at the org or repo # level for whichever GitHub App is bypass-listed on this site's rules. + # Deliberately not narrowed with owner/repositories/permission-*: a + # narrowed token is rejected (GH013) on the descriptor bump even + # though the App is bypass-listed — see issue #298. - name: Git app token id: app-token uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0 with: client-id: ${{ vars.APP_CLIENT_ID }} private-key: ${{ secrets.APP_PRIVATE_KEY }} - owner: ${{ github.repository_owner }} - repositories: ${{ github.event.repository.name }} - permission-contents: write - name: Git app credentials env: diff --git a/docs/src/modules/main/pages/guides-releasing-a-documentation.adoc b/docs/src/modules/main/pages/guides-releasing-a-documentation.adoc index a0879857..69926b95 100644 --- a/docs/src/modules/main/pages/guides-releasing-a-documentation.adoc +++ b/docs/src/modules/main/pages/guides-releasing-a-documentation.adoc @@ -134,3 +134,18 @@ release bumps it forward. Run the workflow by hand: Actions tab → "docouture-release" → Run workflow, supplying the version in versioned mode. Or release the docs in a separate pull request labelled `docs/release` without `release-type/*`. + +[#protected-branches] +== Protected release branches + +If the release branch is covered by a ruleset that requires pull requests, add the GitHub +App behind `APP_CLIENT_ID` and `APP_PRIVATE_KEY` to the ruleset's bypass list. The release +job pushes the release tag and the `docs/.release-version` bump with that App's token. + +That token is deliberately not narrowed with `owner`, `repositories` or `permission-*` +inputs in the release job. A narrowed installation token loses the App's ruleset bypass: +the bump is rejected with `GH013 Changes must be made through a pull request` and +`docs/.release-version` stays on the released version. The tradeoff is that the release +job's token carries all of the App's installation permissions, so install the App only +where it is needed. The `sync-prerelease` and publish jobs never push to the release +branch, so they keep narrowed tokens. diff --git a/openspec/changes/archive/2026-11-11-release-bump-unnarrowed-app-token/.openspec.yaml b/openspec/changes/archive/2026-11-11-release-bump-unnarrowed-app-token/.openspec.yaml new file mode 100644 index 00000000..2a7773d6 --- /dev/null +++ b/openspec/changes/archive/2026-11-11-release-bump-unnarrowed-app-token/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-11 diff --git a/openspec/changes/archive/2026-11-11-release-bump-unnarrowed-app-token/design.md b/openspec/changes/archive/2026-11-11-release-bump-unnarrowed-app-token/design.md new file mode 100644 index 00000000..ecb21939 --- /dev/null +++ b/openspec/changes/archive/2026-11-11-release-bump-unnarrowed-app-token/design.md @@ -0,0 +1,21 @@ +## Context + +`docouture-release.yml` mints one App token in the `release` job and uses it for `Push release tag` and `Bump release descriptor` (a push to the release branch). #250 narrowed it with `owner`, `repositories` and `permission-contents`. On rulesets requiring pull requests, the narrowed token loses the App's bypass (GH013); an un-narrowed token from the same App is accepted. Adding GPG signing did not help. Why narrowing loses bypass is not confirmed. + +## Goals / Non-Goals + +**Goals:** the descriptor bump works on protected release branches where the App is bypass-listed; the template and the header comment stay honest. + +**Non-Goals:** narrowing in `sync-prerelease` and `publish` (neither writes to the release branch); finding the root cause; opt-in narrowing. + +## Decisions + +- **Drop the three inputs in `release` only.** Minimal, matches the verified fix. Alternative, opt-in via a repo variable: `create-github-app-token` inputs cannot be omitted conditionally, so it needs duplicate steps with `if:`; rejected as over-engineering for an unconfirmed cause. +- **Keep `sync-prerelease` and `publish` narrowed.** They push to `automated/sync-*` / `gh-pages` and open PRs, not to the release branch. `gh-pages` could hit the same problem on a protected branch; left for a follow-up if reported. +- **Edit the template and this repo's copy together**, as the copy is rendered from the template (differences are only placeholders and pnpm setup). +- **Rewrite the "Docouture hardening" bullet** and the comment above the step so they do not present narrowing as protection for the release job. + +## Risks / Trade-offs + +- The release token carries all of the App's installation permissions -> mitigated by the App being installed only where intended and by the job's read-only `GITHUB_TOKEN` permissions. +- Unconfirmed cause -> state it as empirical in the comment and the guide. diff --git a/openspec/changes/archive/2026-11-11-release-bump-unnarrowed-app-token/proposal.md b/openspec/changes/archive/2026-11-11-release-bump-unnarrowed-app-token/proposal.md new file mode 100644 index 00000000..00628886 --- /dev/null +++ b/openspec/changes/archive/2026-11-11-release-bump-unnarrowed-app-token/proposal.md @@ -0,0 +1,28 @@ +# Proposal + +## Why + +On a repo whose release branch is covered by a ruleset requiring pull requests, the `Bump release descriptor` step of `docouture-release.yml` is rejected (GH013) even though the GitHub App is on the ruleset's bypass list. The `Git app token` step in the `release` job narrows the installation token with `owner`, `repositories` and `permission-contents`; with those inputs removed, the same push is accepted as a bypassed violation. The tag push succeeds but `docs/.release-version` is left on the released version. See InditexTech/docouture#298. + +## What Changes + +- In the `release` job of `docouture-release.yml`, the `Git app token` step no longer sets `owner`, `repositories` or `permission-contents`. +- The workflow header's "Docouture hardening" note stops claiming the token is narrowed and states why the release job's token is not narrowed (loses ruleset bypass, #298). +- The same edits are applied to this repository's own rendered copy, `.github/workflows/docouture-release.yml`. +- The releasing guide documents the tradeoff: narrowed tokens give least privilege but can lose ruleset bypass on protected branches. +- `publish` (pushes `gh-pages`) and `sync-prerelease` (pushes an `automated/sync-*` branch and opens a PR) keep their narrowed tokens: neither writes to the release branch. + +## Capabilities + +### New Capabilities +- `docs-release-app-token`: the credential the release job uses to push the release tag and the descriptor bump to a protected release branch. + +### Modified Capabilities + +## Impact + +- `code/packages/cli/templates/workflows/docouture-release.yml` (template, scaffolded by `docouture new` / `docouture upgrade`) +- `.github/workflows/docouture-release.yml` (this repo's copy) +- `docs/src/modules/main/pages/guides-releasing-a-documentation.adoc` +- Security: the release job's App token gets all of the App's installation permissions instead of `contents: write` on one repository. Sites that already patched their copy (e.g. weavejs#1285) converge with upstream after `docouture upgrade`. +- Root cause of the lost bypass is unconfirmed upstream; the fix is empirical. diff --git a/openspec/changes/archive/2026-11-11-release-bump-unnarrowed-app-token/specs/docs-release-app-token/spec.md b/openspec/changes/archive/2026-11-11-release-bump-unnarrowed-app-token/specs/docs-release-app-token/spec.md new file mode 100644 index 00000000..4b4bf807 --- /dev/null +++ b/openspec/changes/archive/2026-11-11-release-bump-unnarrowed-app-token/specs/docs-release-app-token/spec.md @@ -0,0 +1,26 @@ +## ADDED Requirements + +### Requirement: Release job App token is not narrowed +The `release` job of the docs release workflow SHALL mint its GitHub App installation token without the `owner`, `repositories` or `permission-*` inputs, so that pushes to the release branch honor the App's ruleset bypass. + +#### Scenario: Bump on a protected release branch +- **WHEN** a versioned release bumps `docs/.release-version` on a release branch protected by a pull-request ruleset whose bypass list contains the App +- **THEN** the push is accepted as a bypassed violation and the descriptor moves to the next patch version + +#### Scenario: Token inputs +- **WHEN** the `Git app token` step of the `release` job is rendered from the template +- **THEN** it sets only `client-id` and `private-key` + +### Requirement: Other jobs keep narrowed tokens +The `sync-prerelease` job and `docouture-publish.yml` SHALL keep narrowing their App tokens to the repository and the permissions they need, since neither pushes to the release branch. + +#### Scenario: Sync job +- **WHEN** the `sync-prerelease` job mints its token +- **THEN** it still sets `owner`, `repositories`, `permission-contents`, `permission-pull-requests` and `permission-workflows` + +### Requirement: Header and docs state the tradeoff +The workflow header comment SHALL NOT describe the release job's token as narrowed, and the releasing guide SHALL explain that narrowing can lose ruleset bypass on protected branches. + +#### Scenario: Reader checks the hardening note +- **WHEN** a reader reads the "Docouture hardening" section of the template +- **THEN** it says the release job's token is not narrowed and references #298 diff --git a/openspec/changes/archive/2026-11-11-release-bump-unnarrowed-app-token/tasks.md b/openspec/changes/archive/2026-11-11-release-bump-unnarrowed-app-token/tasks.md new file mode 100644 index 00000000..b6f73705 --- /dev/null +++ b/openspec/changes/archive/2026-11-11-release-bump-unnarrowed-app-token/tasks.md @@ -0,0 +1,19 @@ +## 1. Workflow template + +- [x] 1.1 In `code/packages/cli/templates/workflows/docouture-release.yml`, remove `owner`, `repositories` and `permission-contents` from the `release` job's `Git app token` step +- [x] 1.2 Rewrite the "Docouture hardening" bullet (header) and the step comment to say the release job's token is not narrowed and why (#298) +- [x] 1.3 Confirm `sync-prerelease` is unchanged and `docouture-publish.yml` is untouched + +## 2. This repository's copy + +- [x] 2.1 Apply the same edits to `.github/workflows/docouture-release.yml` + +## 3. Docs + +- [x] 3.1 Add a short "protected branches" note on the narrowed-token vs bypass tradeoff to `docs/src/modules/main/pages/guides-releasing-a-documentation.adoc`; update its AGENTS.md ledger row if needed + +## 4. Verify + +- [x] 4.1 Diff template vs `.github/workflows` copy: only placeholder/pnpm differences remain +- [x] 4.2 Run the CLI's template tests via `pnpm nx test` for the cli package (from `code/`) +- [x] 4.3 PR closes #298 (`Closes #298`) diff --git a/openspec/specs/docs-release-app-token/spec.md b/openspec/specs/docs-release-app-token/spec.md new file mode 100644 index 00000000..89e2ec6e --- /dev/null +++ b/openspec/specs/docs-release-app-token/spec.md @@ -0,0 +1,30 @@ +# docs-release-app-token Specification + +## Purpose +Defines the GitHub App token the docs release job uses to push the release tag and the descriptor bump to a protected release branch, so that ruleset bypass is honored. + +## Requirements +### Requirement: Release job App token is not narrowed +The `release` job of the docs release workflow SHALL mint its GitHub App installation token without the `owner`, `repositories` or `permission-*` inputs, so that pushes to the release branch honor the App's ruleset bypass. + +#### Scenario: Bump on a protected release branch +- **WHEN** a versioned release bumps `docs/.release-version` on a release branch protected by a pull-request ruleset whose bypass list contains the App +- **THEN** the push is accepted as a bypassed violation and the descriptor moves to the next patch version + +#### Scenario: Token inputs +- **WHEN** the `Git app token` step of the `release` job is rendered from the template +- **THEN** it sets only `client-id` and `private-key` + +### Requirement: Other jobs keep narrowed tokens +The `sync-prerelease` job and `docouture-publish.yml` SHALL keep narrowing their App tokens to the repository and the permissions they need, since neither pushes to the release branch. + +#### Scenario: Sync job +- **WHEN** the `sync-prerelease` job mints its token +- **THEN** it still sets `owner`, `repositories`, `permission-contents`, `permission-pull-requests` and `permission-workflows` + +### Requirement: Header and docs state the tradeoff +The workflow header comment SHALL NOT describe the release job's token as narrowed, and the releasing guide SHALL explain that narrowing can lose ruleset bypass on protected branches. + +#### Scenario: Reader checks the hardening note +- **WHEN** a reader reads the "Docouture hardening" section of the template +- **THEN** it says the release job's token is not narrowed and references #298