Skip to content

Release settings use release.settings.yml - #116

Draft
Marius Storhaug (MariusStorhaug) wants to merge 16 commits into
namespaced-release-labelsfrom
release-settings-filename
Draft

Marius Storhaug (MariusStorhaug) wants to merge 16 commits into
namespaced-release-labelsfrom
release-settings-filename

Conversation

@MariusStorhaug

@MariusStorhaug Marius Storhaug (MariusStorhaug) commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

If your workflow uses .github\auto-release.yml, rename the file to .github\release.settings.yml with a compatible published action. Update the action reference and settings path in the same workflow change. If the workflow still uses the old reader, do not rename the file.

If you select a custom file, keep its path. When you use the compatible action, rename each explicit ConfigurationFile input to SettingsFilePath.

Breaking: Release settings use release.settings.yml

SettingsFilePath now defaults to .github\release.settings.yml. The previous default was .github\auto-release.yml. Relative paths use an explicit WorkingDirectory input, otherwise github.workspace. Explicit absolute and custom paths remain supported.

The action does not read the old default file as a fallback or alias. If you select the old path explicitly, the bootstrap fails before GitHub-Script starts. This rule applies to relative, normalized, and absolute path values. If the old file exists and you select the new default path, startup also fails. The error prevents loss of repository policy during the filename change.

If you select an existing custom file, the action reads that file. If the custom file is missing and the old default file exists, startup fails. If neither file exists, the action uses its standard values and nonempty named inputs.

To update your workflow:

  1. Find the action revision and settings path that your workflow uses. Wait for an authorized, published release with the compatible reader. Select its full source SHA. Do not use either draft head as a production reference.
  2. In the same workflow change, rename each explicit ConfigurationFile: input key to SettingsFilePath:. Keep any intentional custom path unchanged. If you omit the path input, no input-key change is necessary.
  3. If you use the old default file, rename it to .github\release.settings.yml. Keep its valid release policy. If the workflow sets the path explicitly, update that value or omit the input. If both default files exist, combine their required policy in the new file. Then remove the old file.
  4. If you use a custom file, keep its existing path. .github\release.config.yml is a custom path, not a discovery alias. For module repositories, keep .github\PSModule.yml through SettingsPath. No separate module release settings file is necessary.
  5. Omit named settings inputs or leave them empty to keep repository policy. Supply a nonempty input only when you want an invocation override. Explicit false and explicit values equal to a standard remain overrides. To clear VersionPrefix or DatePrereleaseFormat, set an empty string in the selected file.
  6. Run the updated workflow with WhatIf: true. Make sure that the selected settings path, effective values, and bump source are correct. Make sure that the old default path fails before GitHub operations. Complete this check before you let the action write to GitHub.

No intermediate installation is necessary for this filename change. If no default settings file exists and you omit the path input, no file change is necessary.

Before the update:

with:
  ConfigurationFile: .github\auto-release.yml

After you select the compatible published action and rename the default file:

with:
  SettingsFilePath: .github\release.settings.yml
  WhatIf: true

For a custom file, change the input key but keep the existing path value:

with:
  SettingsFilePath: .github\custom-release.settings.yml
  WhatIf: true

Settings and workflow prerequisites

The compatible action must support the settings and release-label contract below. The filename change does not add these capabilities.

All 16 settings support file values and matching named inputs. This includes Debug, Verbose, WorkingDirectory, Version, and dependency Prerelease. The bootstrap resolves settings before GitHub-Script starts. The release script receives the resolved policy and does not read the file again.

Settings resolve in this order: action standards, the selected repository file, then nonempty named inputs. An owned bump label overrides the valid effective DefaultBump. With file policy DefaultBump: major, an omitted or empty input keeps major. An explicit DefaultBump: patch selects patch, even though patch is the standard.

File selection and execution use this order:

  1. Resolve an explicit nonempty WorkingDirectory input from github.workspace. If you omit that input, use the workspace as the initial directory.
  2. Resolve a relative settings path from the initial directory. Check the old default path in that same directory.
  3. Read the selected file once. Resolve a relative file-defined WorkingDirectory from the workspace, not the file directory.
  4. Apply the effective directory to execution without selecting another file.

The input descriptions show the standard values. The action does not copy native policy defaults into omitted inputs. No bundled defaults file, omission token, clear flag, or CallerOverrides input is necessary or supported. Explicit false remains an override. Whitespace is a value, not an empty input. Invalid file values, nulls, unknown keys, and removed keys fail even when another input or label could override them.

Empty inputs do not clear text in a file. To clear supported text settings, put empty strings in the selected file. File Version: '' selects the latest GitHub module dependency.

# .github\release.settings.yml
VersionPrefix: ''
DatePrereleaseFormat: ''

To override repository policy for one invocation, set only the necessary inputs:

with:
  DefaultBump: patch
  AutoCleanup: false
  WhatIf: true

Omit SettingsFilePath to use the default path. An explicitly empty or whitespace-only path fails. The action treats spaces and brackets in a path as literal characters. The selector is not a settings-file key. The Prerelease input still controls the GitHub module dependency, not repository prerelease mode.

VersionPrefix remains configurable, with standard v. Cleanup uses the effective prefix to find the version boundary. If you change the prefix, automatic cleanup keeps releases under earlier prefixes. Close active prerelease series first, or keep those releases for separate authorized cleanup.

If you also change from the v2 interface, apply these prerequisites in the same workflow update:

  • Remove AutoPatching, IgnoreLabels, MajorLabels, MinorLabels, and PatchLabels. Use DefaultBump only for an intentional patch, minor, or major override. There is no none or date bump. If AutoPatching: false prevented publication, use the owned skip decision on each affected active pull request.
  • Use only release:patch, release:minor, release:major, release:prerelease, or release:skip for release decisions. Select no more than one bump label. Prerelease mode can accompany one bump. Skip cannot accompany another owned release label. Bare, retired, and unrelated labels have no effect.
  • Require the compatible reader before you use owned release labels. New labels alone do not add support to an older action. Make sure that the authorized release job runs reviewed source from the trusted default branch.
  • Add issues: write for label creation, with the necessary release and comment permissions. Subscribe to opened, reopened, synchronize, labeled, unlabeled, and closed. Do not use a path filter that bypasses release-decision validation.
  • Keep writable pull_request_target execution on trusted base code. Keep candidate validation read-only. Serialize publication without cancellation. If a label is necessary before the first normal provisioning run, use authorized setup. No historical relabeling or bulk deletion is necessary.
  • Keep UsePRBodyAsReleaseNotes and UsePRTitleAsNotesHeading true to preserve the complete release record. Their existing opt-outs remain supported.

Release decisions still depend on pull-request state. Push-authoritative publication, recovery, and publication governance remain separate work.

Technical details

Source and scope

Comparison Immutable source
Validated lower source, namespaced-release-labels 1040867819d77ef79c88d4492e10e8a8a7b6a37b
Candidate, release-settings-filename a2921454e8ebaefc01e3cd8c2b6adff10a592a42

The scoped diff contains four files, with 302 insertions and 6 deletions:

File Result
action.yml Changes only the default settings path.
src\Initialize-ReleaseConfiguration.ps1 Rejects the old default path before file reads and the startup handoff.
tests\Release-GHRepository.Tests.ps1 Adds isolated cases for the filename change and settings behavior.
README.md States the supported default path, error behavior, and custom-path usage.

#109 supplies the shared schema, startup resolution, settings handoff, safe prefix matching, and paired caller workflow. This PR uses that implementation without a second settings resolver. The controller, helper module, and workflows match the validated lower source. The final startup-forwarding fixture is inherited without an upper change.

The original extraction commit is 905ced93d13306c18ddf239d8bc2a02b4b48533a. It restores tree b2eb47c43236917ba6bc489a9fea391a66f79709 from source 03e20b8293dd8dfb41bead3255930a5edbb2e9bb. Later merges add the prerequisite resolver changes. Current review evidence applies to the candidate above, not the original extraction.

Review evidence

Pester 6.1.0 passed all 245 repository cases, with zero failures, skips, or not-run cases. PSScriptAnalyzer 1.25.0 reported no diagnostics in five PowerShell files. README Markdown lint passed. These checks use the actual bootstrap, YAML reader, settings resolver, and controller. Test doubles prevent external writes. They do not prove live publication.

Two new guard regressions failed before the guard moved and passed after it. They cover legacy-only and conflicting files before any startup output. Other filename cases cover the initial directory, file-defined execution, custom paths, omission, false, and explicit standard-value overrides.

All GitHub checks pass for a2921454e8ebaefc01e3cd8c2b6adff10a592a42:

Check Result Evidence
Pester 6.1 245 passed, zero failed, skipped, or not-run cases Repository cases
Actual composite caller Both policy calls, preparation, and cleanup passed Caller job
Lint code base Passed, including all 13 lint contexts Linter
Analyze - actions Passed Actions analysis
CodeQL Passed CodeQL
Current-head review Approved, with no open issues Submitted review

The caller fixture stays under runner.temp, and the token has read-only permissions. Its two calls distinguish an omitted bump from an explicit standard-valued patch. The logs show the actual startup values and the resolved policy:

Setting Repository policy call Named override call
Debug true false
Verbose true false
Dependency Prerelease true false
Dependency Version [0.43.1] [0.43.1]
WorkingDirectory Workspace .github directory Workspace
DefaultBump major from RepositorySetting patch from ActionInput
AutoCleanup false false
CreateMajorTag false from the file false from the file
DatePrereleaseFormat and VersionPrefix File yyyyMMdd and v remain File yyyyMMdd and v remain
WhatIf true true

Three additional controls use the real version library to reproduce the original cleanup examples. Own-branch cleanup now selects the expected release, including a version-like prefix. The other-branch release has zero candidates.

GitHub merges native input defaults before the action runs. It does not expose the original set of supplied keys to the composite action. The action therefore does not compare an input with its standard to infer omission. See GitHub input defaults and the runner implementation.

Standards and documentation

The review uses MSXOrg/docs at d5bc395416fb4194c1801871990f46faf301bf8a.

Changed surface Standards checked Framework docs checked Result
Default filename Naming, YAML, GitHub Actions SettingsFilePath contract in action.yml and README Fixed in this PR
Bootstrap path guard PowerShell, Error Handling, Code Layout README initial-directory selection and custom-file behavior Aligned
Filename tests Testing, PowerShell Testing Actual bootstrap, controller, YAML reader, and settings resolver Aligned
README and PR text Natural Language, Markdown, PR Format README and release-settings contract Fixed in this PR

The PR text uses ASD-STE100 Issue 9 writing practices and en-US English. The language review uses the official rules and dictionary. Technical identifiers and interface names keep their exact spelling.

Route and draft status

This PR targets namespaced-release-labels. The release workflow accepts only pull requests to main. This route does not publish an artifact. This PR therefore has no release labels or release-decision block. The Breaking heading states the consumer impact. The eventual publishing route must make its own release decision for the complete release.

The PR remains in draft with auto-merge off. #115 depends on #111. That issue depends on #112. Successful source checks do not remove these prerequisites or authorize publication. Automated review does not replace required human approval.

The reviewed template source is PSModule/Template-Action@634ca503a47a39ca26d72fa59c784da8118ae835. It uses the old reader. The review has no verified compatible template commit. Authorized action publication and the necessary template update remain pending.

Plan and issue convergence

The filename guard, bootstrap cases, lower-fixture synchronization, and exact-head checks in #115 are complete for this scoped diff. Its native prerequisites still block integration.

Open-issue searches for release in:title and settings in:title found six distinct issues. Only #115 matches the complete four-file change. The resolver, decision gate, publication authority, custom message, and broader settings discovery remain separate work. This PR closes no additional issue.

Related references

Copilot AI previously approved these changes Nov 13, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approved

No active review issues are reported for this change.

No open issues 🎉

What changed in this PR

This PR changes the Action’s canonical settings filename to .github\release.settings.yml, while preserving explicit custom paths and the prerequisite resolver’s settings contract.

Changes:

  • Updates the default filename and documents coordinated filename/reader adoption.
  • Rejects the removed conventional path and legacy-file conflicts before GitHub operations.
  • Adds coverage for filename validation, custom paths, settings precedence, and dry-run behavior.
File Description
tests/​Release-GHRepository.Tests.ps1 Adds isolated caller tests for the filename transition and retained settings behavior.
src/​main.ps1 Normalizes selected paths and rejects unsupported legacy-path configurations.
README.md Documents the canonical filename, legacy rejection, and custom-path usage.
action.yml Changes the ConfigurationFile default to .github\release.settings.yml.

Review effort: Balanced

@MariusStorhaug Marius Storhaug (MariusStorhaug) added the release:major Publish a major release. label Nov 13, 2026
Copilot AI previously approved these changes Nov 15, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approved

No active review issues block the release Action’s settings-filename transition.

No open issues 🎉

Review effort: Balanced

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The adoption instructions still use ConfigurationFile instead of SettingsFilePath, which can leave custom configuration files unselected and cause default policy to be applied.

1 open issue

Review effort: Balanced

Comment thread README.md Resolved
Copilot AI previously approved these changes Nov 15, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approved

The release settings filename migration has no active review issues.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

Copilot AI previously approved these changes Nov 15, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approved

No active review issues were identified for the release settings filename migration.

No open issues 🎉

Review effort: Balanced

Copilot AI previously approved these changes Nov 15, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approved

No active review issues block the release-settings filename migration.

No open issues 🎉

Review effort: Balanced

Copilot AI previously approved these changes Nov 15, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approved

No active review issues block the release-settings filename migration.

No open issues 🎉

Review effort: Balanced

Copilot AI previously approved these changes Nov 15, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approved

No active review issues remain for the release-settings filename migration.

No open issues 🎉

Review effort: Balanced

@MariusStorhaug Marius Storhaug (MariusStorhaug) removed the release:major Publish a major release. label Nov 15, 2026
@MariusStorhaug Marius Storhaug (MariusStorhaug) changed the title Release settings use the canonical filename Release settings use release.settings.yml Nov 15, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approved

No active review issues remain for the release settings-file migration.

No open issues 🎉

Review effort: Balanced

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Release settings use one canonical conventional filename

2 participants