Version each publish leg against its own branch; validate at entry#215

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ptr727 merged 1 commit into from
Jun 26, 2026
Merged

Version each publish leg against its own branch; validate at entry #215

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
1 change: 1 addition & 0 deletions .github/workflows/build-docker-task.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -33,6 +33,7 @@ jobs:
secrets: inherit
with:
ref: ${{ inputs.ref }}
branch: ${{ inputs.branch }}

build-docker:
name: Build Docker image job
Expand Down
1 change: 1 addition & 0 deletions .github/workflows/build-executable-task.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,7 @@ jobs:
secrets: inherit
with:
ref: ${{ inputs.ref }}
branch: ${{ inputs.branch }}

build-executable-matrix:
name: Build executable project matrix job
Expand Down
1 change: 1 addition & 0 deletions .github/workflows/build-nugetlibrary-task.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -32,6 +32,7 @@ jobs:
uses: ./.github/workflows/get-version-task.yml
with:
ref: ${{ inputs.ref }}
branch: ${{ inputs.branch }}

build-nugetlibrary:
name: Build NuGet library project job
Expand Down
1 change: 1 addition & 0 deletions .github/workflows/build-pypilibrary-task.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -36,6 +36,7 @@ jobs:
uses: ./.github/workflows/get-version-task.yml
with:
ref: ${{ inputs.ref }}
branch: ${{ inputs.branch }}

build-pypilibrary:
name: Build PyPI library project job
Expand Down
52 changes: 32 additions & 20 deletions .github/workflows/build-release-task.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -67,11 +67,38 @@ jobs:
secrets: inherit
with:
ref: ${{ inputs.ref }}
branch: ${{ inputs.branch }}

# Entry gate: validate branch<->version consistency once, before the build jobs, so an NBGV mis-classification fails
# fast instead of after building and publishing. main must be a public release (no prerelease '-'); every other branch
# must carry a prerelease '-' (guards a develop leg being classified public and published as stable). Strip
# '+buildmetadata' first; a '-' there is legitimate, only a '-' in the core/prerelease segment marks a prerelease.
validate-release:
name: Validate release version job
needs: [get-version]
runs-on: ubuntu-latest
steps:
- name: Validate branch and version consistency step
env:
SEMVER2: ${{ needs.get-version.outputs.SemVer2 }}
BRANCH: ${{ inputs.branch }}
run: |
set -euo pipefail
CORE_AND_PRE="${SEMVER2%%+*}"
if [[ "$BRANCH" == "main" ]]; then
if [[ "$CORE_AND_PRE" == *-* ]]; then
echo "::error::Public (main) release version '$SEMVER2' carries a prerelease suffix; refusing to publish."
exit 1
fi
elif [[ "$CORE_AND_PRE" != *-* ]]; then
echo "::error::Prerelease ($BRANCH) version '$SEMVER2' has no prerelease suffix (NBGV classified it public); refusing to publish."
exit 1
fi

build-nugetlibrary:
name: Build NuGet library job
if: ${{ inputs.enable_nuget }}
needs: [get-version]
needs: [get-version, validate-release]
uses: ./.github/workflows/build-nugetlibrary-task.yml
secrets: inherit
with:
Expand All@@ -88,7 +115,7 @@ jobs:
build-pypilibrary:
name: Build PyPI library job
if: ${{ inputs.enable_pypi }}
needs: [get-version]
needs: [get-version, validate-release]
uses: ./.github/workflows/build-pypilibrary-task.yml
secrets: inherit
with:
Expand All@@ -101,7 +128,7 @@ jobs:
build-executable:
name: Build executable job
if: ${{ inputs.enable_executable }}
needs: [get-version]
needs: [get-version, validate-release]
uses: ./.github/workflows/build-executable-task.yml
secrets: inherit
with:
Expand All@@ -113,7 +140,7 @@ jobs:
build-docker:
name: Build Docker job
if: ${{ inputs.enable_docker }}
needs: [get-version]
needs: [get-version, validate-release]
uses: ./.github/workflows/build-docker-task.yml
secrets: inherit
with:
Expand All@@ -130,7 +157,7 @@ jobs:
# `github: true` still can't create a release.
if: ${{ inputs.github && !inputs.smoke }}
runs-on: ubuntu-latest
needs: [get-version, build-nugetlibrary, build-pypilibrary, build-executable, build-docker]
needs: [get-version, validate-release, build-nugetlibrary, build-pypilibrary, build-executable, build-docker]

steps:

Expand All@@ -140,21 +167,6 @@ jobs:
with:
ref: ${{ needs.get-version.outputs.GitCommitId }}

# Backstop (main only): a public release must not carry a prerelease '-', guarding against NBGV mis-versioning the
# public ref (e.g. a dispatch on a non-default ref) into a malformed "Latest" release. Strip '+buildmetadata'
# first - a '-' there is legitimate; only a '-' in the core/prerelease segment marks a prerelease.
- name: Verify public release version step
if: ${{ inputs.branch == 'main' }}
env:
SEMVER2: ${{ needs.get-version.outputs.SemVer2 }}
run: |
set -euo pipefail
CORE_AND_PRE="${SEMVER2%%+*}" # drop +buildmetadata; a '-' here is the genuine prerelease separator
if [[ "$CORE_AND_PRE" == *-* ]]; then
echo "::error::Public (main) release version '$SEMVER2' carries a prerelease suffix; refusing to publish."
exit 1
fi

# Collect assets by the `release-asset-<branch>-*` pattern so this step is target-agnostic: subset releases by
# deleting the target, not `enable_*: false` (a skipped `needs` job would skip this release job too). The release
# step guards `fail_on_unmatched_files: true`, so at least one `release-asset-*` must match; a repo that drops
Expand Down
11 changes: 11 additions & 0 deletions .github/workflows/get-version-task.yml
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -9,6 +9,12 @@ on:
required: false
type: string
default: ''
# Logical branch NBGV classifies against. Pins PublicRelease to this branch instead of the runner's GITHUB_REF,
# which on a publish dispatched from the default branch is that branch for every matrix leg. Empty keeps GITHUB_REF.
branch:
required: false
type: string
default: ''
outputs:
SemVer2:
value: ${{ jobs.get-version.outputs.SemVer2 }}
Expand DownExpand Up@@ -52,3 +58,8 @@ jobs:
- name: Run Nerdbank.GitVersioning tool step
id: nbgv
uses: dotnet/nbgv@master
env:
# NBGV reads the branch from GITHUB_REF; pin it to the leg being versioned so a publish dispatched from the
# default branch doesn't classify every leg as the public ref and strip its prerelease suffix.
GITHUB_REF: ${{ inputs.branch != '' && format('refs/heads/{0}', inputs.branch) || github.ref }}
GITHUB_REF_NAME: ${{ inputs.branch != '' && inputs.branch || github.ref_name }}
1 change: 1 addition & 0 deletions AGENTS.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -192,6 +192,7 @@ These conventions describe the target state. New and modified workflows must res
- **Shells**: multi-line `run:` blocks with bash start with `set -euo pipefail` - fail fast, fail on undefined vars, fail on a failed pipe segment.
- **Conditionals**: multi-line `if:` uses folded scalar `if: >-` so YAML preserves whitespace correctly. Literal block (`if: |`) is wrong because it embeds newlines inside the boolean expression.
- **Boolean inputs**: workflows triggered both via `workflow_call` and `workflow_dispatch` must declare each boolean input in *both* trigger blocks - one definition does not propagate to the other. `workflow_call` delivers booleans as actual booleans; `workflow_dispatch` delivers them as the *strings* `"true"`/`"false"`. Any `if:` consuming a boolean input must compare against both forms - `if: ${{ inputs.foo == true || inputs.foo == 'true' }}`.
- **Validate input/state consistency at entry, fail fast**: when a workflow's inputs must satisfy a cross-input or input-versus-derived-state invariant (e.g. the release branch must match the computed version's prerelease status, or two inputs are mutually exclusive), assert it **once** in a dedicated entry validation step/job that the downstream jobs `needs:`, before any expensive build or publish work - not as partial checks scattered deep in later jobs. One gate that fails fast with a clear `::error::` beats a late or one-directional check. Examples: [`build-release-task.yml`](./.github/workflows/build-release-task.yml)'s `validate-release` job (branch-versus-prerelease, both directions) and [`publish-docker-readme-task.yml`](./.github/workflows/publish-docker-readme-task.yml)'s "Validate inputs step".
- **Reusable workflows**: job-level `permissions:` are validated *before* the `if:` evaluates, so even a skipped job needs valid permissions declared. A `release` job with `permissions: contents: write` and `if: ${{ inputs.publish }}` will still cause `startup_failure` on a caller that doesn't grant `contents: write`. Either declare permissions at the call site, or omit the inner block and inherit.
- **Allowlist `success` and `skipped` explicitly** when chaining jobs across optional dependencies - `!= 'failure'` lets `cancelled` through (timeout, runner failure, manual cancel). Use `(needs.X.result == 'success' || needs.X.result == 'skipped')`.
- **Artifact retention**: workflow artifacts are an intra-run handoff only - durable copies live on the GitHub release, not in workflow artifacts - so they must not survive the run and accumulate against the small account-wide artifact-storage quota. **Every workflow that can produce artifacts ends with a terminal `cleanup-artifacts` job** that deletes the run's artifacts via the REST API: `permissions: actions: write`, `needs` the artifact producers, an `if:` that **includes** `always()` (so a failed run still cleans up) plus any workflow-specific gate (e.g. `publish-release.yml` adds `&& needs.setup.outputs.publish == 'true'` to run only on real publishes), independent of any required status check so housekeeping never gates a merge, `continue-on-error: true` on the delete step so even an unexpected failure never reds the run, and tolerant of individual list/delete failures (warn and continue). This covers not just `actions/upload-artifact` but build-records that actions emit automatically (e.g. `docker/build-push-action`'s `.dockerbuild`). Both `publish-release.yml` and `test-pull-request.yml` carry one; add one to any new artifact-producing entry workflow. Set `retention-days: 1` on explicit uploads as a backstop.
Expand Down
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
Version each publish leg against its own branch; validate at entry#215

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

