Skip to content
Merged
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
13 changes: 8 additions & 5 deletions .github/workflows/docouture-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down
13 changes: 8 additions & 5 deletions code/packages/cli/templates/workflows/docouture-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-11-11
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -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`)
30 changes: 30 additions & 0 deletions openspec/specs/docs-release-app-token/spec.md
Original file line number Diff line number Diff line change
@@ -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
Loading