BUILD-11805 Document BUILD_NUMBER reuse across actions wrapping get-build-number

[julien-carsique-sonarsource]

Summary

Audits every ci-github-actions action that internally calls get-build-number and closes the documentation gaps:

• config-pip, config-poetry, config-uv: had no "Input Environment Variables" section at all despite calling get-build-number - added it with the BUILD_NUMBER reuse row.
• build-yarn: calls get-build-number directly (no config-yarn wrapper exists) but didn't document it - added the "automatically calls" note and the BUILD_NUMBER row.
• build-poetry: added a "See also config-poetry input environment variables" pointer, matching the existing build-npm/build-gradle/build-maven pattern.
• promote: only documented PROJECT_VERSION, not BUILD_NUMBER. Added the row and a note clarifying that cross-job reuse (e.g. a build job followed by a promote job in the same workflow run) is now automatic since v2 via Git references - no manual needs/env: BUILD_NUMBER wiring required, unlike the old actions/cache-based v1 mechanism. Annotated the existing "Basic usage" example accordingly instead of adding a new example that would reintroduce the obsolete manual-wiring pattern.

config-maven, config-gradle, config-npm, build-maven, build-gradle, build-npm, and get-build-number itself were already accurate and complete - no changes needed there.

Jira: BUILD-11805

Test plan

• pre-commit run --files README.md (markdownlint + others) passes
• Verified each edited action's action.yml to confirm it actually calls get-build-number (directly or via a config-* wrapper) before documenting the reuse behavior

[hashicorp-vault-sonar-prod]

BUILD-11805

[gitar-bot]

Code Review ✅ Approved 3 resolved / 3 findings

Documents BUILD_NUMBER reuse across actions that wrap get-build-number, closing gaps in config-pip, config-poetry, config-uv, build-yarn, build-poetry, and promote. Addresses missing environment variable tables, clarifies that cross-job BUILD_NUMBER reuse is now automatic in v2 via Git references, and corrects a promote example that was annotating the obsolete v1 manual-wiring pattern.

✅ 3 resolved

✅ Quality: config-poetry env table omits CURRENT_VERSION/PROJECT_VERSION

📄 README.md:453-457 📄 README.md:985-991
The newly added config-poetry "Input Environment Variables" section lists only BUILD_NUMBER, but config-poetry/poetry_set_project_version.sh honors a pre-set pair of CURRENT_VERSION/PROJECT_VERSION ("If both are set, they will be used as-is and no version update will be performed") exactly like config-maven, config-gradle and config-npm, whose tables all document that row (README.md:244-247, 663, 989). A reader now sees an authoritative-looking section for config-poetry that hides the only supported way to skip version replacement. config-pip and config-uv were checked and genuinely have no version handling, so their new tables are complete as-is.

✅ Edge Case: promote docs omit that BUILD_NUMBER is required across runs

📄 README.md:1422-1424 📄 README.md:1485
The new promote note and table row only state that BUILD_NUMBER is "not needed when promote runs in the same workflow run", never the converse: promote/action.yml:50 calls get-build-number unconditionally, so when promote runs in a different workflow run (e.g. a separate manually-triggered promote workflow) with no BUILD_NUMBER in the environment there is no refs/build-runs/<run_id>/* marker, a brand-new number is claimed, and promote.sh then queries build info for <build-name>/<new-number> and fails with "Build info retrieval failed" (promote/promote.sh:38,95) while also burning a build number. Spell out that BUILD_NUMBER must be provided explicitly in that case.

✅ Quality: Promote example annotates @v1 with the v2-only refs mechanism

📄 README.md:1422-1424 📄 README.md:1460-1461 📄 README.md:136-146
The added note links Git References - the refs/build-runs/<run_id>/<number> mechanism introduced in 2.0.0 - and the new inline comment is placed in an example pinned to promote@v1, whose get-build-number implementation (tag 1.8.9) coordinates through actions/cache with key build-number-${{ github.run_id }} and has no refs at all, so the referenced section does not describe what a @v1 user gets. Note also that because that v1 cache key is already scoped to github.run_id, same-run cross-job reuse worked in v1 too, contradicting the PR description's claim that it required manual needs/env: BUILD_NUMBER wiring before v2. Either move these examples to @v2 or qualify the note with the version that the Git References mechanism applies to.

Implementation Status ✅ 4 of 4 objectives covered

✅ BUILD-11805 - 4 of 4 objectives covered

This PR covers documenting the recommended workflow pattern for BUILD_NUMBER reuse, auditing and adding BUILD_NUMBER input environment variables to actions wrapping get-build-number, cross-referencing get-build-number behavior, and adding a promote usage example.

✅ 4 covered here

• ✅ Document the recommended workflow pattern where a dedicated job calls get-build-number and downstream jobs receive it via needs outputs and env BUILD_NUMBER
• ✅ Audit all ci-github-actions wrapping get-build-number and add BUILD_NUMBER to their Input Environment Variables sections where missing
• ✅ Cross-reference get-build-number docs for behavior when BUILD_NUMBER is pre-set
• ✅ Add a usage example for promote showing BUILD_NUMBER propagation across jobs

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing less information.

Comment with these commands to change the behavior for this request:

Auto-apply	Compact
gitar auto-apply:on	gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | Gitar}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues
0 New dependency risks

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud