Release: Alpha 4 readiness checklist

[bobtista]

Goal

Ship one verified Alpha 4 release from a pinned development commit.

Checking an item means its result has been verified—not merely that a PR exists. PR #229 must not be merged solely because it becomes mechanically mergeable.

Release blockers

• Remove client-side UploadThing credentials: Security: remove client-side UploadThing credentials #298 / fix(security): remove client-side UploadThing credentials #300
• Fix Linux startup dependency resolution: Linux startup fails without GitHub token storage #299 / fix(linux): resolve optional token storage at startup #301
• Fix filesystem manifest discovery: Fix filesystem manifest discovery JSON filename pattern #302 / fix(manifest): use JSON file pattern during discovery #305
• Continue manifest discovery past unavailable directories: Manifest discovery aborts when a nested directory becomes unavailable #308 / fix(manifest): continue past unavailable directories #309
• Make Steam proxy preparation rollback-safe: Steam proxy preparation can leave the proxy installed after failure #303 / fix(steam): roll back failed proxy preparation #304
• Resolve provider version ordering: Version ordering is inconsistent across provider formats and application flows #306 / fix: use provider-declared schemes for version ordering #297
• Decide whether fix: support extended GeneralsOnline version format with build suffixes #296 merges independently or is superseded by fix: use provider-declared schemes for version ordering #297
• Open and land an issue/PR disabling destructive CAS garbage collection
• Open and land an issue/PR requiring explicit release promotion
• Confirm artifacts contain no reusable service credentials

Operational security

• Revoke and rotate the affected UploadThing credential
• Remove obsolete repository secrets
• Privately review provider-account activity

Integration

• All selected blocker PRs are merged into development
• Superseded PRs are closed with an explanation
• Windows and Linux CI pass
• Record the exact release-candidate commit SHA
• Update PR chore: alpha 4 release #229 to contain that candidate
• Confirm PR chore: alpha 4 release #229 contains no unrelated changes
• Obtain at least one human maintainer approval
• Satisfy the main ruleset without bypassing checks

Windows validation

Record the tester, package, operating system and candidate SHA in a comment.

• Installer completes successfully
• Packaged application starts
• Existing configuration loads
• Game installations are detected
• A profile can be created and launched
• Steam preparation failure restores the original executable
• Upload controls are disabled
• Existing public UploadThing links remain importable
• CAS garbage collection performs no deletion

Linux validation

Record the tester, package, distribution and candidate SHA in a comment.

• Package installs or extracts successfully
• Packaged application starts
• Existing configuration loads
• Game installations are detected
• A supported profile can be created and launched
• Upload controls are disabled
• Existing public UploadThing links remain importable
• CAS garbage collection performs no deletion

Release preparation

• Agree on the exact release version and tag
• Generate release notes from the previous release tag
• Document disabled uploads and CAS garbage collection
• Confirm releases require explicit promotion
• Confirm successful CI exists for the candidate SHA
• Verify expected Windows and Linux assets exist and are non-empty

Promotion

• Merge the verified PR chore: alpha 4 release #229
• Promote the exact verified commit
• Verify the published tag points to that commit
• Verify installers, packages and metadata
• Perform final installation/startup checks from published assets
• Publish release notes
• Close the Alpha 4 milestone

[coderabbitai]

Coding Plan

Summary

• Fix the concrete, root-caused code defects behind the release blockers: the Linux DI duplicate/missing registrations, the filesystem manifest-discovery string-literal typo, the non-atomic Steam manifest patch, the automatic destructive CAS GC, and the provider version-ordering comparisons.
• Make destructive/irreversible operations safe by default (atomic-with-rollback manifest writes; non-destructive CAS maintenance) and enforce explicit, human-gated release promotion in CI.
• Treat the UploadThing credential removal / upload-control disabling and all credential-rotation, PR-merge, and manual Windows/Linux validation items as operational/integration work outside this snapshot, since no corresponding code exists in the current tree—flagged clearly so they are verified during Integration rather than assumed complete.

Design Choices

Design Choice 1: Where does the "UploadThing" client-side credential / upload-control code live?

Options Considered:

1. Implement credential removal and upload-control disabling in this plan.
2. Treat UploadThing work as living in a separate branch/PR (e.g. PR #229 or a feature branch) that must be landed/reviewed outside this codebase snapshot, and scope this plan to the blockers that have identifiable code here.

Chosen Option: 2

Rationale: Because there is literally no UploadThing code to modify in this snapshot, this plan cannot implement it; it is flagged as an external dependency that must be verified during Integration/validation rather than coded here.

Design Choice 2: How should destructive CAS garbage collection be disabled for the release?

Options Considered:

1. Flip the EnableAutomaticGc default to false so no scheduled deletion occurs unless a user opts in.
2. Add an explicit hard gate that prevents any destructive deletion path (background loop performs analysis/reporting only, never calls delete), independent of the user toggle.

Chosen Option: 2

Rationale: The ticket requires that "CAS garbage collection performs no deletion," so a hard non-destructive gate is safer than relying solely on a default that a loaded user config could override (with Option 1 default flip as reinforcement).

Design Choice 3: How should "explicit release promotion" be enforced in CI/CD?

Options Considered:

1. Make the release job produce a draft release only, and add a separate manual workflow_dispatch "promote" job/workflow that publishes (un-drafts) a chosen candidate.
2. Gate the publish step behind a GitHub Environment with required reviewers.

Chosen Option: 1

Rationale: It is fully version-controlled in the repo (reviewable in this PR), does not depend on server-side environment configuration that isn't captured in-repo, and directly satisfies "releases require explicit promotion."

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Startup and Content-Discovery Correctness

This phase fixes the two defects that prevent the application from starting correctly on Linux and from discovering local content, which are prerequisites for every downstream validation item (startup, config load, installation detection, profile launch).

Task 1: Fix Linux startup dependency resolution

Eliminate the order-dependent DI registration conflict and Linux-specific gaps that can break startup/resolution.

• Resolve the duplicate IGameInstallationDetectionOrchestrator registration between GenHub/Infrastructure/DependencyInjection/GameDetectionModule.cs (Transient factory) and GenHub/Infrastructure/DependencyInjection/GameInstallationModule.cs (Singleton concrete type); consolidate to a single, consistent registration/lifetime so behavior no longer depends on module ordering.
• Review GenHub.Linux/Infrastructure/DependencyInjection/LinuxServicesModule.cs against WindowsServicesModule and add the missing IGitHubTokenStorage registration (or provide a safe no-op/default implementation for Linux) so that any view model requiring it as a non-nullable dependency (e.g. GitHubTokenDialogViewModel) can resolve without throwing.
• Consider enabling container validation (ValidateOnBuild/ValidateScopes) in GenHub.Linux/Program.cs build to surface resolution errors deterministically at startup.
• Verify LinuxInstallationDetector remains discoverable as the single IGameInstallationDetector enumerable member consumed by the consolidated orchestrator.

Task 2: Fix filesystem manifest discovery

Correct the literal-string search pattern that causes filesystem discovery to silently return zero manifests.

• In GenHub/Features/Manifest/ManifestDiscoveryService.cs (DiscoverManifestsAsync), replace the quoted literal "FileTypes.JsonFilePattern" with the actual constant reference FileTypes.JsonFilePattern, and align the pattern set with the private DiscoverFileSystemManifestsAsync method (which also matches .manifest.json).
• Confirm FileSystemDiscoverer now returns discovered manifests for configured content directories.
• Optionally address the latent SourceUrl/RequiresResolution inconsistency between FileSystemDiscoverer and LocalManifestResolver only if it blocks correct discovery; otherwise leave out of scope to avoid unrelated changes.

🤖 Prompt for AI agents

Implement this phase to fix startup and content-discovery defects that block
every downstream validation item.

For the Linux DI fix:
- Resolve the duplicate `IGameInstallationDetectionOrchestrator` registration
between `GenHub/Infrastructure/DependencyInjection/GameDetectionModule.cs`
(registered as Transient via factory) and
`GenHub/Infrastructure/DependencyInjection/GameInstallationModule.cs`
(registered as Singleton concrete type). Consolidate to a single, consistent
registration and lifetime so behavior does not depend on module registration
order.
- In `GenHub.Linux/Infrastructure/DependencyInjection/LinuxServicesModule.cs`,
compare against `WindowsServicesModule` and add the missing
`IGitHubTokenStorage` registration, or provide a safe no-op/default
implementation for Linux, so non-nullable dependents (e.g.
`GitHubTokenDialogViewModel`) can resolve without throwing.
- Consider enabling container validation options
(`ValidateOnBuild`/`ValidateScopes`) in `GenHub.Linux/Program.cs`'s
host/container build so resolution errors surface deterministically at startup.
- Verify `LinuxInstallationDetector` is still discoverable as the sole
`IGameInstallationDetector` enumerable member consumed by the consolidated
orchestrator.

For the filesystem manifest discovery fix:
- In `GenHub/Features/Manifest/ManifestDiscoveryService.cs`, in
`DiscoverManifestsAsync`, replace the quoted literal string
`"FileTypes.JsonFilePattern"` with the actual constant reference
`FileTypes.JsonFilePattern`.
- Align the pattern set with the private `DiscoverFileSystemManifestsAsync`
method, which also matches `.manifest.json`.
- Confirm `FileSystemDiscoverer` correctly returns discovered manifests for
configured content directories after the fix.
- Optionally address the `SourceUrl`/`RequiresResolution` inconsistency between
`FileSystemDiscoverer` and `LocalManifestResolver` only if it actually blocks
correct discovery; otherwise leave it out of scope.

Phase 2: Data-Safety Fixes (Steam Proxy and CAS GC)

This phase makes on-disk mutations safe/non-destructive, satisfying the "Steam preparation failure restores the original executable" and "CAS garbage collection performs no deletion" validation items.

Task 1: Make Steam proxy preparation rollback-safe

Ensure a failed manifest patch never leaves a truncated/corrupted manifest cache file.

• In GenHub/Features/Manifest/SteamManifestPatcher.cs (PatchManifestAsync), replace the non-atomic File.Create + serialize with an atomic write pattern: serialize to a temporary file, flush, then atomically replace the original (e.g. File.Replace/backup-then-move), so an interrupted write cannot corrupt the existing manifest.
• Add rollback semantics so that on any exception the original manifest content is restored (retain the backup until the replace succeeds; restore it in a catch/finally).
• Ensure the caller path in GameProfiles/ViewModels/GameProfileLauncherViewModel.cs (ToggleSteamLaunch) remains consistent: on patch failure the persisted profile toggle and the on-disk manifest end in a matching, valid state.

Task 2: Disable destructive CAS garbage collection

Guarantee the shipped build performs no automatic deletion.

• In GenHub/Features/Storage/Services/CasMaintenanceService.cs, gate the destructive path so the background loop performs analysis/reporting only and never invokes deletion for this release (a hard guard independent of user configuration).
• Reinforce by setting the EnableAutomaticGc default to disabled in the CAS configuration/options binding path (CasConfiguration / CasModule / configuration provider defaults).
• Ensure manual GC entry points (if surfaced via Settings) either remain unavailable or clearly require explicit user action; do not remove the underlying CasService.RunGarbageCollectionAsync capability, only prevent automatic destructive execution.
• This will be documented in Release preparation ("Document disabled uploads and CAS garbage collection").

🤖 Prompt for AI agents

Implement this phase to make on-disk mutations safe and non-destructive,
satisfying the Steam preparation rollback and CAS garbage-collection-disabled
requirements.

For Steam proxy preparation rollback safety:
- In `GenHub/Features/Manifest/SteamManifestPatcher.cs`, within
`PatchManifestAsync`, replace the current non-atomic `File.Create` + serialize
approach with an atomic write pattern: serialize to a temporary file, flush it,
then atomically replace the original file (e.g. via `File.Replace` or a
backup-then-move approach), so an interrupted write cannot corrupt the existing
manifest.
- Add rollback semantics so that on any exception the original manifest content
is restored: retain the backup until the replace succeeds, and restore it from
within a `catch`/`finally` block if the operation fails.
- Verify that the caller path in
`GameProfiles/ViewModels/GameProfileLauncherViewModel.cs` (`ToggleSteamLaunch`)
remains consistent — on patch failure, the persisted profile toggle state and
the on-disk manifest must end up in a matching, valid state.

For disabling destructive CAS garbage collection:
- In `GenHub/Features/Storage/Services/CasMaintenanceService.cs`, add a hard
gate on the destructive deletion path so that the background maintenance loop
performs analysis/reporting only and never invokes deletion for this release,
independent of any user configuration toggle.
- Reinforce this by setting the `EnableAutomaticGc` default to disabled across
the CAS configuration/options binding path (`CasConfiguration`, `CasModule`, and
any configuration provider defaults).
- Ensure that any manual GC entry points surfaced via Settings either remain
unavailable or clearly require explicit user action. Do not remove the
underlying `CasService.RunGarbageCollectionAsync` capability — only prevent its
automatic/destructive execution.
- Note that this behavior should be documented as part of release preparation
("Document disabled uploads and CAS garbage collection"), though the
documentation itself is out of scope for this code phase.

Phase 3: Provider Version Ordering

This phase fixes incorrect "latest version" selection across content providers so update detection behaves correctly, satisfying "Resolve provider version ordering (#306/#297)."

Task 1: Introduce a consistent version-comparison utility

Provide a single correct comparison path to replace ad-hoc/duplicated logic.

• Add or consolidate a shared version-comparison helper in GenHub.Core/Helpers/ (extending VersionHelper.cs) that correctly orders numeric version components (avoiding both ordinal-string and digit-concatenation pitfalls) and can accommodate the provider-specific formats where needed.
• Keep scope limited to what the update services require; do not refactor unrelated ManifestId/GitHub version-extraction helpers unless they feed the same comparison.

Task 2: Fix provider update services to compare the correct version field

Correct the two confirmed ordering bugs.

• In GenHub/Features/Content/Services/CommunityOutpost/CommunityOutpostUpdateService.cs, change ordering/equality/"already installed" checks from ManifestVersion (schema constant "1") to the actual content Version, using the shared comparer, so updates are no longer perpetually re-detected.
• In GenHub/Features/Content/Services/Publishers/SuperHackersUpdateService.cs, replace the ordinal string.Compare in CompareVersions (and the current-version selection between Generals/ZeroHour) with the shared comparer.
• Leave GeneralsOnlineUpdateService.cs's already-correct bespoke date+QFE comparison as-is, optionally routing it through the shared helper only if it does not change behavior.
• Address item "Decide whether #296 merges independently or is superseded by #297": treat this as a review/integration decision recorded in the PR rather than a code change here.

🤖 Prompt for AI agents

Implement this phase to fix incorrect "latest version" selection across content
providers so update detection behaves correctly.

First, introduce a consistent version-comparison utility:
- Add or consolidate a shared version-comparison helper in
`GenHub.Core/Helpers/`, extending `VersionHelper.cs`, that correctly orders
numeric version components, avoiding both ordinal-string comparison pitfalls and
digit-concatenation pitfalls, and that can accommodate provider-specific version
formats where needed.
- Keep the scope limited to what the update services require; do not refactor
unrelated `ManifestId`/`GitHub` version-extraction helpers unless they feed the
same comparison logic.

Then, fix the provider update services to use the correct version field and the
shared comparer:
- In
`GenHub/Features/Content/Services/CommunityOutpost/CommunityOutpostUpdateService.cs`,
change ordering/equality/"already installed" checks from using `ManifestVersion`
(a schema constant of `"1"`) to using the actual content `Version` field,
applying the shared comparer, so updates are no longer perpetually re-detected.
- In `GenHub/Features/Content/Services/Publishers/SuperHackersUpdateService.cs`,
replace the ordinal `string.Compare` call in `CompareVersions` (and the
current-version selection logic between Generals/ZeroHour) with the shared
comparer.
- Leave `GeneralsOnlineUpdateService.cs`'s existing bespoke date+QFE comparison
logic as-is since it is already correct; optionally route it through the shared
helper only if doing so does not change its behavior.
- Treat the decision of "whether `#296` merges independently or is superseded by
`#297`" as a review/integration decision to be recorded in the PR, not as a code
change in this phase.

Phase 4: Release Pipeline — Explicit Promotion and Credential Hygiene

This phase enforces that releases require a deliberate promotion step and that shipped artifacts contain no reusable service credentials, satisfying the corresponding release-blocker and release-preparation items.

Task 1: Require explicit release promotion

Convert automatic publish-on-push into a draft + manual promotion flow.

• Modify .github/workflows/release.yml so the release-creation step produces a draft (unpublished) release on push to main instead of a public non-draft prerelease.
• Add a separate manual promotion trigger (a workflow_dispatch job/workflow keyed to a specific candidate commit/tag) that publishes (un-drafts) the verified release, so promotion is a deliberate human action.
• Ensure the promotion path verifies/targets the exact release-candidate commit SHA (supports "Promote the exact verified commit" and "Verify the published tag points to that commit").

Task 2: Confirm no reusable service credentials ship in artifacts

Validate and, if needed, remove any embedded secrets.

• Audit GenHub/appsettings.json, GenHub.Core/Options/*, and GenHub.Core/Constants/* to confirm no embedded API keys/tokens are packaged (exploration found none beyond public URLs and env-var name references).
• Confirm CI/release build/publish/vpk pack steps in ci.yml/release.yml inject only non-sensitive metadata and do not bake secrets into installers; ensure any obsolete repository secrets are removed as an operational follow-up.
• This underpins the Integration item "Confirm artifacts contain no reusable service credentials."

🤖 Prompt for AI agents

Implement this phase to enforce explicit, deliberate release promotion in CI and
to confirm no reusable service credentials ship in artifacts.

For explicit release promotion:
- Modify `.github/workflows/release.yml` so that the release-creation step,
triggered on push to `main`, produces a **draft** (unpublished) release rather
than a public non-draft prerelease.
- Add a separate manual promotion trigger — a `workflow_dispatch` job or
workflow keyed to a specific candidate commit/tag — that publishes (un-drafts)
the verified release. This makes promotion a deliberate human action rather than
an automatic side effect of pushing to `main`.
- Ensure the promotion path verifies and targets the exact release-candidate
commit SHA, supporting the requirements to "promote the exact verified commit"
and "verify the published tag points to that commit."

For credential hygiene confirmation:
- Audit `GenHub/appsettings.json`, `GenHub.Core/Options/*`, and
`GenHub.Core/Constants/*` to confirm no embedded API keys or tokens are packaged
into artifacts (prior exploration found none beyond public URLs and
environment-variable name references).
- Confirm that the CI/release build/publish/`vpk pack` steps in
`ci.yml`/`release.yml` inject only non-sensitive metadata and do not bake
secrets into installers.
- Note that removal of any obsolete repository secrets is an operational
follow-up, not a code change in this phase.
- This work underpins the Integration validation item "Confirm artifacts contain
no reusable service credentials."

Research

GenHub is a .NET/Avalonia desktop application split across GenHub.Core (models, interfaces, constants, helpers), GenHub (shared features and DI modules), and platform heads GenHub.Windows / GenHub.Linux. DI is composed by AppServices.ConfigureApplicationServices invoking feature "modules," with the platform module registered last. Content is discovered/resolved through a provider pipeline (ContentOrchestrator, discoverers, resolvers, *UpdateService background services), stored in a local Content-Addressable Store (CAS) with a background CasMaintenanceService, and launched via a workspace preparation pipeline. CI/CD is defined in .github/workflows/ (ci.yml, release.yml, deploy.yml), where release.yml currently auto-publishes on push to main.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement this phase to fix startup and content-discovery defects that block
every downstream validation item.

For the Linux DI fix:
- Resolve the duplicate `IGameInstallationDetectionOrchestrator` registration
between `GenHub/Infrastructure/DependencyInjection/GameDetectionModule.cs`
(registered as Transient via factory) and
`GenHub/Infrastructure/DependencyInjection/GameInstallationModule.cs`
(registered as Singleton concrete type). Consolidate to a single, consistent
registration and lifetime so behavior does not depend on module registration
order.
- In `GenHub.Linux/Infrastructure/DependencyInjection/LinuxServicesModule.cs`,
compare against `WindowsServicesModule` and add the missing
`IGitHubTokenStorage` registration, or provide a safe no-op/default
implementation for Linux, so non-nullable dependents (e.g.
`GitHubTokenDialogViewModel`) can resolve without throwing.
- Consider enabling container validation options
(`ValidateOnBuild`/`ValidateScopes`) in `GenHub.Linux/Program.cs`'s
host/container build so resolution errors surface deterministically at startup.
- Verify `LinuxInstallationDetector` is still discoverable as the sole
`IGameInstallationDetector` enumerable member consumed by the consolidated
orchestrator.

For the filesystem manifest discovery fix:
- In `GenHub/Features/Manifest/ManifestDiscoveryService.cs`, in
`DiscoverManifestsAsync`, replace the quoted literal string
`"FileTypes.JsonFilePattern"` with the actual constant reference
`FileTypes.JsonFilePattern`.
- Align the pattern set with the private `DiscoverFileSystemManifestsAsync`
method, which also matches `.manifest.json`.
- Confirm `FileSystemDiscoverer` correctly returns discovered manifests for
configured content directories after the fix.
- Optionally address the `SourceUrl`/`RequiresResolution` inconsistency between
`FileSystemDiscoverer` and `LocalManifestResolver` only if it actually blocks
correct discovery; otherwise leave it out of scope.
===============================================================================

Task: 2

Implement this phase to make on-disk mutations safe and non-destructive,
satisfying the Steam preparation rollback and CAS garbage-collection-disabled
requirements.

For Steam proxy preparation rollback safety:
- In `GenHub/Features/Manifest/SteamManifestPatcher.cs`, within
`PatchManifestAsync`, replace the current non-atomic `File.Create` + serialize
approach with an atomic write pattern: serialize to a temporary file, flush it,
then atomically replace the original file (e.g. via `File.Replace` or a
backup-then-move approach), so an interrupted write cannot corrupt the existing
manifest.
- Add rollback semantics so that on any exception the original manifest content
is restored: retain the backup until the replace succeeds, and restore it from
within a `catch`/`finally` block if the operation fails.
- Verify that the caller path in
`GameProfiles/ViewModels/GameProfileLauncherViewModel.cs` (`ToggleSteamLaunch`)
remains consistent — on patch failure, the persisted profile toggle state and
the on-disk manifest must end up in a matching, valid state.

For disabling destructive CAS garbage collection:
- In `GenHub/Features/Storage/Services/CasMaintenanceService.cs`, add a hard
gate on the destructive deletion path so that the background maintenance loop
performs analysis/reporting only and never invokes deletion for this release,
independent of any user configuration toggle.
- Reinforce this by setting the `EnableAutomaticGc` default to disabled across
the CAS configuration/options binding path (`CasConfiguration`, `CasModule`, and
any configuration provider defaults).
- Ensure that any manual GC entry points surfaced via Settings either remain
unavailable or clearly require explicit user action. Do not remove the
underlying `CasService.RunGarbageCollectionAsync` capability — only prevent its
automatic/destructive execution.
- Note that this behavior should be documented as part of release preparation
("Document disabled uploads and CAS garbage collection"), though the
documentation itself is out of scope for this code phase.
===============================================================================

Task: 3

Implement this phase to fix incorrect "latest version" selection across content
providers so update detection behaves correctly.

First, introduce a consistent version-comparison utility:
- Add or consolidate a shared version-comparison helper in
`GenHub.Core/Helpers/`, extending `VersionHelper.cs`, that correctly orders
numeric version components, avoiding both ordinal-string comparison pitfalls and
digit-concatenation pitfalls, and that can accommodate provider-specific version
formats where needed.
- Keep the scope limited to what the update services require; do not refactor
unrelated `ManifestId`/`GitHub` version-extraction helpers unless they feed the
same comparison logic.

Then, fix the provider update services to use the correct version field and the
shared comparer:
- In
`GenHub/Features/Content/Services/CommunityOutpost/CommunityOutpostUpdateService.cs`,
change ordering/equality/"already installed" checks from using `ManifestVersion`
(a schema constant of `"1"`) to using the actual content `Version` field,
applying the shared comparer, so updates are no longer perpetually re-detected.
- In `GenHub/Features/Content/Services/Publishers/SuperHackersUpdateService.cs`,
replace the ordinal `string.Compare` call in `CompareVersions` (and the
current-version selection logic between Generals/ZeroHour) with the shared
comparer.
- Leave `GeneralsOnlineUpdateService.cs`'s existing bespoke date+QFE comparison
logic as-is since it is already correct; optionally route it through the shared
helper only if doing so does not change its behavior.
- Treat the decision of "whether `#296` merges independently or is superseded by
`#297`" as a review/integration decision to be recorded in the PR, not as a code
change in this phase.
===============================================================================

Task: 4

Implement this phase to enforce explicit, deliberate release promotion in CI and
to confirm no reusable service credentials ship in artifacts.

For explicit release promotion:
- Modify `.github/workflows/release.yml` so that the release-creation step,
triggered on push to `main`, produces a **draft** (unpublished) release rather
than a public non-draft prerelease.
- Add a separate manual promotion trigger — a `workflow_dispatch` job or
workflow keyed to a specific candidate commit/tag — that publishes (un-drafts)
the verified release. This makes promotion a deliberate human action rather than
an automatic side effect of pushing to `main`.
- Ensure the promotion path verifies and targets the exact release-candidate
commit SHA, supporting the requirements to "promote the exact verified commit"
and "verify the published tag points to that commit."

For credential hygiene confirmation:
- Audit `GenHub/appsettings.json`, `GenHub.Core/Options/*`, and
`GenHub.Core/Constants/*` to confirm no embedded API keys or tokens are packaged
into artifacts (prior exploration found none beyond public URLs and
environment-variable name references).
- Confirm that the CI/release build/publish/`vpk pack` steps in
`ci.yml`/`release.yml` inject only non-sensitive metadata and do not bake
secrets into installers.
- Note that removal of any obsolete repository secrets is an operational
follow-up, not a code change in this phase.
- This work underpins the Integration validation item "Confirm artifacts contain
no reusable service credentials."

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[bobtista]

Both remaining blocker PRs are now open:

• Disable destructive CAS garbage collection: CAS garbage collection deletes blobs based on incomplete reference tracking #310 (issue) / fix: disable unsafe CAS garbage collection #312 (PR, fix/disable-unsafe-cas-gc → development)
• Require explicit release promotion: Every push to main publishes a release with no promotion step #311 (issue) / ci: gate releases behind explicit promotion #313 (PR, ci/manual-release-gates → development)

Notes:

• ci: gate releases behind explicit promotion #313 deliberately targets development so the Alpha 4 merge commit (chore: alpha 4 release #229) carries the gated workflow — merging chore: alpha 4 release #229 then cannot fire the old push-triggered auto-release. Until chore: alpha 4 release #229 merges, nothing else should be merged directly to main, since main's current workflow still auto-publishes on push.
• ci: gate releases behind explicit promotion #313 keeps the Inject Secrets steps; fix(security): remove client-side UploadThing credentials #300 removes them. Whichever lands second rebases trivially.
• ci: gate releases behind explicit promotion #313 supersedes the local agent/manual-release-gates branch (rebased onto development's rewritten release.yml from fix: refactor changelog generation logic in GitHub release #226/feat: Refactor and implement Map/Replay Managers and Tools Sidebar #238, with two fixes for the tag-trigger model: changelog now excludes the tag being released, and dispatch-created tags are pinned to the promoted SHA via target_commitish).

[bobtista]

Phase 1 progress — blocker merges into development

Merged (squash), in order:

PR	Squash commit	Subject
#305	083c62d	fix(manifest): use JSON file pattern during discovery
#300	b3280ad	fix(security): remove client-side UploadThing credentials
#301	8f46ae1	fix(linux): resolve optional token storage at startup
#304	5e29ec4	fix(steam): roll back failed proxy preparation
#297	b7b6a0c	fix: use provider-declared schemes for version ordering
#312	a783b36	fix: disable unsafe CAS garbage collection

#296 decision: superseded by #297, closed. #297's MmddyyQfeVersionScheme parses MMDDYY, the QFE revision and any number of trailing build tags (042826_QFE3_EAC), excluding the tags from ordering — the behaviour #296 added — and additionally fixes cross-year ordering by comparing a structured ContentVersion rather than MMDDYY as an integer. #297 also deletes ParseGeneralsOnlineVersion, so #296 no longer applies. Rationale recorded on #296.

Still open — both need a rebase force-push before they can merge:

• fix(manifest): continue past unavailable directories #309 — was stacked on fix(manifest): use JSON file pattern during discovery #305. Squash-merging fix(manifest): use JSON file pattern during discovery #305 left fix(manifest): continue past unavailable directories #309 carrying fix(manifest): use JSON file pattern during discovery #305's unsquashed commits, so it went CONFLICTING when retargeted to development. Rebased locally with --onto; the result is exactly fix(manifest): continue past unavailable directories #309's own two commits (ManifestDiscoveryService.cs, ManifestDiscoveryServiceTests.cs) with no duplication of fix(manifest): use JSON file pattern during discovery #305.
• ci: gate releases behind explicit promotion #313 — conflicted with fix(security): remove client-side UploadThing credentials #300 in release.yml, as anticipated. Resolved by dropping both Inject Secrets steps and keeping ci: gate releases behind explicit promotion #313's Run Release Tests steps plus the Linux Extract Build Info step (the Linux job has no buildinfo step on development, and Publish Linux App references steps.buildinfo.outputs.VERSION). fix(security): remove client-side UploadThing credentials #300 deleted .github/scripts/inject-token.ps1 outright, so retaining Inject Secrets would have broken the workflow. Resolved file parses as valid YAML and contains no UPLOADTHING/inject-token references.

No merges to main have been made; #229 is untouched.

[bobtista]

Phase 1 complete — all blocker PRs merged into development

development now at 8e07339:

PR	Squash commit
#305	083c62d
#300	b3280ad
#301	8f46ae1
#304	5e29ec4
#297	b7b6a0c
#312	a783b36
#313	4202a8a
#309	8e07339

#296 closed as superseded by #297.

Notes on the two rebased PRs:

• fix(manifest): continue past unavailable directories #309 — after rebasing, CodeRabbit correctly flagged that the new test injected failures only into the file enumerator, leaving the _enumerateDirectories catch in EnumerateFilesSafely uncovered. Fixed in ace7451: the test now injects a directory enumerator that throws UnauthorizedAccessException for an unlistable/ directory containing a nested manifest, so discovery skips that subtree and still finds the accessible manifest. Confirmed the test pins the branch — removing the catch makes it fail; restored, all 8 ManifestDiscoveryServiceTests pass.
• ci: gate releases behind explicit promotion #313 — release.yml conflict with fix(security): remove client-side UploadThing credentials #300 resolved by dropping both Inject Secrets steps (fix(security): remove client-side UploadThing credentials #300 deleted .github/scripts/inject-token.ps1, so retaining them would have broken the workflow) and keeping the Run Release Tests steps plus the Linux Extract Build Info step, which Publish Linux App depends on via steps.buildinfo.outputs.VERSION. Windows and Linux builds passed on the rewritten workflow file.

Both force-pushes dismissed the prior approvals (dismiss_stale_reviews_on_push: true); CodeRabbit re-approved both, and all Windows/Linux CI plus Greptile and Kilo reviews passed before merge.

Remaining before a release candidate can be pinned: confirm artifacts contain no reusable service credentials, the operational-security items, then packaged Windows/Linux validation. No changes have been made to main; #229 is untouched.

ℹ️ Local-toolchain note (corrected — my earlier wording said CI's SDK was "pinned", which is wrong; there is no global.json and the workflows request the floating 8.0.x).

GitHubTopicsDiscoverer.cs:418 fails to compile with error CS0121 (ambiguous string.Split) on SDK 8.0.129. This is a compiler bug, not a code defect: the 8.0.1xx feature band ships Roslyn 4.8, whose overload resolution wrongly treats a collection expression as a candidate for Split(string?, StringSplitOptions). CI resolves 8.0.x to 8.0.423 (8.0.4xx band, newer Roslyn) and compiles it correctly, so CI and the release build are not at risk and no RC action is required.

Anyone hitting this locally is on an 8.0.1xx SDK — Homebrew's dotnet@8 is the usual cause. Installing an 8.0.4xx (or newer) SDK resolves it with no repo change. No fix is being made for Alpha 4 by decision; pinning the SDK band via global.json is the durable fix if this recurs.

[bobtista]

Release candidate pinned

RC SHA: 8e073394a9b4215e6eb927a4eb354cc55504b10b

RC commit	8e07339 (development tip)
PR #229 head	8e07339 — identical, no update needed
Commits in RC	52 (main..development)
Diff	814 files, +87,857 / −14,050

CI on the candidate SHA

Run	Event	Result
30454365599	push	success
30454371473	pull_request	success

Both cover Build Windows and Build Linux.

#229 contains no unrelated changes

• All 52 commits are PR-numbered merges of Alpha 4 work; no stray or direct-to-branch commits.
• No local-only planning docs (PLAN.md, SPEC.md, NOTES.md, docs/design|specs|plans) present in the tree.
• Workflow changes limited to the three expected files from fix(security): remove client-side UploadThing credentials #300 and ci: gate releases behind explicit promotion #313.
• CNAME is safe. It exists on main only and is not deleted in development relative to the merge base, so merging chore: alpha 4 release #229 preserves it and the site domain. Worth re-checking if the merge is ever re-cut.

Artifacts contain no reusable service credentials

The pre-#300 build injected the UploadThing token at CI time via .github/scripts/inject-token.ps1, which XOR-obfuscated it with a random key and wrote both the ciphertext and the key into ApiConstants.cs. Shipping both together makes it trivially reversible, so published v0.0.1–v0.0.3 artifacts contain a recoverable token — this is why rotation below is mandatory rather than precautionary.

Verified for the RC:

• No workflow references UPLOADTHING_TOKEN; the only remaining workflow secrets are NETLIFY_* in deploy.yml (website deploy, unrelated).
• .github/scripts/inject-token.ps1 is deleted; no injection step remains.
• ApiConstants.cs has no PLACEHOLDER_DATA/PLACEHOLDER_KEY, byte arrays, or obfuscation code.
• UploadThingService is inert — upload and delete log a warning and return null/false, with no credential or HTTP client.
• No secret-shaped literals anywhere in *.cs/*.json/*.yml.
• A local Release build of 8e07339 yields 0 credential-shaped strings in GenHub.Core.dll and GenHub.dll.

Git history is clean: only empty placeholders were ever committed. The token existed solely in CI and in the binaries CI produced. Final confirmation against the actual published assets remains part of “Verify installers, packages and metadata” in Promotion.

Remaining before #229 can merge

• Ops security — revoke/rotate the UploadThing credential (mandatory, see above), remove obsolete repo secrets, review provider-account activity. Needs admin.
• Packaged Windows and Linux validation — recorded per the checklists above.
• One human maintainer approval on chore: alpha 4 release #229, from someone other than @bobtista, since most of these fixes are ours. chore: alpha 4 release #229 currently shows CHANGES_REQUESTED from four stale CodeRabbit reviews predating the blocker merges; these need dismissing or re-requesting.

Note for Phase 3: #313’s promote job requires a successful CI push run for the exact SHA on main. The runs above are on development, so the merge commit will need its own green CI run on main before the release can be promoted.

[bobtista]

Linux container smoke test — supporting evidence (does NOT replace packaged validation)

Ran the release.yml build-linux job against RC 8e07339 inside a linux/amd64 container on Apple Silicon, using the same publish command, the same vpk pack invocation and the same asset assertions as the workflow. No Linux validation boxes are being ticked — this is a container smoke test, not validation on a real distribution, and it does not cover most of the checklist.

Environment: mcr.microsoft.com/dotnet/sdk:8.0 (SDK 8.0.423 — identical to CI), Debian 12, linux/amd64 via Rosetta, GUI started under Xvfb.

Check	Result
linux-x64 self-contained publish	pass
GenHub.Linux present and executable	pass
Binary is 64-bit x86-64 ELF	pass
Velopack package produced	pass
No empty assets	pass
.nupkg extracts	pass
Application starts, alive 25s under Xvfb	pass
No missing shared libraries	pass
No unhandled exceptions at startup	pass

Assets match the shape of v0.0.1–v0.0.3: GenHub-0.0.4-linux-full.nupkg (133 MB), GenHub.AppImage (134 MB), RELEASES-linux, assets.linux.json, releases.linux.json.

Startup reached a fully initialised UI: tool plugins loaded, MainViewModel initialised, Velopack update check correctly compared Current=0.0.4 vs Latest=0.0.3, GitHub topic discovery returned 13 repositories, downloads populated. Clean log, no errors.

Most useful result: the app started in a bare container with no keyring or secret service present — exactly the condition #299/#301 addressed. This is a real regression check on the Linux startup dependency fix.

Explicitly NOT covered (still requires a real Linux desktop with retail game data):

• Package installs on a target distribution (only extraction was verified)
• Existing configuration loads
• Game installations detected
• Profile created and launched
• Upload controls disabled (UI state)
• Existing public UploadThing links importable
• CAS garbage collection performs no deletion

Also note the app was started from the publish directory rather than from the installed package, so this does not exercise the Velopack install path.

Minor observation for whoever owns the workflow: Install Linux Dependencies installs only libgtk-3-dev libx11-dev, and vpk pack additionally needs mksquashfs to build the AppImage — it fails hard without it. GitHub's ubuntu-latest image currently provides it (v0.0.1–v0.0.3 all shipped Linux assets), so this is not a blocker, but the release depends on a runner-image package that the workflow never declares. Adding squashfs-tools to that apt line would remove the hidden dependency.