[PR] docs(ci): record the Nightly tag push a workflow change rejects [maka]

["Astro-Han (via GitHub)" <gi...@apache.org>]

Astro-Han opened a new pull request, #5245:
URL: https://github.com/apache/maka/pull/5245

   ## Summary
   
   Desktop Nightly tags the npm Nightly source commit, and by the time that push happens the commit is an ancestor of `main`. `GITHUB_TOKEN` can never hold `workflows` write, so GitHub rejects the push whenever `.github/workflows/` changed on `main` after the source commit:
   
   ```
   ! [remote rejected] <sha> -> v<version> (refusing to allow a GitHub App to create or
     update workflow `.github/workflows/ci.yml` without `workflows` permission)
   ```
   
   The run stops at `Ensure the exact versioned Nightly tag`, so that version ends up with no tag and no prerelease. Observed on 2026-09-12 for `0.2.0-dev.29.20260912` (run [34711858653](https://github.com/apache/maka/actions/runs/34711858653)): #5241 and #5187 landed on `ci.yml` between the npm source commit (18:13 UTC) and the tag push (19:01 UTC). Nights whose window contains no workflow change succeed, so this is a race between unrelated merges and the tag step, not a broken build.
   
   This adds the failure signature and the recovery decision next to the rerun rule that already sits in that paragraph, so an operator who hits it recovers the documented way instead of reaching for a credential. Documentation only: no workflow, script, or runtime behavior changes.
   
   ## Root cause
   
   Two rules that are each correct meet at this step. The tag must point at the exact approved source commit, which the pipeline can only reach after ~45 minutes of builds, so it is always an ancestor of `main` rather than its tip; and a `GITHUB_TOKEN` push cannot create a ref whose workflow files differ from the default branch. There is no code path that satisfies both while `.github/workflows/` moves underneath the run.
   
   The alternatives were weighed and rejected: a credential with `workflows` write would let the release pipeline edit CI, and it would be the only long-lived secret of its kind in the repository against the trusted-publishing stance in this same document; retrying does not converge, because `main` only moves further away; tagging `main` instead would break the provenance the tag exists for; and creating the tag before verification would leave tags for versions that were never published.
   
   ## Verification
   
   - Reproduced the failure from the real run log (`gh run view 34711858653 --log-failed`), which names the `Ensure the exact versioned Nightly tag` step and the `workflows` permission rejection.
   - Confirmed the two `ci.yml` commits that landed inside the source-commit to tag-push window, and that the preceding nights carry no workflow change in that window and published normally.
   - Confirmed `release.yml` creates its product tag through the same `scripts/product-release-tag.mjs` and the same token, so the note applies to both publication paths.
   - Documentation-only change: no test covers it, and the lint/format lane does not apply to Markdown (Biome covers TS/JS/MJS only). No suite was run against this diff.
   
   ## AI use
   
   - [ ] No generative tool made a substantive contribution
   - [x] Generative tooling made a substantive contribution
   
   Tool(s) and scope: Maka agent — drafted the added sentence and this description from the failed run's log and the checked-in release documents. The maintainer made the decision to record this as an accepted risk with no credential and no code change.
   
   ## Checklist
   
   - [ ] Tests cover the change and fail without it
   - [ ] Lint, format, typecheck and the affected suites pass locally
   
   Does this PR entail a change in behavior?
   
   - [ ] Yes — described under Summary above
   - [x] No
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org

Re: [PR] docs(ci): record the Nightly tag push a workflow change rejects [maka]

["Astro-Han (via GitHub)" <gi...@apache.org>]

Astro-Han closed pull request #5245: docs(ci): record the Nightly tag push a workflow change rejects
URL: https://github.com/apache/maka/pull/5245


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org