[build] generate release docs at approval and commit them after the packages publish - #18113

• Generate API documentation alongside package publishing to shorten the release workflow.
• Build docs only for languages in the release tag, then commit their artifacts once publishing
 completes.
• Preserve manual documentation runs with generation and commit enabled by default.

graph TD
  Parser["Release tag parser"] --> Generator["Docs generation"] --> Artifacts["Documentation artifacts"] --> Commit["Docs commit"] --> Pages["gh-pages branch"]
  Parser --> Publish["Package publishing"] --> Commit

Loading

Keep parallel, per-language generation followed by one commit: it removes documentation builds from the post-publish path and avoids competing pushes. A single aggregate build would reduce parallelism, while retaining per-language commits would retain push contention. Before merging, consider requiring successful generation rather than merely a non-skipped result so a failed build cannot lead to a partial documentation commit.

Other (3) +51 / -21

parse-release-tag.ymlExpose released languages as a JSON matrix +7/-0

Expose released languages as a JSON matrix

• Adds a 'languages' output containing either the tag's single language or all five languages for a full release. The release workflow uses it to start only applicable documentation jobs.

.github/workflows/parse-release-tag.yml

release.ymlGenerate docs before publishing completes, then commit once +22/-9

Generate docs before publishing completes, then commit once

• Adds a tag-driven documentation matrix after authorization and tag creation, running alongside package publishing. Replaces the per-language post-publish documentation jobs with one commit-only job and includes generation in release-completion dependencies.

.github/workflows/release.yml

update-documentation.ymlSeparate documentation generation from committing +22/-12

Separate documentation generation from committing

• Replaces 'skip' with independently configurable 'generate' and 'commit' inputs that default to true for manual and reusable runs. The commit job collects all documentation artifacts into 'docs/api' and pushes once without the former rebase retry loop.

.github/workflows/update-documentation.yml

Description

The docs condition accepts a failed generate-docs matrix because it excludes only skipped, and
the final reusable workflow downloads whatever documentation artifacts exist. If one language fails
while another succeeds, the commit job can push only the successful language's documentation to
gh-pages.

Code

.github/workflows/release.yml[266]

+      needs.generate-docs.result != 'skipped' &&

Evidence

The matrix continues other languages after a failure, while the final job permits a failed matrix
result and commits artifacts without rebuilding them.

.github/workflows/release.yml[244-252]
.github/workflows/release.yml[263-276]
.github/workflows/update-documentation.yml[84-93]
.github/workflows/update-documentation.yml[96-121]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A failed language-specific documentation build does not stop the final job from committing the other languages' artifacts.
## Fix Focus Areas
- .github/workflows/release.yml[263-276]
## Recommended Fix
Require `needs.generate-docs.result == 'success'` before invoking the final documentation workflow.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

commit-docs now pushes its checked-out gh-pages branch once, without the previous pull-and-retry
loop or a concurrency constraint. If two release or manual documentation runs check out the same
branch state, the first push advances it and the second is rejected as non-fast-forward.

Code

.github/workflows/update-documentation.yml[121]

+          git push origin gh-pages

Evidence

The documentation workflow accepts independent manual runs and release calls; each checks out the
shared branch and now pushes without synchronization or retry.

.github/workflows/update-documentation.yml[4-29]
.github/workflows/update-documentation.yml[103-121]
.github/workflows/release.yml[263-278]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Independent documentation runs can overlap, and a single push from a stale checkout fails after another run updates gh-pages.
## Fix Focus Areas
- .github/workflows/update-documentation.yml[103-121]
## Recommended Fix
Restore a bounded fetch/rebase-and-push retry for non-fast-forward failures, or serialize all documentation writers with an appropriate concurrency group.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

commit-docs permits a skipped generate-docs job, but its download step looks for artifacts
produced in the current run. A fresh manual dispatch with generate: false and commit: true
therefore reaches the commit path without any documentation artifact to apply.

Code

.github/workflows/update-documentation.yml[R98-100]

+    if: >-
+      ${{ !cancelled() && inputs.commit &&
+          needs.parse.result == 'success' && needs.generate-docs.result != 'failure' }}

Evidence

Both booleans are exposed to manual dispatch; skipping generation leaves no producer in that run,
yet the commit condition still allows the download step.

.github/workflows/update-documentation.yml[22-29]
.github/workflows/update-documentation.yml[84-100]
.github/workflows/update-documentation.yml[108-113]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A fresh manual run can request a documentation commit while disabling the only job that produces its artifacts.
## Fix Focus Areas
- .github/workflows/update-documentation.yml[22-29]
- .github/workflows/update-documentation.yml[84-113]
## Recommended Fix
Reject `generate: false` with `commit: true` for a fresh manual dispatch, or provide an explicit source run from which to download artifacts.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

💡 Did you know, you can keep summaries lean with Findings visible per group, which tucks the rest behind a View link

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