ptr727
merged 1 commit into

from

Jun 26, 2026
 Merged


Version each publish leg against its own branch; validate at entry
#215
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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


1 change: 1 addition & 0 deletions
.github/workflows/build-docker-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -33,6 +33,7 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-docker:
 name: Build Docker image job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-executable-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,7 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-executable-matrix:
 name: Build executable project matrix job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-nugetlibrary-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,6 +32,7 @@ jobs:
 uses: ./.github/workflows/get-version-task.yml
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-nugetlibrary:
 name: Build NuGet library project job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-pypilibrary-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -36,6 +36,7 @@ jobs:
 uses: ./.github/workflows/get-version-task.yml
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-pypilibrary:
 name: Build PyPI library project job
Expand Down

52 changes: 32 additions & 20 deletions
.github/workflows/build-release-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -67,11 +67,38 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 # Entry gate: validate branch<->version consistency once, before the build jobs, so an NBGV mis-classification fails
 # fast instead of after building and publishing. main must be a public release (no prerelease '-'); every other branch
 # must carry a prerelease '-' (guards a develop leg being classified public and published as stable). Strip
 # '+buildmetadata' first; a '-' there is legitimate, only a '-' in the core/prerelease segment marks a prerelease.
 validate-release:
 name: Validate release version job
 needs: [get-version]
 runs-on: ubuntu-latest
 steps:
 - name: Validate branch and version consistency step
 env:
 SEMVER2: ${{ needs.get-version.outputs.SemVer2 }}
 BRANCH: ${{ inputs.branch }}
 run: |
 set -euo pipefail
 CORE_AND_PRE="${SEMVER2%%+*}"
 if [[ "$BRANCH" == "main" ]]; then
 if [[ "$CORE_AND_PRE" == *-* ]]; then
 echo "::error::Public (main) release version '$SEMVER2' carries a prerelease suffix; refusing to publish."
 exit 1
 fi
 elif [[ "$CORE_AND_PRE" != *-* ]]; then
 echo "::error::Prerelease ($BRANCH) version '$SEMVER2' has no prerelease suffix (NBGV classified it public); refusing to publish."
 exit 1
 fi

 build-nugetlibrary:
 name: Build NuGet library job
 if: ${{ inputs.enable_nuget }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-nugetlibrary-task.yml
 secrets: inherit
 with:
Expand All@@ -88,7 +115,7 @@ jobs:
 build-pypilibrary:
 name: Build PyPI library job
 if: ${{ inputs.enable_pypi }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-pypilibrary-task.yml
 secrets: inherit
 with:
Expand All@@ -101,7 +128,7 @@ jobs:
 build-executable:
 name: Build executable job
 if: ${{ inputs.enable_executable }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-executable-task.yml
 secrets: inherit
 with:
Expand All@@ -113,7 +140,7 @@ jobs:
 build-docker:
 name: Build Docker job
 if: ${{ inputs.enable_docker }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-docker-task.yml
 secrets: inherit
 with:
Expand All@@ -130,7 +157,7 @@ jobs:
 # `github: true` still can't create a release.
 if: ${{ inputs.github && !inputs.smoke }}
 runs-on: ubuntu-latest
 needs: [get-version, build-nugetlibrary, build-pypilibrary, build-executable, build-docker]
 needs: [get-version, validate-release, build-nugetlibrary, build-pypilibrary, build-executable, build-docker]

 steps:

Expand All@@ -140,21 +167,6 @@ jobs:
 with:
 ref: ${{ needs.get-version.outputs.GitCommitId }}

 # Backstop (main only): a public release must not carry a prerelease '-', guarding against NBGV mis-versioning the
 # public ref (e.g. a dispatch on a non-default ref) into a malformed "Latest" release. Strip '+buildmetadata'
 # first - a '-' there is legitimate; only a '-' in the core/prerelease segment marks a prerelease.
 - name: Verify public release version step
 if: ${{ inputs.branch == 'main' }}
 env:
 SEMVER2: ${{ needs.get-version.outputs.SemVer2 }}
 run: |
 set -euo pipefail
 CORE_AND_PRE="${SEMVER2%%+*}" # drop +buildmetadata; a '-' here is the genuine prerelease separator
 if [[ "$CORE_AND_PRE" == *-* ]]; then
 echo "::error::Public (main) release version '$SEMVER2' carries a prerelease suffix; refusing to publish."
 exit 1
 fi

 # Collect assets by the `release-asset-<branch>-*` pattern so this step is target-agnostic: subset releases by
 # deleting the target, not `enable_*: false` (a skipped `needs` job would skip this release job too). The release
 # step guards `fail_on_unmatched_files: true`, so at least one `release-asset-*` must match; a repo that drops
Expand Down

11 changes: 11 additions & 0 deletions
.github/workflows/get-version-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,6 +9,12 @@ on:
 required: false
 type: string
 default: ''
 # Logical branch NBGV classifies against. Pins PublicRelease to this branch instead of the runner's GITHUB_REF,
 # which on a publish dispatched from the default branch is that branch for every matrix leg. Empty keeps GITHUB_REF.
 branch:
 required: false
 type: string
 default: ''
 outputs:
 SemVer2:
 value: ${{ jobs.get-version.outputs.SemVer2 }}
Expand DownExpand Up@@ -52,3 +58,8 @@ jobs:
 - name: Run Nerdbank.GitVersioning tool step
 id: nbgv
 uses: dotnet/nbgv@master
 env:
 # NBGV reads the branch from GITHUB_REF; pin it to the leg being versioned so a publish dispatched from the
 # default branch doesn't classify every leg as the public ref and strip its prerelease suffix.
 GITHUB_REF: ${{ inputs.branch != '' && format('refs/heads/{0}', inputs.branch) || github.ref }}
 GITHUB_REF_NAME: ${{ inputs.branch != '' && inputs.branch || github.ref_name }}

1 change: 1 addition & 0 deletions
AGENTS.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -192,6 +192,7 @@ These conventions describe the target state. New and modified workflows must res
- **Shells**: multi-line `run:` blocks with bash start with `set -euo pipefail` - fail fast, fail on undefined vars, fail on a failed pipe segment.
- **Conditionals**: multi-line `if:` uses folded scalar `if: >-` so YAML preserves whitespace correctly. Literal block (`if: |`) is wrong because it embeds newlines inside the boolean expression.
- **Boolean inputs**: workflows triggered both via `workflow_call` and `workflow_dispatch` must declare each boolean input in *both* trigger blocks - one definition does not propagate to the other. `workflow_call` delivers booleans as actual booleans; `workflow_dispatch` delivers them as the *strings* `"true"`/`"false"`. Any `if:` consuming a boolean input must compare against both forms - `if: ${{ inputs.foo == true || inputs.foo == 'true' }}`.
- **Validate input/state consistency at entry, fail fast**: when a workflow's inputs must satisfy a cross-input or input-versus-derived-state invariant (e.g. the release branch must match the computed version's prerelease status, or two inputs are mutually exclusive), assert it **once** in a dedicated entry validation step/job that the downstream jobs `needs:`, before any expensive build or publish work - not as partial checks scattered deep in later jobs. One gate that fails fast with a clear `::error::` beats a late or one-directional check. Examples: [`build-release-task.yml`](./.github/workflows/build-release-task.yml)'s `validate-release` job (branch-versus-prerelease, both directions) and [`publish-docker-readme-task.yml`](./.github/workflows/publish-docker-readme-task.yml)'s "Validate inputs step".
- **Reusable workflows**: job-level `permissions:` are validated *before* the `if:` evaluates, so even a skipped job needs valid permissions declared. A `release` job with `permissions: contents: write` and `if: ${{ inputs.publish }}` will still cause `startup_failure` on a caller that doesn't grant `contents: write`. Either declare permissions at the call site, or omit the inner block and inherit.
- **Allowlist `success` and `skipped` explicitly** when chaining jobs across optional dependencies - `!= 'failure'` lets `cancelled` through (timeout, runner failure, manual cancel). Use `(needs.X.result == 'success' || needs.X.result == 'skipped')`.
- **Artifact retention**: workflow artifacts are an intra-run handoff only - durable copies live on the GitHub release, not in workflow artifacts - so they must not survive the run and accumulate against the small account-wide artifact-storage quota. **Every workflow that can produce artifacts ends with a terminal `cleanup-artifacts` job** that deletes the run's artifacts via the REST API: `permissions: actions: write`, `needs` the artifact producers, an `if:` that **includes** `always()` (so a failed run still cleans up) plus any workflow-specific gate (e.g. `publish-release.yml` adds `&& needs.setup.outputs.publish == 'true'` to run only on real publishes), independent of any required status check so housekeeping never gates a merge, `continue-on-error: true` on the delete step so even an unexpected failure never reds the run, and tolerant of individual list/delete failures (warn and continue). This covers not just `actions/upload-artifact` but build-records that actions emit automatically (e.g. `docker/build-push-action`'s `.dockerbuild`). Both `publish-release.yml` and `test-pull-request.yml` carry one; add one to any new artifact-producing entry workflow. Set `retention-days: 1` on explicit uploads as a backstop.
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Version each publish leg against its own branch; validate at entry#215

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

ptr727
merged 1 commit into

from

Jun 26, 2026
 Merged


Version each publish leg against its own branch; validate at entry
#215
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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


1 change: 1 addition & 0 deletions
.github/workflows/build-docker-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -33,6 +33,7 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-docker:
 name: Build Docker image job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-executable-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,7 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-executable-matrix:
 name: Build executable project matrix job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-nugetlibrary-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,6 +32,7 @@ jobs:
 uses: ./.github/workflows/get-version-task.yml
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-nugetlibrary:
 name: Build NuGet library project job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-pypilibrary-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -36,6 +36,7 @@ jobs:
 uses: ./.github/workflows/get-version-task.yml
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-pypilibrary:
 name: Build PyPI library project job
Expand Down

52 changes: 32 additions & 20 deletions
.github/workflows/build-release-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -67,11 +67,38 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 # Entry gate: validate branch<->version consistency once, before the build jobs, so an NBGV mis-classification fails
 # fast instead of after building and publishing. main must be a public release (no prerelease '-'); every other branch
 # must carry a prerelease '-' (guards a develop leg being classified public and published as stable). Strip
 # '+buildmetadata' first; a '-' there is legitimate, only a '-' in the core/prerelease segment marks a prerelease.
 validate-release:
 name: Validate release version job
 needs: [get-version]
 runs-on: ubuntu-latest
 steps:
 - name: Validate branch and version consistency step
 env:
 SEMVER2: ${{ needs.get-version.outputs.SemVer2 }}
 BRANCH: ${{ inputs.branch }}
 run: |
 set -euo pipefail
 CORE_AND_PRE="${SEMVER2%%+*}"
 if [[ "$BRANCH" == "main" ]]; then
 if [[ "$CORE_AND_PRE" == *-* ]]; then
 echo "::error::Public (main) release version '$SEMVER2' carries a prerelease suffix; refusing to publish."
 exit 1
 fi
 elif [[ "$CORE_AND_PRE" != *-* ]]; then
 echo "::error::Prerelease ($BRANCH) version '$SEMVER2' has no prerelease suffix (NBGV classified it public); refusing to publish."
 exit 1
 fi

 build-nugetlibrary:
 name: Build NuGet library job
 if: ${{ inputs.enable_nuget }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-nugetlibrary-task.yml
 secrets: inherit
 with:
Expand All@@ -88,7 +115,7 @@ jobs:
 build-pypilibrary:
 name: Build PyPI library job
 if: ${{ inputs.enable_pypi }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-pypilibrary-task.yml
 secrets: inherit
 with:
Expand All@@ -101,7 +128,7 @@ jobs:
 build-executable:
 name: Build executable job
 if: ${{ inputs.enable_executable }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-executable-task.yml
 secrets: inherit
 with:
Expand All@@ -113,7 +140,7 @@ jobs:
 build-docker:
 name: Build Docker job
 if: ${{ inputs.enable_docker }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-docker-task.yml
 secrets: inherit
 with:
Expand All@@ -130,7 +157,7 @@ jobs:
 # `github: true` still can't create a release.
 if: ${{ inputs.github && !inputs.smoke }}
 runs-on: ubuntu-latest
 needs: [get-version, build-nugetlibrary, build-pypilibrary, build-executable, build-docker]
 needs: [get-version, validate-release, build-nugetlibrary, build-pypilibrary, build-executable, build-docker]

 steps:

Expand All@@ -140,21 +167,6 @@ jobs:
 with:
 ref: ${{ needs.get-version.outputs.GitCommitId }}

 # Backstop (main only): a public release must not carry a prerelease '-', guarding against NBGV mis-versioning the
 # public ref (e.g. a dispatch on a non-default ref) into a malformed "Latest" release. Strip '+buildmetadata'
 # first - a '-' there is legitimate; only a '-' in the core/prerelease segment marks a prerelease.
 - name: Verify public release version step
 if: ${{ inputs.branch == 'main' }}
 env:
 SEMVER2: ${{ needs.get-version.outputs.SemVer2 }}
 run: |
 set -euo pipefail
 CORE_AND_PRE="${SEMVER2%%+*}" # drop +buildmetadata; a '-' here is the genuine prerelease separator
 if [[ "$CORE_AND_PRE" == *-* ]]; then
 echo "::error::Public (main) release version '$SEMVER2' carries a prerelease suffix; refusing to publish."
 exit 1
 fi

 # Collect assets by the `release-asset-<branch>-*` pattern so this step is target-agnostic: subset releases by
 # deleting the target, not `enable_*: false` (a skipped `needs` job would skip this release job too). The release
 # step guards `fail_on_unmatched_files: true`, so at least one `release-asset-*` must match; a repo that drops
Expand Down

11 changes: 11 additions & 0 deletions
.github/workflows/get-version-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,6 +9,12 @@ on:
 required: false
 type: string
 default: ''
 # Logical branch NBGV classifies against. Pins PublicRelease to this branch instead of the runner's GITHUB_REF,
 # which on a publish dispatched from the default branch is that branch for every matrix leg. Empty keeps GITHUB_REF.
 branch:
 required: false
 type: string
 default: ''
 outputs:
 SemVer2:
 value: ${{ jobs.get-version.outputs.SemVer2 }}
Expand DownExpand Up@@ -52,3 +58,8 @@ jobs:
 - name: Run Nerdbank.GitVersioning tool step
 id: nbgv
 uses: dotnet/nbgv@master
 env:
 # NBGV reads the branch from GITHUB_REF; pin it to the leg being versioned so a publish dispatched from the
 # default branch doesn't classify every leg as the public ref and strip its prerelease suffix.
 GITHUB_REF: ${{ inputs.branch != '' && format('refs/heads/{0}', inputs.branch) || github.ref }}
 GITHUB_REF_NAME: ${{ inputs.branch != '' && inputs.branch || github.ref_name }}

1 change: 1 addition & 0 deletions
AGENTS.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -192,6 +192,7 @@ These conventions describe the target state. New and modified workflows must res
- **Shells**: multi-line `run:` blocks with bash start with `set -euo pipefail` - fail fast, fail on undefined vars, fail on a failed pipe segment.
- **Conditionals**: multi-line `if:` uses folded scalar `if: >-` so YAML preserves whitespace correctly. Literal block (`if: |`) is wrong because it embeds newlines inside the boolean expression.
- **Boolean inputs**: workflows triggered both via `workflow_call` and `workflow_dispatch` must declare each boolean input in *both* trigger blocks - one definition does not propagate to the other. `workflow_call` delivers booleans as actual booleans; `workflow_dispatch` delivers them as the *strings* `"true"`/`"false"`. Any `if:` consuming a boolean input must compare against both forms - `if: ${{ inputs.foo == true || inputs.foo == 'true' }}`.
- **Validate input/state consistency at entry, fail fast**: when a workflow's inputs must satisfy a cross-input or input-versus-derived-state invariant (e.g. the release branch must match the computed version's prerelease status, or two inputs are mutually exclusive), assert it **once** in a dedicated entry validation step/job that the downstream jobs `needs:`, before any expensive build or publish work - not as partial checks scattered deep in later jobs. One gate that fails fast with a clear `::error::` beats a late or one-directional check. Examples: [`build-release-task.yml`](./.github/workflows/build-release-task.yml)'s `validate-release` job (branch-versus-prerelease, both directions) and [`publish-docker-readme-task.yml`](./.github/workflows/publish-docker-readme-task.yml)'s "Validate inputs step".
- **Reusable workflows**: job-level `permissions:` are validated *before* the `if:` evaluates, so even a skipped job needs valid permissions declared. A `release` job with `permissions: contents: write` and `if: ${{ inputs.publish }}` will still cause `startup_failure` on a caller that doesn't grant `contents: write`. Either declare permissions at the call site, or omit the inner block and inherit.
- **Allowlist `success` and `skipped` explicitly** when chaining jobs across optional dependencies - `!= 'failure'` lets `cancelled` through (timeout, runner failure, manual cancel). Use `(needs.X.result == 'success' || needs.X.result == 'skipped')`.
- **Artifact retention**: workflow artifacts are an intra-run handoff only - durable copies live on the GitHub release, not in workflow artifacts - so they must not survive the run and accumulate against the small account-wide artifact-storage quota. **Every workflow that can produce artifacts ends with a terminal `cleanup-artifacts` job** that deletes the run's artifacts via the REST API: `permissions: actions: write`, `needs` the artifact producers, an `if:` that **includes** `always()` (so a failed run still cleans up) plus any workflow-specific gate (e.g. `publish-release.yml` adds `&& needs.setup.outputs.publish == 'true'` to run only on real publishes), independent of any required status check so housekeeping never gates a merge, `continue-on-error: true` on the delete step so even an unexpected failure never reds the run, and tolerant of individual list/delete failures (warn and continue). This covers not just `actions/upload-artifact` but build-records that actions emit automatically (e.g. `docker/build-push-action`'s `.dockerbuild`). Both `publish-release.yml` and `test-pull-request.yml` carry one; add one to any new artifact-producing entry workflow. Set `retention-days: 1` on explicit uploads as a backstop.
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Version each publish leg against its own branch; validate at entry#215

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

ptr727
merged 1 commit into

from

Jun 26, 2026
 Merged


Version each publish leg against its own branch; validate at entry
#215
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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


1 change: 1 addition & 0 deletions
.github/workflows/build-docker-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -33,6 +33,7 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-docker:
 name: Build Docker image job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-executable-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,7 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-executable-matrix:
 name: Build executable project matrix job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-nugetlibrary-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,6 +32,7 @@ jobs:
 uses: ./.github/workflows/get-version-task.yml
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-nugetlibrary:
 name: Build NuGet library project job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-pypilibrary-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -36,6 +36,7 @@ jobs:
 uses: ./.github/workflows/get-version-task.yml
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-pypilibrary:
 name: Build PyPI library project job
Expand Down

52 changes: 32 additions & 20 deletions
.github/workflows/build-release-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -67,11 +67,38 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 # Entry gate: validate branch<->version consistency once, before the build jobs, so an NBGV mis-classification fails
 # fast instead of after building and publishing. main must be a public release (no prerelease '-'); every other branch
 # must carry a prerelease '-' (guards a develop leg being classified public and published as stable). Strip
 # '+buildmetadata' first; a '-' there is legitimate, only a '-' in the core/prerelease segment marks a prerelease.
 validate-release:
 name: Validate release version job
 needs: [get-version]
 runs-on: ubuntu-latest
 steps:
 - name: Validate branch and version consistency step
 env:
 SEMVER2: ${{ needs.get-version.outputs.SemVer2 }}
 BRANCH: ${{ inputs.branch }}
 run: |
 set -euo pipefail
 CORE_AND_PRE="${SEMVER2%%+*}"
 if [[ "$BRANCH" == "main" ]]; then
 if [[ "$CORE_AND_PRE" == *-* ]]; then
 echo "::error::Public (main) release version '$SEMVER2' carries a prerelease suffix; refusing to publish."
 exit 1
 fi
 elif [[ "$CORE_AND_PRE" != *-* ]]; then
 echo "::error::Prerelease ($BRANCH) version '$SEMVER2' has no prerelease suffix (NBGV classified it public); refusing to publish."
 exit 1
 fi

 build-nugetlibrary:
 name: Build NuGet library job
 if: ${{ inputs.enable_nuget }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-nugetlibrary-task.yml
 secrets: inherit
 with:
Expand All@@ -88,7 +115,7 @@ jobs:
 build-pypilibrary:
 name: Build PyPI library job
 if: ${{ inputs.enable_pypi }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-pypilibrary-task.yml
 secrets: inherit
 with:
Expand All@@ -101,7 +128,7 @@ jobs:
 build-executable:
 name: Build executable job
 if: ${{ inputs.enable_executable }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-executable-task.yml
 secrets: inherit
 with:
Expand All@@ -113,7 +140,7 @@ jobs:
 build-docker:
 name: Build Docker job
 if: ${{ inputs.enable_docker }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-docker-task.yml
 secrets: inherit
 with:
Expand All@@ -130,7 +157,7 @@ jobs:
 # `github: true` still can't create a release.
 if: ${{ inputs.github && !inputs.smoke }}
 runs-on: ubuntu-latest
 needs: [get-version, build-nugetlibrary, build-pypilibrary, build-executable, build-docker]
 needs: [get-version, validate-release, build-nugetlibrary, build-pypilibrary, build-executable, build-docker]

 steps:

Expand All@@ -140,21 +167,6 @@ jobs:
 with:
 ref: ${{ needs.get-version.outputs.GitCommitId }}

 # Backstop (main only): a public release must not carry a prerelease '-', guarding against NBGV mis-versioning the
 # public ref (e.g. a dispatch on a non-default ref) into a malformed "Latest" release. Strip '+buildmetadata'
 # first - a '-' there is legitimate; only a '-' in the core/prerelease segment marks a prerelease.
 - name: Verify public release version step
 if: ${{ inputs.branch == 'main' }}
 env:
 SEMVER2: ${{ needs.get-version.outputs.SemVer2 }}
 run: |
 set -euo pipefail
 CORE_AND_PRE="${SEMVER2%%+*}" # drop +buildmetadata; a '-' here is the genuine prerelease separator
 if [[ "$CORE_AND_PRE" == *-* ]]; then
 echo "::error::Public (main) release version '$SEMVER2' carries a prerelease suffix; refusing to publish."
 exit 1
 fi

 # Collect assets by the `release-asset-<branch>-*` pattern so this step is target-agnostic: subset releases by
 # deleting the target, not `enable_*: false` (a skipped `needs` job would skip this release job too). The release
 # step guards `fail_on_unmatched_files: true`, so at least one `release-asset-*` must match; a repo that drops
Expand Down

11 changes: 11 additions & 0 deletions
.github/workflows/get-version-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,6 +9,12 @@ on:
 required: false
 type: string
 default: ''
 # Logical branch NBGV classifies against. Pins PublicRelease to this branch instead of the runner's GITHUB_REF,
 # which on a publish dispatched from the default branch is that branch for every matrix leg. Empty keeps GITHUB_REF.
 branch:
 required: false
 type: string
 default: ''
 outputs:
 SemVer2:
 value: ${{ jobs.get-version.outputs.SemVer2 }}
Expand DownExpand Up@@ -52,3 +58,8 @@ jobs:
 - name: Run Nerdbank.GitVersioning tool step
 id: nbgv
 uses: dotnet/nbgv@master
 env:
 # NBGV reads the branch from GITHUB_REF; pin it to the leg being versioned so a publish dispatched from the
 # default branch doesn't classify every leg as the public ref and strip its prerelease suffix.
 GITHUB_REF: ${{ inputs.branch != '' && format('refs/heads/{0}', inputs.branch) || github.ref }}
 GITHUB_REF_NAME: ${{ inputs.branch != '' && inputs.branch || github.ref_name }}

1 change: 1 addition & 0 deletions
AGENTS.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -192,6 +192,7 @@ These conventions describe the target state. New and modified workflows must res
- **Shells**: multi-line `run:` blocks with bash start with `set -euo pipefail` - fail fast, fail on undefined vars, fail on a failed pipe segment.
- **Conditionals**: multi-line `if:` uses folded scalar `if: >-` so YAML preserves whitespace correctly. Literal block (`if: |`) is wrong because it embeds newlines inside the boolean expression.
- **Boolean inputs**: workflows triggered both via `workflow_call` and `workflow_dispatch` must declare each boolean input in *both* trigger blocks - one definition does not propagate to the other. `workflow_call` delivers booleans as actual booleans; `workflow_dispatch` delivers them as the *strings* `"true"`/`"false"`. Any `if:` consuming a boolean input must compare against both forms - `if: ${{ inputs.foo == true || inputs.foo == 'true' }}`.
- **Validate input/state consistency at entry, fail fast**: when a workflow's inputs must satisfy a cross-input or input-versus-derived-state invariant (e.g. the release branch must match the computed version's prerelease status, or two inputs are mutually exclusive), assert it **once** in a dedicated entry validation step/job that the downstream jobs `needs:`, before any expensive build or publish work - not as partial checks scattered deep in later jobs. One gate that fails fast with a clear `::error::` beats a late or one-directional check. Examples: [`build-release-task.yml`](./.github/workflows/build-release-task.yml)'s `validate-release` job (branch-versus-prerelease, both directions) and [`publish-docker-readme-task.yml`](./.github/workflows/publish-docker-readme-task.yml)'s "Validate inputs step".
- **Reusable workflows**: job-level `permissions:` are validated *before* the `if:` evaluates, so even a skipped job needs valid permissions declared. A `release` job with `permissions: contents: write` and `if: ${{ inputs.publish }}` will still cause `startup_failure` on a caller that doesn't grant `contents: write`. Either declare permissions at the call site, or omit the inner block and inherit.
- **Allowlist `success` and `skipped` explicitly** when chaining jobs across optional dependencies - `!= 'failure'` lets `cancelled` through (timeout, runner failure, manual cancel). Use `(needs.X.result == 'success' || needs.X.result == 'skipped')`.
- **Artifact retention**: workflow artifacts are an intra-run handoff only - durable copies live on the GitHub release, not in workflow artifacts - so they must not survive the run and accumulate against the small account-wide artifact-storage quota. **Every workflow that can produce artifacts ends with a terminal `cleanup-artifacts` job** that deletes the run's artifacts via the REST API: `permissions: actions: write`, `needs` the artifact producers, an `if:` that **includes** `always()` (so a failed run still cleans up) plus any workflow-specific gate (e.g. `publish-release.yml` adds `&& needs.setup.outputs.publish == 'true'` to run only on real publishes), independent of any required status check so housekeeping never gates a merge, `continue-on-error: true` on the delete step so even an unexpected failure never reds the run, and tolerant of individual list/delete failures (warn and continue). This covers not just `actions/upload-artifact` but build-records that actions emit automatically (e.g. `docker/build-push-action`'s `.dockerbuild`). Both `publish-release.yml` and `test-pull-request.yml` carry one; add one to any new artifact-producing entry workflow. Set `retention-days: 1` on explicit uploads as a backstop.
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
Version each publish leg against its own branch; validate at entry#215

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

ptr727
merged 1 commit into

from

Jun 26, 2026
 Merged


Version each publish leg against its own branch; validate at entry
#215
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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


1 change: 1 addition & 0 deletions
.github/workflows/build-docker-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -33,6 +33,7 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-docker:
 name: Build Docker image job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-executable-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,7 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-executable-matrix:
 name: Build executable project matrix job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-nugetlibrary-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,6 +32,7 @@ jobs:
 uses: ./.github/workflows/get-version-task.yml
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-nugetlibrary:
 name: Build NuGet library project job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-pypilibrary-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -36,6 +36,7 @@ jobs:
 uses: ./.github/workflows/get-version-task.yml
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-pypilibrary:
 name: Build PyPI library project job
Expand Down

52 changes: 32 additions & 20 deletions
.github/workflows/build-release-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -67,11 +67,38 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 # Entry gate: validate branch<->version consistency once, before the build jobs, so an NBGV mis-classification fails
 # fast instead of after building and publishing. main must be a public release (no prerelease '-'); every other branch
 # must carry a prerelease '-' (guards a develop leg being classified public and published as stable). Strip
 # '+buildmetadata' first; a '-' there is legitimate, only a '-' in the core/prerelease segment marks a prerelease.
 validate-release:
 name: Validate release version job
 needs: [get-version]
 runs-on: ubuntu-latest
 steps:
 - name: Validate branch and version consistency step
 env:
 SEMVER2: ${{ needs.get-version.outputs.SemVer2 }}
 BRANCH: ${{ inputs.branch }}
 run: |
 set -euo pipefail
 CORE_AND_PRE="${SEMVER2%%+*}"
 if [[ "$BRANCH" == "main" ]]; then
 if [[ "$CORE_AND_PRE" == *-* ]]; then
 echo "::error::Public (main) release version '$SEMVER2' carries a prerelease suffix; refusing to publish."
 exit 1
 fi
 elif [[ "$CORE_AND_PRE" != *-* ]]; then
 echo "::error::Prerelease ($BRANCH) version '$SEMVER2' has no prerelease suffix (NBGV classified it public); refusing to publish."
 exit 1
 fi

 build-nugetlibrary:
 name: Build NuGet library job
 if: ${{ inputs.enable_nuget }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-nugetlibrary-task.yml
 secrets: inherit
 with:
Expand All@@ -88,7 +115,7 @@ jobs:
 build-pypilibrary:
 name: Build PyPI library job
 if: ${{ inputs.enable_pypi }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-pypilibrary-task.yml
 secrets: inherit
 with:
Expand All@@ -101,7 +128,7 @@ jobs:
 build-executable:
 name: Build executable job
 if: ${{ inputs.enable_executable }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-executable-task.yml
 secrets: inherit
 with:
Expand All@@ -113,7 +140,7 @@ jobs:
 build-docker:
 name: Build Docker job
 if: ${{ inputs.enable_docker }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-docker-task.yml
 secrets: inherit
 with:
Expand All@@ -130,7 +157,7 @@ jobs:
 # `github: true` still can't create a release.
 if: ${{ inputs.github && !inputs.smoke }}
 runs-on: ubuntu-latest
 needs: [get-version, build-nugetlibrary, build-pypilibrary, build-executable, build-docker]
 needs: [get-version, validate-release, build-nugetlibrary, build-pypilibrary, build-executable, build-docker]

 steps:

Expand All@@ -140,21 +167,6 @@ jobs:
 with:
 ref: ${{ needs.get-version.outputs.GitCommitId }}

 # Backstop (main only): a public release must not carry a prerelease '-', guarding against NBGV mis-versioning the
 # public ref (e.g. a dispatch on a non-default ref) into a malformed "Latest" release. Strip '+buildmetadata'
 # first - a '-' there is legitimate; only a '-' in the core/prerelease segment marks a prerelease.
 - name: Verify public release version step
 if: ${{ inputs.branch == 'main' }}
 env:
 SEMVER2: ${{ needs.get-version.outputs.SemVer2 }}
 run: |
 set -euo pipefail
 CORE_AND_PRE="${SEMVER2%%+*}" # drop +buildmetadata; a '-' here is the genuine prerelease separator
 if [[ "$CORE_AND_PRE" == *-* ]]; then
 echo "::error::Public (main) release version '$SEMVER2' carries a prerelease suffix; refusing to publish."
 exit 1
 fi

 # Collect assets by the `release-asset-<branch>-*` pattern so this step is target-agnostic: subset releases by
 # deleting the target, not `enable_*: false` (a skipped `needs` job would skip this release job too). The release
 # step guards `fail_on_unmatched_files: true`, so at least one `release-asset-*` must match; a repo that drops
Expand Down

11 changes: 11 additions & 0 deletions
.github/workflows/get-version-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,6 +9,12 @@ on:
 required: false
 type: string
 default: ''
 # Logical branch NBGV classifies against. Pins PublicRelease to this branch instead of the runner's GITHUB_REF,
 # which on a publish dispatched from the default branch is that branch for every matrix leg. Empty keeps GITHUB_REF.
 branch:
 required: false
 type: string
 default: ''
 outputs:
 SemVer2:
 value: ${{ jobs.get-version.outputs.SemVer2 }}
Expand DownExpand Up@@ -52,3 +58,8 @@ jobs:
 - name: Run Nerdbank.GitVersioning tool step
 id: nbgv
 uses: dotnet/nbgv@master
 env:
 # NBGV reads the branch from GITHUB_REF; pin it to the leg being versioned so a publish dispatched from the
 # default branch doesn't classify every leg as the public ref and strip its prerelease suffix.
 GITHUB_REF: ${{ inputs.branch != '' && format('refs/heads/{0}', inputs.branch) || github.ref }}
 GITHUB_REF_NAME: ${{ inputs.branch != '' && inputs.branch || github.ref_name }}

1 change: 1 addition & 0 deletions
AGENTS.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -192,6 +192,7 @@ These conventions describe the target state. New and modified workflows must res
- **Shells**: multi-line `run:` blocks with bash start with `set -euo pipefail` - fail fast, fail on undefined vars, fail on a failed pipe segment.
- **Conditionals**: multi-line `if:` uses folded scalar `if: >-` so YAML preserves whitespace correctly. Literal block (`if: |`) is wrong because it embeds newlines inside the boolean expression.
- **Boolean inputs**: workflows triggered both via `workflow_call` and `workflow_dispatch` must declare each boolean input in *both* trigger blocks - one definition does not propagate to the other. `workflow_call` delivers booleans as actual booleans; `workflow_dispatch` delivers them as the *strings* `"true"`/`"false"`. Any `if:` consuming a boolean input must compare against both forms - `if: ${{ inputs.foo == true || inputs.foo == 'true' }}`.
- **Validate input/state consistency at entry, fail fast**: when a workflow's inputs must satisfy a cross-input or input-versus-derived-state invariant (e.g. the release branch must match the computed version's prerelease status, or two inputs are mutually exclusive), assert it **once** in a dedicated entry validation step/job that the downstream jobs `needs:`, before any expensive build or publish work - not as partial checks scattered deep in later jobs. One gate that fails fast with a clear `::error::` beats a late or one-directional check. Examples: [`build-release-task.yml`](./.github/workflows/build-release-task.yml)'s `validate-release` job (branch-versus-prerelease, both directions) and [`publish-docker-readme-task.yml`](./.github/workflows/publish-docker-readme-task.yml)'s "Validate inputs step".
- **Reusable workflows**: job-level `permissions:` are validated *before* the `if:` evaluates, so even a skipped job needs valid permissions declared. A `release` job with `permissions: contents: write` and `if: ${{ inputs.publish }}` will still cause `startup_failure` on a caller that doesn't grant `contents: write`. Either declare permissions at the call site, or omit the inner block and inherit.
- **Allowlist `success` and `skipped` explicitly** when chaining jobs across optional dependencies - `!= 'failure'` lets `cancelled` through (timeout, runner failure, manual cancel). Use `(needs.X.result == 'success' || needs.X.result == 'skipped')`.
- **Artifact retention**: workflow artifacts are an intra-run handoff only - durable copies live on the GitHub release, not in workflow artifacts - so they must not survive the run and accumulate against the small account-wide artifact-storage quota. **Every workflow that can produce artifacts ends with a terminal `cleanup-artifacts` job** that deletes the run's artifacts via the REST API: `permissions: actions: write`, `needs` the artifact producers, an `if:` that **includes** `always()` (so a failed run still cleans up) plus any workflow-specific gate (e.g. `publish-release.yml` adds `&& needs.setup.outputs.publish == 'true'` to run only on real publishes), independent of any required status check so housekeeping never gates a merge, `continue-on-error: true` on the delete step so even an unexpected failure never reds the run, and tolerant of individual list/delete failures (warn and continue). This covers not just `actions/upload-artifact` but build-records that actions emit automatically (e.g. `docker/build-push-action`'s `.dockerbuild`). Both `publish-release.yml` and `test-pull-request.yml` carry one; add one to any new artifact-producing entry workflow. Set `retention-days: 1` on explicit uploads as a backstop.
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Version each publish leg against its own branch; validate at entry#215

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

ptr727
merged 1 commit into

from

Jun 26, 2026
 Merged


Version each publish leg against its own branch; validate at entry
#215
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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


1 change: 1 addition & 0 deletions
.github/workflows/build-docker-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -33,6 +33,7 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-docker:
 name: Build Docker image job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-executable-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,7 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-executable-matrix:
 name: Build executable project matrix job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-nugetlibrary-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,6 +32,7 @@ jobs:
 uses: ./.github/workflows/get-version-task.yml
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-nugetlibrary:
 name: Build NuGet library project job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-pypilibrary-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -36,6 +36,7 @@ jobs:
 uses: ./.github/workflows/get-version-task.yml
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-pypilibrary:
 name: Build PyPI library project job
Expand Down

52 changes: 32 additions & 20 deletions
.github/workflows/build-release-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -67,11 +67,38 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 # Entry gate: validate branch<->version consistency once, before the build jobs, so an NBGV mis-classification fails
 # fast instead of after building and publishing. main must be a public release (no prerelease '-'); every other branch
 # must carry a prerelease '-' (guards a develop leg being classified public and published as stable). Strip
 # '+buildmetadata' first; a '-' there is legitimate, only a '-' in the core/prerelease segment marks a prerelease.
 validate-release:
 name: Validate release version job
 needs: [get-version]
 runs-on: ubuntu-latest
 steps:
 - name: Validate branch and version consistency step
 env:
 SEMVER2: ${{ needs.get-version.outputs.SemVer2 }}
 BRANCH: ${{ inputs.branch }}
 run: |
 set -euo pipefail
 CORE_AND_PRE="${SEMVER2%%+*}"
 if [[ "$BRANCH" == "main" ]]; then
 if [[ "$CORE_AND_PRE" == *-* ]]; then
 echo "::error::Public (main) release version '$SEMVER2' carries a prerelease suffix; refusing to publish."
 exit 1
 fi
 elif [[ "$CORE_AND_PRE" != *-* ]]; then
 echo "::error::Prerelease ($BRANCH) version '$SEMVER2' has no prerelease suffix (NBGV classified it public); refusing to publish."
 exit 1
 fi

 build-nugetlibrary:
 name: Build NuGet library job
 if: ${{ inputs.enable_nuget }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-nugetlibrary-task.yml
 secrets: inherit
 with:
Expand All@@ -88,7 +115,7 @@ jobs:
 build-pypilibrary:
 name: Build PyPI library job
 if: ${{ inputs.enable_pypi }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-pypilibrary-task.yml
 secrets: inherit
 with:
Expand All@@ -101,7 +128,7 @@ jobs:
 build-executable:
 name: Build executable job
 if: ${{ inputs.enable_executable }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-executable-task.yml
 secrets: inherit
 with:
Expand All@@ -113,7 +140,7 @@ jobs:
 build-docker:
 name: Build Docker job
 if: ${{ inputs.enable_docker }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-docker-task.yml
 secrets: inherit
 with:
Expand All@@ -130,7 +157,7 @@ jobs:
 # `github: true` still can't create a release.
 if: ${{ inputs.github && !inputs.smoke }}
 runs-on: ubuntu-latest
 needs: [get-version, build-nugetlibrary, build-pypilibrary, build-executable, build-docker]
 needs: [get-version, validate-release, build-nugetlibrary, build-pypilibrary, build-executable, build-docker]

 steps:

Expand All@@ -140,21 +167,6 @@ jobs:
 with:
 ref: ${{ needs.get-version.outputs.GitCommitId }}

 # Backstop (main only): a public release must not carry a prerelease '-', guarding against NBGV mis-versioning the
 # public ref (e.g. a dispatch on a non-default ref) into a malformed "Latest" release. Strip '+buildmetadata'
 # first - a '-' there is legitimate; only a '-' in the core/prerelease segment marks a prerelease.
 - name: Verify public release version step
 if: ${{ inputs.branch == 'main' }}
 env:
 SEMVER2: ${{ needs.get-version.outputs.SemVer2 }}
 run: |
 set -euo pipefail
 CORE_AND_PRE="${SEMVER2%%+*}" # drop +buildmetadata; a '-' here is the genuine prerelease separator
 if [[ "$CORE_AND_PRE" == *-* ]]; then
 echo "::error::Public (main) release version '$SEMVER2' carries a prerelease suffix; refusing to publish."
 exit 1
 fi

 # Collect assets by the `release-asset-<branch>-*` pattern so this step is target-agnostic: subset releases by
 # deleting the target, not `enable_*: false` (a skipped `needs` job would skip this release job too). The release
 # step guards `fail_on_unmatched_files: true`, so at least one `release-asset-*` must match; a repo that drops
Expand Down

11 changes: 11 additions & 0 deletions
.github/workflows/get-version-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,6 +9,12 @@ on:
 required: false
 type: string
 default: ''
 # Logical branch NBGV classifies against. Pins PublicRelease to this branch instead of the runner's GITHUB_REF,
 # which on a publish dispatched from the default branch is that branch for every matrix leg. Empty keeps GITHUB_REF.
 branch:
 required: false
 type: string
 default: ''
 outputs:
 SemVer2:
 value: ${{ jobs.get-version.outputs.SemVer2 }}
Expand DownExpand Up@@ -52,3 +58,8 @@ jobs:
 - name: Run Nerdbank.GitVersioning tool step
 id: nbgv
 uses: dotnet/nbgv@master
 env:
 # NBGV reads the branch from GITHUB_REF; pin it to the leg being versioned so a publish dispatched from the
 # default branch doesn't classify every leg as the public ref and strip its prerelease suffix.
 GITHUB_REF: ${{ inputs.branch != '' && format('refs/heads/{0}', inputs.branch) || github.ref }}
 GITHUB_REF_NAME: ${{ inputs.branch != '' && inputs.branch || github.ref_name }}

1 change: 1 addition & 0 deletions
AGENTS.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -192,6 +192,7 @@ These conventions describe the target state. New and modified workflows must res
- **Shells**: multi-line `run:` blocks with bash start with `set -euo pipefail` - fail fast, fail on undefined vars, fail on a failed pipe segment.
- **Conditionals**: multi-line `if:` uses folded scalar `if: >-` so YAML preserves whitespace correctly. Literal block (`if: |`) is wrong because it embeds newlines inside the boolean expression.
- **Boolean inputs**: workflows triggered both via `workflow_call` and `workflow_dispatch` must declare each boolean input in *both* trigger blocks - one definition does not propagate to the other. `workflow_call` delivers booleans as actual booleans; `workflow_dispatch` delivers them as the *strings* `"true"`/`"false"`. Any `if:` consuming a boolean input must compare against both forms - `if: ${{ inputs.foo == true || inputs.foo == 'true' }}`.
- **Validate input/state consistency at entry, fail fast**: when a workflow's inputs must satisfy a cross-input or input-versus-derived-state invariant (e.g. the release branch must match the computed version's prerelease status, or two inputs are mutually exclusive), assert it **once** in a dedicated entry validation step/job that the downstream jobs `needs:`, before any expensive build or publish work - not as partial checks scattered deep in later jobs. One gate that fails fast with a clear `::error::` beats a late or one-directional check. Examples: [`build-release-task.yml`](./.github/workflows/build-release-task.yml)'s `validate-release` job (branch-versus-prerelease, both directions) and [`publish-docker-readme-task.yml`](./.github/workflows/publish-docker-readme-task.yml)'s "Validate inputs step".
- **Reusable workflows**: job-level `permissions:` are validated *before* the `if:` evaluates, so even a skipped job needs valid permissions declared. A `release` job with `permissions: contents: write` and `if: ${{ inputs.publish }}` will still cause `startup_failure` on a caller that doesn't grant `contents: write`. Either declare permissions at the call site, or omit the inner block and inherit.
- **Allowlist `success` and `skipped` explicitly** when chaining jobs across optional dependencies - `!= 'failure'` lets `cancelled` through (timeout, runner failure, manual cancel). Use `(needs.X.result == 'success' || needs.X.result == 'skipped')`.
- **Artifact retention**: workflow artifacts are an intra-run handoff only - durable copies live on the GitHub release, not in workflow artifacts - so they must not survive the run and accumulate against the small account-wide artifact-storage quota. **Every workflow that can produce artifacts ends with a terminal `cleanup-artifacts` job** that deletes the run's artifacts via the REST API: `permissions: actions: write`, `needs` the artifact producers, an `if:` that **includes** `always()` (so a failed run still cleans up) plus any workflow-specific gate (e.g. `publish-release.yml` adds `&& needs.setup.outputs.publish == 'true'` to run only on real publishes), independent of any required status check so housekeeping never gates a merge, `continue-on-error: true` on the delete step so even an unexpected failure never reds the run, and tolerant of individual list/delete failures (warn and continue). This covers not just `actions/upload-artifact` but build-records that actions emit automatically (e.g. `docker/build-push-action`'s `.dockerbuild`). Both `publish-release.yml` and `test-pull-request.yml` carry one; add one to any new artifact-producing entry workflow. Set `retention-days: 1` on explicit uploads as a backstop.
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
Version each publish leg against its own branch; validate at entry#215

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

ptr727
merged 1 commit into

from

Jun 26, 2026
 Merged


Version each publish leg against its own branch; validate at entry
#215
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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


1 change: 1 addition & 0 deletions
.github/workflows/build-docker-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -33,6 +33,7 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-docker:
 name: Build Docker image job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-executable-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,7 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-executable-matrix:
 name: Build executable project matrix job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-nugetlibrary-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,6 +32,7 @@ jobs:
 uses: ./.github/workflows/get-version-task.yml
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-nugetlibrary:
 name: Build NuGet library project job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-pypilibrary-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -36,6 +36,7 @@ jobs:
 uses: ./.github/workflows/get-version-task.yml
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-pypilibrary:
 name: Build PyPI library project job
Expand Down

52 changes: 32 additions & 20 deletions
.github/workflows/build-release-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -67,11 +67,38 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 # Entry gate: validate branch<->version consistency once, before the build jobs, so an NBGV mis-classification fails
 # fast instead of after building and publishing. main must be a public release (no prerelease '-'); every other branch
 # must carry a prerelease '-' (guards a develop leg being classified public and published as stable). Strip
 # '+buildmetadata' first; a '-' there is legitimate, only a '-' in the core/prerelease segment marks a prerelease.
 validate-release:
 name: Validate release version job
 needs: [get-version]
 runs-on: ubuntu-latest
 steps:
 - name: Validate branch and version consistency step
 env:
 SEMVER2: ${{ needs.get-version.outputs.SemVer2 }}
 BRANCH: ${{ inputs.branch }}
 run: |
 set -euo pipefail
 CORE_AND_PRE="${SEMVER2%%+*}"
 if [[ "$BRANCH" == "main" ]]; then
 if [[ "$CORE_AND_PRE" == *-* ]]; then
 echo "::error::Public (main) release version '$SEMVER2' carries a prerelease suffix; refusing to publish."
 exit 1
 fi
 elif [[ "$CORE_AND_PRE" != *-* ]]; then
 echo "::error::Prerelease ($BRANCH) version '$SEMVER2' has no prerelease suffix (NBGV classified it public); refusing to publish."
 exit 1
 fi

 build-nugetlibrary:
 name: Build NuGet library job
 if: ${{ inputs.enable_nuget }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-nugetlibrary-task.yml
 secrets: inherit
 with:
Expand All@@ -88,7 +115,7 @@ jobs:
 build-pypilibrary:
 name: Build PyPI library job
 if: ${{ inputs.enable_pypi }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-pypilibrary-task.yml
 secrets: inherit
 with:
Expand All@@ -101,7 +128,7 @@ jobs:
 build-executable:
 name: Build executable job
 if: ${{ inputs.enable_executable }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-executable-task.yml
 secrets: inherit
 with:
Expand All@@ -113,7 +140,7 @@ jobs:
 build-docker:
 name: Build Docker job
 if: ${{ inputs.enable_docker }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-docker-task.yml
 secrets: inherit
 with:
Expand All@@ -130,7 +157,7 @@ jobs:
 # `github: true` still can't create a release.
 if: ${{ inputs.github && !inputs.smoke }}
 runs-on: ubuntu-latest
 needs: [get-version, build-nugetlibrary, build-pypilibrary, build-executable, build-docker]
 needs: [get-version, validate-release, build-nugetlibrary, build-pypilibrary, build-executable, build-docker]

 steps:

Expand All@@ -140,21 +167,6 @@ jobs:
 with:
 ref: ${{ needs.get-version.outputs.GitCommitId }}

 # Backstop (main only): a public release must not carry a prerelease '-', guarding against NBGV mis-versioning the
 # public ref (e.g. a dispatch on a non-default ref) into a malformed "Latest" release. Strip '+buildmetadata'
 # first - a '-' there is legitimate; only a '-' in the core/prerelease segment marks a prerelease.
 - name: Verify public release version step
 if: ${{ inputs.branch == 'main' }}
 env:
 SEMVER2: ${{ needs.get-version.outputs.SemVer2 }}
 run: |
 set -euo pipefail
 CORE_AND_PRE="${SEMVER2%%+*}" # drop +buildmetadata; a '-' here is the genuine prerelease separator
 if [[ "$CORE_AND_PRE" == *-* ]]; then
 echo "::error::Public (main) release version '$SEMVER2' carries a prerelease suffix; refusing to publish."
 exit 1
 fi

 # Collect assets by the `release-asset-<branch>-*` pattern so this step is target-agnostic: subset releases by
 # deleting the target, not `enable_*: false` (a skipped `needs` job would skip this release job too). The release
 # step guards `fail_on_unmatched_files: true`, so at least one `release-asset-*` must match; a repo that drops
Expand Down

11 changes: 11 additions & 0 deletions
.github/workflows/get-version-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,6 +9,12 @@ on:
 required: false
 type: string
 default: ''
 # Logical branch NBGV classifies against. Pins PublicRelease to this branch instead of the runner's GITHUB_REF,
 # which on a publish dispatched from the default branch is that branch for every matrix leg. Empty keeps GITHUB_REF.
 branch:
 required: false
 type: string
 default: ''
 outputs:
 SemVer2:
 value: ${{ jobs.get-version.outputs.SemVer2 }}
Expand DownExpand Up@@ -52,3 +58,8 @@ jobs:
 - name: Run Nerdbank.GitVersioning tool step
 id: nbgv
 uses: dotnet/nbgv@master
 env:
 # NBGV reads the branch from GITHUB_REF; pin it to the leg being versioned so a publish dispatched from the
 # default branch doesn't classify every leg as the public ref and strip its prerelease suffix.
 GITHUB_REF: ${{ inputs.branch != '' && format('refs/heads/{0}', inputs.branch) || github.ref }}
 GITHUB_REF_NAME: ${{ inputs.branch != '' && inputs.branch || github.ref_name }}

1 change: 1 addition & 0 deletions
AGENTS.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -192,6 +192,7 @@ These conventions describe the target state. New and modified workflows must res
- **Shells**: multi-line `run:` blocks with bash start with `set -euo pipefail` - fail fast, fail on undefined vars, fail on a failed pipe segment.
- **Conditionals**: multi-line `if:` uses folded scalar `if: >-` so YAML preserves whitespace correctly. Literal block (`if: |`) is wrong because it embeds newlines inside the boolean expression.
- **Boolean inputs**: workflows triggered both via `workflow_call` and `workflow_dispatch` must declare each boolean input in *both* trigger blocks - one definition does not propagate to the other. `workflow_call` delivers booleans as actual booleans; `workflow_dispatch` delivers them as the *strings* `"true"`/`"false"`. Any `if:` consuming a boolean input must compare against both forms - `if: ${{ inputs.foo == true || inputs.foo == 'true' }}`.
- **Validate input/state consistency at entry, fail fast**: when a workflow's inputs must satisfy a cross-input or input-versus-derived-state invariant (e.g. the release branch must match the computed version's prerelease status, or two inputs are mutually exclusive), assert it **once** in a dedicated entry validation step/job that the downstream jobs `needs:`, before any expensive build or publish work - not as partial checks scattered deep in later jobs. One gate that fails fast with a clear `::error::` beats a late or one-directional check. Examples: [`build-release-task.yml`](./.github/workflows/build-release-task.yml)'s `validate-release` job (branch-versus-prerelease, both directions) and [`publish-docker-readme-task.yml`](./.github/workflows/publish-docker-readme-task.yml)'s "Validate inputs step".
- **Reusable workflows**: job-level `permissions:` are validated *before* the `if:` evaluates, so even a skipped job needs valid permissions declared. A `release` job with `permissions: contents: write` and `if: ${{ inputs.publish }}` will still cause `startup_failure` on a caller that doesn't grant `contents: write`. Either declare permissions at the call site, or omit the inner block and inherit.
- **Allowlist `success` and `skipped` explicitly** when chaining jobs across optional dependencies - `!= 'failure'` lets `cancelled` through (timeout, runner failure, manual cancel). Use `(needs.X.result == 'success' || needs.X.result == 'skipped')`.
- **Artifact retention**: workflow artifacts are an intra-run handoff only - durable copies live on the GitHub release, not in workflow artifacts - so they must not survive the run and accumulate against the small account-wide artifact-storage quota. **Every workflow that can produce artifacts ends with a terminal `cleanup-artifacts` job** that deletes the run's artifacts via the REST API: `permissions: actions: write`, `needs` the artifact producers, an `if:` that **includes** `always()` (so a failed run still cleans up) plus any workflow-specific gate (e.g. `publish-release.yml` adds `&& needs.setup.outputs.publish == 'true'` to run only on real publishes), independent of any required status check so housekeeping never gates a merge, `continue-on-error: true` on the delete step so even an unexpected failure never reds the run, and tolerant of individual list/delete failures (warn and continue). This covers not just `actions/upload-artifact` but build-records that actions emit automatically (e.g. `docker/build-push-action`'s `.dockerbuild`). Both `publish-release.yml` and `test-pull-request.yml` carry one; add one to any new artifact-producing entry workflow. Set `retention-days: 1` on explicit uploads as a backstop.
Expand Down

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
Version each publish leg against its own branch; validate at entry#215

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

ptr727
merged 1 commit into

from

Jun 26, 2026
 Merged


Version each publish leg against its own branch; validate at entry
#215
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


1 commit


Select commit


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


1 change: 1 addition & 0 deletions
.github/workflows/build-docker-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -33,6 +33,7 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-docker:
 name: Build Docker image job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-executable-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -28,6 +28,7 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-executable-matrix:
 name: Build executable project matrix job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-nugetlibrary-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -32,6 +32,7 @@ jobs:
 uses: ./.github/workflows/get-version-task.yml
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-nugetlibrary:
 name: Build NuGet library project job
Expand Down

1 change: 1 addition & 0 deletions
.github/workflows/build-pypilibrary-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -36,6 +36,7 @@ jobs:
 uses: ./.github/workflows/get-version-task.yml
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 build-pypilibrary:
 name: Build PyPI library project job
Expand Down

52 changes: 32 additions & 20 deletions
.github/workflows/build-release-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -67,11 +67,38 @@ jobs:
 secrets: inherit
 with:
 ref: ${{ inputs.ref }}
 branch: ${{ inputs.branch }}

 # Entry gate: validate branch<->version consistency once, before the build jobs, so an NBGV mis-classification fails
 # fast instead of after building and publishing. main must be a public release (no prerelease '-'); every other branch
 # must carry a prerelease '-' (guards a develop leg being classified public and published as stable). Strip
 # '+buildmetadata' first; a '-' there is legitimate, only a '-' in the core/prerelease segment marks a prerelease.
 validate-release:
 name: Validate release version job
 needs: [get-version]
 runs-on: ubuntu-latest
 steps:
 - name: Validate branch and version consistency step
 env:
 SEMVER2: ${{ needs.get-version.outputs.SemVer2 }}
 BRANCH: ${{ inputs.branch }}
 run: |
 set -euo pipefail
 CORE_AND_PRE="${SEMVER2%%+*}"
 if [[ "$BRANCH" == "main" ]]; then
 if [[ "$CORE_AND_PRE" == *-* ]]; then
 echo "::error::Public (main) release version '$SEMVER2' carries a prerelease suffix; refusing to publish."
 exit 1
 fi
 elif [[ "$CORE_AND_PRE" != *-* ]]; then
 echo "::error::Prerelease ($BRANCH) version '$SEMVER2' has no prerelease suffix (NBGV classified it public); refusing to publish."
 exit 1
 fi

 build-nugetlibrary:
 name: Build NuGet library job
 if: ${{ inputs.enable_nuget }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-nugetlibrary-task.yml
 secrets: inherit
 with:
Expand All@@ -88,7 +115,7 @@ jobs:
 build-pypilibrary:
 name: Build PyPI library job
 if: ${{ inputs.enable_pypi }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-pypilibrary-task.yml
 secrets: inherit
 with:
Expand All@@ -101,7 +128,7 @@ jobs:
 build-executable:
 name: Build executable job
 if: ${{ inputs.enable_executable }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-executable-task.yml
 secrets: inherit
 with:
Expand All@@ -113,7 +140,7 @@ jobs:
 build-docker:
 name: Build Docker job
 if: ${{ inputs.enable_docker }}
 needs: [get-version]
 needs: [get-version, validate-release]
 uses: ./.github/workflows/build-docker-task.yml
 secrets: inherit
 with:
Expand All@@ -130,7 +157,7 @@ jobs:
 # `github: true` still can't create a release.
 if: ${{ inputs.github && !inputs.smoke }}
 runs-on: ubuntu-latest
 needs: [get-version, build-nugetlibrary, build-pypilibrary, build-executable, build-docker]
 needs: [get-version, validate-release, build-nugetlibrary, build-pypilibrary, build-executable, build-docker]

 steps:

Expand All@@ -140,21 +167,6 @@ jobs:
 with:
 ref: ${{ needs.get-version.outputs.GitCommitId }}

 # Backstop (main only): a public release must not carry a prerelease '-', guarding against NBGV mis-versioning the
 # public ref (e.g. a dispatch on a non-default ref) into a malformed "Latest" release. Strip '+buildmetadata'
 # first - a '-' there is legitimate; only a '-' in the core/prerelease segment marks a prerelease.
 - name: Verify public release version step
 if: ${{ inputs.branch == 'main' }}
 env:
 SEMVER2: ${{ needs.get-version.outputs.SemVer2 }}
 run: |
 set -euo pipefail
 CORE_AND_PRE="${SEMVER2%%+*}" # drop +buildmetadata; a '-' here is the genuine prerelease separator
 if [[ "$CORE_AND_PRE" == *-* ]]; then
 echo "::error::Public (main) release version '$SEMVER2' carries a prerelease suffix; refusing to publish."
 exit 1
 fi

 # Collect assets by the `release-asset-<branch>-*` pattern so this step is target-agnostic: subset releases by
 # deleting the target, not `enable_*: false` (a skipped `needs` job would skip this release job too). The release
 # step guards `fail_on_unmatched_files: true`, so at least one `release-asset-*` must match; a repo that drops
Expand Down

11 changes: 11 additions & 0 deletions
.github/workflows/get-version-task.yml

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -9,6 +9,12 @@ on:
 required: false
 type: string
 default: ''
 # Logical branch NBGV classifies against. Pins PublicRelease to this branch instead of the runner's GITHUB_REF,
 # which on a publish dispatched from the default branch is that branch for every matrix leg. Empty keeps GITHUB_REF.
 branch:
 required: false
 type: string
 default: ''
 outputs:
 SemVer2:
 value: ${{ jobs.get-version.outputs.SemVer2 }}
Expand DownExpand Up@@ -52,3 +58,8 @@ jobs:
 - name: Run Nerdbank.GitVersioning tool step
 id: nbgv
 uses: dotnet/nbgv@master
 env:
 # NBGV reads the branch from GITHUB_REF; pin it to the leg being versioned so a publish dispatched from the
 # default branch doesn't classify every leg as the public ref and strip its prerelease suffix.
 GITHUB_REF: ${{ inputs.branch != '' && format('refs/heads/{0}', inputs.branch) || github.ref }}
 GITHUB_REF_NAME: ${{ inputs.branch != '' && inputs.branch || github.ref_name }}

1 change: 1 addition & 0 deletions
AGENTS.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -192,6 +192,7 @@ These conventions describe the target state. New and modified workflows must res
- **Shells**: multi-line `run:` blocks with bash start with `set -euo pipefail` - fail fast, fail on undefined vars, fail on a failed pipe segment.
- **Conditionals**: multi-line `if:` uses folded scalar `if: >-` so YAML preserves whitespace correctly. Literal block (`if: |`) is wrong because it embeds newlines inside the boolean expression.
- **Boolean inputs**: workflows triggered both via `workflow_call` and `workflow_dispatch` must declare each boolean input in *both* trigger blocks - one definition does not propagate to the other. `workflow_call` delivers booleans as actual booleans; `workflow_dispatch` delivers them as the *strings* `"true"`/`"false"`. Any `if:` consuming a boolean input must compare against both forms - `if: ${{ inputs.foo == true || inputs.foo == 'true' }}`.
- **Validate input/state consistency at entry, fail fast**: when a workflow's inputs must satisfy a cross-input or input-versus-derived-state invariant (e.g. the release branch must match the computed version's prerelease status, or two inputs are mutually exclusive), assert it **once** in a dedicated entry validation step/job that the downstream jobs `needs:`, before any expensive build or publish work - not as partial checks scattered deep in later jobs. One gate that fails fast with a clear `::error::` beats a late or one-directional check. Examples: [`build-release-task.yml`](./.github/workflows/build-release-task.yml)'s `validate-release` job (branch-versus-prerelease, both directions) and [`publish-docker-readme-task.yml`](./.github/workflows/publish-docker-readme-task.yml)'s "Validate inputs step".
- **Reusable workflows**: job-level `permissions:` are validated *before* the `if:` evaluates, so even a skipped job needs valid permissions declared. A `release` job with `permissions: contents: write` and `if: ${{ inputs.publish }}` will still cause `startup_failure` on a caller that doesn't grant `contents: write`. Either declare permissions at the call site, or omit the inner block and inherit.
- **Allowlist `success` and `skipped` explicitly** when chaining jobs across optional dependencies - `!= 'failure'` lets `cancelled` through (timeout, runner failure, manual cancel). Use `(needs.X.result == 'success' || needs.X.result == 'skipped')`.
- **Artifact retention**: workflow artifacts are an intra-run handoff only - durable copies live on the GitHub release, not in workflow artifacts - so they must not survive the run and accumulate against the small account-wide artifact-storage quota. **Every workflow that can produce artifacts ends with a terminal `cleanup-artifacts` job** that deletes the run's artifacts via the REST API: `permissions: actions: write`, `needs` the artifact producers, an `if:` that **includes** `always()` (so a failed run still cleans up) plus any workflow-specific gate (e.g. `publish-release.yml` adds `&& needs.setup.outputs.publish == 'true'` to run only on real publishes), independent of any required status check so housekeeping never gates a merge, `continue-on-error: true` on the delete step so even an unexpected failure never reds the run, and tolerant of individual list/delete failures (warn and continue). This covers not just `actions/upload-artifact` but build-records that actions emit automatically (e.g. `docker/build-push-action`'s `.dockerbuild`). Both `publish-release.yml` and `test-pull-request.yml` carry one; add one to any new artifact-producing entry workflow. Set `retention-days: 1` on explicit uploads as a backstop.
Expand Down