Compare commits

...
7 Commits
Author SHA1 Message Date
james.maesandClaude Fable 5.1 2c4726e30e feat(release): Authenticode-sign releases with Azure Artifact Signing over OIDC (#96)
## What

Releases are now Authenticode-signed (K22-REL-05) through the standards'
shared workflow, which already carries the signing steps behind `sign`
(`azure/login` v3.1.0 and `azure/artifact-signing-action` v2.0.0, both
SHA-pinned and current; `vpk pack --azureTrustedSignFile`). ADR 0008.

- `release.yml`: `sign: true`; new `verify-signatures` job after
`release` downloads the published Setup.exe, portable zip and CLI zip
and runs `signtool verify /pa /all` + `Get-AuthenticodeSignature` on
every gclo executable, failing on an invalid, untimestamped or
foreign-publisher signature (`TRUSTED_SIGNING_SUBJECT`).
- Authentication is GitHub OIDC: an Entra application
`gclo-release-signing` with a federated credential for
`repo:KofTwentyTwo/gclo:environment:release` and only *Artifact Signing
Certificate Profile Signer* on the certificate profile. No secret, key
or PFX anywhere. The identity is `release`-environment **variables**:
`AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_SUBSCRIPTION_ID`,
`TRUSTED_SIGNING_ENDPOINT`, `TRUSTED_SIGNING_ACCOUNT`,
`TRUSTED_SIGNING_PROFILE`, `TRUSTED_SIGNING_SUBJECT`.
- `.github/scripts/Set-ReleaseSigning.ps1`: idempotent Azure
configuration (reads the existing account and Active profile through
ARM, ensures app + service principal + federated credential +
profile-scoped role, prints the `gh variable set` lines). Run
interactively by the owner; never creates secrets or touches the
account, validation or profile.
- Docs: RELEASING.md ("Code signing", local signing with SignTool + the
`Microsoft.ArtifactSigning.Client` dlib, the verify job), SECURITY.md,
README verify step 4, threat-model revision row.

Closes #57 (part of #62). After the first signed release verifies,
EX-0002 closes for gclo in the standards register.

## Azure configuration status

Pending the owner's interactive sign-in; the script output and `signtool
verify` results of the first signed prerelease will be posted here
before merge.

## How it was tested

- `actionlint` clean; PSScriptAnalyzer 0 findings.
- Verification of a real signed build: pending the Azure configuration
(recorded here when done).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Signed-off-by: James Maes <james@kof22.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-10 14:39:26 -05:00
james.maesandClaude Fable 5.1 c4d84779ab fix: keep per-user data out of the Velopack install root (#94)
## What

Running any `Setup.exe` over an existing install wiped `accounts.json`,
`accounts.json.bak`, `settings.json` and `logs\` on the maintainer's
machine (#91): Velopack uninstalls the previous version first and
deletes the whole install root, and gclo stored its data in that same
folder, `%LOCALAPPDATA%\gclo`.

- Default data root is now `%LOCALAPPDATA%\KofTwentyTwo\gclo`
(`GcloPaths.DefaultDataRoot`); the CLI's and the activity log's default
follow. `GCLO_DATA_DIR` still overrides it.
- **No migration**, as agreed: single user, single machine, green
fields. The default vault scope is still unscoped, so the existing
`gclo:account:<id>` Credential Manager entries keep working once
accounts are re-added.
- README, `docs/CLI.md`, the two store doc comments and the threat model
(asset table + revision row) say where the data lives and why.
- Tests: default root is the new path and is never under the install
root; same for the log directory.

Closes #91 (blocks #67). Part of #62.

## How it was tested

- `dotnet build -warnaserror` 0 warnings; `dotnet format
--verify-no-changes` clean.
- `gclo.Engine.Tests` 425/425, `gclo.Cli.Tests` 129/129; line coverage
100% on `gclo.Engine` and `gclo.ViewModels`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Signed-off-by: James Maes <james@kof22.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-10 14:30:48 -05:00
james.maesandClaude Fable 5.1 e411c30344 ci: retry PSScriptAnalyzer per file when it throws (#90)
PSScriptAnalyzer 1.25.0 still throws `Object reference not set to an
instance of an object` intermittently even one file per call; it failed
the format gate of the v1.0.2-beta.1 release run (38074357696) until a
re-run. Each file is now analyzed up to three times (2 s pause, a
warning annotation per retry) and only a file that keeps throwing fails
the gate, with the analyzer's error. Findings still fail as before.

Closes #89 (part of #62).

Tested: `actionlint` clean; the loop run locally over the same scripts
reports 0 findings.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Signed-off-by: James Maes <james@kof22.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-10 14:16:12 -05:00
james.maesandClaude Fable 5.1 e63b64fb89 fix(release): keep build and publish on one resource configuration; smoke test what ships (#88)
## What

v1.0.1 and the beta.3 rehearsal crash at startup (`0xc000027b` in
`Microsoft.UI.Xaml.dll`). Root cause in #87: the shared release workflow
builds Release (framework-dependent) and then publishes self-contained
into the same `obj`, and the incremental `_GenerateProjectPriFileCore`
target skipped because its new inputs (the Windows App SDK `.pri` files
from the NuGet cache) were older than the index it had already written.
The published `gclo.pri` was 115 KB instead of 2.3 MB and lacked the
WinUI theme resources.

- `gclo/gclo.csproj`: `WindowsPackageType=None` and
`WindowsAppSDKSelfContained=true` unconditionally. gclo ships only
unpackaged and self-contained, so build and publish now share one
resource configuration and the incremental index is always right.
- `release.yml`: new `smoke` job between the gates and the shared
release. It restores, builds Release and publishes with the shared
workflow's exact commands (same incremental `obj` state), then runs the
FlaUI suite against the published `gclo.exe` through `GCLO_UITEST_EXE`.
`release` needs it, so a build that does not start can never be
published again.
- `docs/RELEASING.md`: the smoke job in "Watch the workflow".

Closes #87 (part of #62). Shared-workflow follow-up filed as
KofTwentyTwo/standards#22.

## Done outside this PR

- v1.0.1 marked prerelease with a warning in its notes ("A broken
release" runbook), so stable installs stop receiving it.
- 1.0.0 reinstalled on the maintainer's machine.

## How it was tested

- From clean `bin`/`obj` with the workflow's exact sequence (locked
restore, `dotnet build gclo.slnx -c Release -p:Platform=x64`, the
publish command): before the csproj change `gclo.pri` = 115,816 bytes
and the app exits `0xC000027B`; after it the build and the publish both
give 2,298,032 bytes and the published app opens its main window.
- `actionlint` clean.
- Next: tag `v1.0.2-beta.1`, **install it on a clean machine**, then
`v1.0.2`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Signed-off-by: James Maes <james@kof22.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-10 13:04:22 -05:00
james.maesandClaude Fable 5.1 7511d4568d ci(release): open the packaging PR with a release GitHub App token (#86)
## What

`protect-main` requires signed commits, and the `build(packaging): …` PR
the `packages` job opens had an unsigned commit. #82's DCO sign-off was
not enough: `peter-evans/create-pull-request` signs only with a bot
token and explicitly not with a PAT, which is why the v1.0.1 packaging
PR went #80 → #83 (re-created unsigned by "update branch") → #84
(cherry-picked and signed by hand).

- `packages` now mints a short-lived token from a release GitHub App
(`actions/create-github-app-token` v3.2.0, SHA-pinned) using the
repository variable `RELEASE_APP_CLIENT_ID` and the
`release`-environment secret `RELEASE_APP_PRIVATE_KEY` (contents + pull
requests write, this repository only, no bypass), and opens the PR with
it and `sign-commits: true`. GitHub signs the commit, its author is the
App's `[bot]` user (exempt from `pr / dco`), and the PR still triggers
the required checks. Same pattern as the standards repository's own
release automation.
- `DEPS_PAT` is no longer used by the release workflow (it stays
optional for `nuget-updates.yml`). The preflight step fails when the App
id or key is missing.
- `docs/RELEASING.md` (tokens table + "Why a GitHub App" with the
one-time setup), ADR 0003 and the threat model revision table record the
change.

Closes #85 (follows #81, part of #62).

## Owner steps before the next stable release

1. Create a GitHub App (Settings → Developer settings → GitHub Apps):
installed **only on KofTwentyTwo/gclo**, permissions **Contents: write**
and **Pull requests: write**, no ruleset bypass.
2. Repository variable `RELEASE_APP_CLIENT_ID` = the App's client id.
3. `release` environment secret `RELEASE_APP_PRIVATE_KEY` = the App's
private key (`.pem`), e.g. `op read "op://<vault>/<item>/private key" |
gh secret set RELEASE_APP_PRIVATE_KEY --env release --repo
KofTwentyTwo/gclo`.

## How it was tested

- `actionlint` clean; `create-github-app-token@bcd2ba4` is the `v3.2.0`
tag and exposes `client-id`, `private-key`, `permission-contents`,
`permission-pull-requests`.
- Not exercised on a tag: the next stable release is the first run. If
the App is not set up by then, the `packages` job fails at its preflight
and can be re-run alone after the secrets are added.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Signed-off-by: James Maes <james@kof22.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-10 12:24:57 -05:00
james.maes 34b6870f3d build(packaging): point the Scoop and Chocolatey manifests at v1.0.1 (#84)
Generated by the Release workflow for tag `v1.0.1`.

- `bucket/gclo.json` (Scoop) and `packaging/chocolatey` now point at
  `gclo-cli-win-x64-1.0.1.zip`
(SHA-256
`641ae4100022fba3fe489f8abe6ccc43186c070087d3edbf3a7891d5dc7428f7`).
- `scoop update gclo` picks this up as soon as this PR is merged (Scoop
  reads the manifest from `main`); the Chocolatey package was pushed to
  chocolatey.org.

Relates to #9.

Signed-off-by: James Maes <james@kof22.com>
2026-10-10 12:14:15 -05:00
james.maesandClaude Fable 5.1 f2b3900490 ci(release): sign off the generated packaging commit (#82)
## What

The `packages` job's `build(packaging): …` pull request is generated by
`peter-evans/create-pull-request`, and its commit carried no
`Signed-off-by:` trailer, so the standards' `pr / dco` gate (which needs
a sign-off matching the commit author) failed on the first real one, #80
for v1.0.1. The action now sets `author` and `committer` to the same
identity (the actor who pushed the tag,
`<id>+<login>@users.noreply.github.com`) and `signoff: true`, so the
trailer it adds matches the author the check compares against.

Closes #81 (part of #62). #80 itself needs its commit amended with a
sign-off (or an admin merge); this PR fixes every later release.

## How it was tested

- `actionlint` clean.
- The three inputs exist on the pinned `create-pull-request` v8.1.1
(checked `action.yml` at the SHA).
- Not exercised on a tag: the next stable release is the first run.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Signed-off-by: James Maes <james@kof22.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-10 11:45:51 -05:00
19 changed files with 616 additions and 70 deletions

No files matched your search

+159
View File
@@ -0,0 +1,159 @@
# Copyright (c) 2026 James Maes (KofTwentyTwo)
# SPDX-License-Identifier: MIT
<#
.SYNOPSIS
Configures the Azure side of gclo's release signing (ADR 0008) and prints the
GitHub `release`-environment variables the workflow needs.
.DESCRIPTION
Idempotent. Run interactively by the owner after `Connect-AzAccount` into the
KofTwentyTwo tenant (Az.Accounts, Az.Resources and Az.CodeSigning modules).
It never creates a secret, key or certificate and never touches the signing
account, the publisher validation or the certificate profile themselves:
1. Reads the Artifact Signing account and its certificate profile and fails if
either is missing or the profile is not Active.
2. Ensures an Entra application + service principal for this repository.
3. Ensures a federated credential on it that trusts GitHub's OIDC issuer for
subject `repo:<owner/repo>:environment:<environment>` only.
4. Ensures the service principal holds "Artifact Signing Certificate Profile
Signer" scoped to the certificate profile, and nothing broader.
5. Prints the variable values to set with `gh variable set --env release`.
.PARAMETER Repository
The GitHub repository the credential is bound to (owner/name).
.PARAMETER Environment
The GitHub environment whose jobs may sign (its deployment rule limits it to
v* tags).
.PARAMETER ResourceGroup
Resource group that holds the signing account.
.PARAMETER AccountName
The Artifact Signing account name.
.PARAMETER ProfileName
The certificate profile name on that account.
.PARAMETER ApplicationName
Display name of the Entra application that represents this repository's
release job.
.EXAMPLE
Connect-AzAccount -Tenant koftwentytwooutlook.onmicrosoft.com
./.github/scripts/Set-ReleaseSigning.ps1
#>
[CmdletBinding(SupportsShouldProcess)]
param(
[string] $Repository = 'KofTwentyTwo/gclo',
[string] $Environment = 'release',
[string] $ResourceGroup = 'rg-code-signing',
[string] $AccountName = 'kof22signing',
[string] $ProfileName = 'releases',
[string] $ApplicationName = 'gclo-release-signing'
)
Set-StrictMode -Version Latest
$ErrorActionPreference = 'Stop'
$signerRole = 'Artifact Signing Certificate Profile Signer'
$issuer = 'https://token.actions.githubusercontent.com'
$subject = "repo:$Repository`:environment:$Environment"
$context = Get-AzContext
if($null -eq $context)
{
throw 'Not signed in. Run Connect-AzAccount into the KofTwentyTwo tenant first.'
}
Write-Output "Tenant $($context.Tenant.Id), subscription '$($context.Subscription.Name)' ($($context.Subscription.Id))"
# 1. The signing account and profile must already exist; this script never creates them.
# Az.CodeSigning has no account/profile cmdlets, so this reads the ARM resources.
$apiVersion = '2024-09-30-preview'
$accountPath = "/subscriptions/$($context.Subscription.Id)/resourceGroups/$ResourceGroup/providers/Microsoft.CodeSigning/codeSigningAccounts/$AccountName"
$accountResponse = Invoke-AzRestMethod -Method GET -Path "$accountPath`?api-version=$apiVersion"
if($accountResponse.StatusCode -ne 200)
{
throw "Signing account '$AccountName' not found in '$ResourceGroup' (HTTP $($accountResponse.StatusCode)): $($accountResponse.Content)"
}
$account = $accountResponse.Content | ConvertFrom-Json
$certProfileResponse = Invoke-AzRestMethod -Method GET -Path "$accountPath/certificateProfiles/$ProfileName`?api-version=$apiVersion"
if($certProfileResponse.StatusCode -ne 200)
{
throw "Certificate profile '$ProfileName' not found on '$AccountName' (HTTP $($certProfileResponse.StatusCode)): $($certProfileResponse.Content)"
}
$certProfile = $certProfileResponse.Content | ConvertFrom-Json
if($certProfile.properties.status -ne 'Active')
{
throw "Certificate profile '$ProfileName' is '$($certProfile.properties.status)', not Active."
}
$endpoint = $account.properties.accountUri.TrimEnd('/')
# The validated publisher is on the issued certificate (subjectName), not on the profile.
$certificate = $certProfile.properties.certificates | Where-Object { $_.status -eq 'Active' } | Select-Object -First 1
if($null -eq $certificate)
{
throw "Certificate profile '$ProfileName' has no active certificate."
}
$subjectName = (($certificate.subjectName -split ',\s*') | Where-Object { $_ -like 'CN=*' } | Select-Object -First 1) -replace '^CN='
Write-Output "Signing account '$AccountName' in $($account.location): endpoint $endpoint."
Write-Output "Profile '$ProfileName' is Active (type $($certProfile.properties.profileType)); certificate subject CN='$subjectName'."
# 2. One application per repository, so the trust can be revoked per repository.
$app = Get-AzADApplication -DisplayName $ApplicationName | Select-Object -First 1
if($null -eq $app)
{
if($PSCmdlet.ShouldProcess($ApplicationName, 'Create Entra application'))
{
$app = New-AzADApplication -DisplayName $ApplicationName -SignInAudience AzureADMyOrg
}
}
$sp = Get-AzADServicePrincipal -ApplicationId $app.AppId
if($null -eq $sp)
{
if($PSCmdlet.ShouldProcess($ApplicationName, 'Create service principal'))
{
$sp = New-AzADServicePrincipal -ApplicationId $app.AppId
}
}
Write-Output "Application '$ApplicationName': client id $($app.AppId), service principal $($sp.Id)."
# 3. Federated credential: GitHub OIDC, this repository's release environment only.
$credentialName = "github-$($Repository.Replace('/', '-'))-$Environment"
$existing = Get-AzADAppFederatedCredential -ApplicationObjectId $app.Id | Where-Object { $_.Subject -eq $subject -and $_.Issuer -eq $issuer }
if($null -eq $existing)
{
if($PSCmdlet.ShouldProcess($credentialName, "Create federated credential for $subject"))
{
New-AzADAppFederatedCredential -ApplicationObjectId $app.Id -Name $credentialName -Issuer $issuer -Subject $subject -Audience 'api://AzureADTokenExchange' | Out-Null
}
}
Write-Output "Federated credential trusts $issuer for subject '$subject'."
# 4. Signer role on the certificate profile only. Owner/Contributor grant no signing right.
$profileScope = $certProfile.Id
$assignment = Get-AzRoleAssignment -ObjectId $sp.Id -Scope $profileScope -RoleDefinitionName $signerRole -ErrorAction SilentlyContinue
if($null -eq $assignment)
{
if($PSCmdlet.ShouldProcess($profileScope, "Assign '$signerRole'"))
{
New-AzRoleAssignment -ObjectId $sp.Id -Scope $profileScope -RoleDefinitionName $signerRole | Out-Null
}
}
$broader = Get-AzRoleAssignment -ObjectId $sp.Id | Where-Object { $_.Scope -ne $profileScope }
if($broader)
{
Write-Warning "The service principal also holds: $(($broader | ForEach-Object { "$($_.RoleDefinitionName) @ $($_.Scope)" }) -join '; '). Remove anything it does not need."
}
Write-Output "'$signerRole' is assigned at $profileScope."
# 5. The values the workflow reads (none of them is a secret).
Write-Output ''
Write-Output "gh variable set AZURE_TENANT_ID --env $Environment --repo $Repository --body '$($context.Tenant.Id)'"
Write-Output "gh variable set AZURE_CLIENT_ID --env $Environment --repo $Repository --body '$($app.AppId)'"
Write-Output "gh variable set AZURE_SUBSCRIPTION_ID --env $Environment --repo $Repository --body '$($context.Subscription.Id)'"
Write-Output "gh variable set TRUSTED_SIGNING_ENDPOINT --env $Environment --repo $Repository --body '$endpoint'"
Write-Output "gh variable set TRUSTED_SIGNING_ACCOUNT --env $Environment --repo $Repository --body '$AccountName'"
Write-Output "gh variable set TRUSTED_SIGNING_PROFILE --env $Environment --repo $Repository --body '$ProfileName'"
Write-Output "gh variable set TRUSTED_SIGNING_SUBJECT --env $Environment --repo $Repository --body '$subjectName'"
+21 -4
View File
@@ -169,13 +169,30 @@ jobs:
shell: pwsh
run: |
Install-Module PSScriptAnalyzer -RequiredVersion 1.25.0 -Scope CurrentUser -Force
# One file per call: PSScriptAnalyzer 1.25.0 intermittently fails with
# "Object reference not set to an instance of an object" when it is
# handed a directory, and never when it is handed a single script.
# One file per call, three attempts each: PSScriptAnalyzer 1.25.0
# intermittently throws "Object reference not set to an instance of an
# object" from inside the analyzer (#89); a retry has always passed. A
# file that throws three times fails the gate with the analyzer's error.
$settings = (Resolve-Path ./PSScriptAnalyzerSettings.psd1).Path
$scripts = Get-ChildItem -Path .github/scripts, packaging/chocolatey/tools -Recurse -Include *.ps1, *.psm1, *.psd1
$findings = @()
foreach ($script in $scripts) { $findings += @(Invoke-ScriptAnalyzer -Path $script.FullName -Settings $settings) }
foreach ($script in $scripts)
{
for ($attempt = 1; $attempt -le 3; $attempt++)
{
try
{
$findings += @(Invoke-ScriptAnalyzer -Path $script.FullName -Settings $settings -ErrorAction Stop)
break
}
catch
{
if ($attempt -eq 3) { throw }
Write-Output "::warning file=$($script.FullName)::PSScriptAnalyzer threw on attempt $attempt ($($_.Exception.Message)); retrying."
Start-Sleep -Seconds 2
}
}
}
foreach ($f in $findings) { Write-Output "::error file=$($f.ScriptPath),line=$($f.Line)::$($f.RuleName): $($f.Message)" }
if ($findings.Count -gt 0) { exit 1 }
Write-Output 'PSScriptAnalyzer: no findings.'
+154 -10
View File
@@ -24,14 +24,17 @@
# published stable installer, so the job runs once the WINGET_PACKAGE_ID variable
# is set (docs/RELEASING.md) and fails if the token is missing from then on. The
# tokens live in the `release` environment, which only v* tags can use:
# DEPS_PAT fine-grained token: contents + pull requests (write) on this
# repository, so the packaging PR runs the required checks
# RELEASE_APP_PRIVATE_KEY private key of the release GitHub App (contents +
# pull requests write on this repository only); the job mints a
# short-lived token from it, so the packaging PR's commit is
# signed by GitHub and the PR runs the required checks
# CHOCO_API_KEY chocolatey.org API key
# WINGET_TOKEN fine-grained token that can fork and open pull requests on
# public repositories (microsoft/winget-pkgs)
# NUGET_API_KEY nuget.org key with push rights for gclo.Engine (NUGET_PUBLISH)
# plus the repository variable WINGET_PACKAGE_ID (KofTwentyTwo.gclo, set after the
# one-time manual `wingetcreate new`).
# plus the repository variables RELEASE_APP_CLIENT_ID (the release App's client id)
# and WINGET_PACKAGE_ID (KofTwentyTwo.gclo, set after the one-time manual
# `wingetcreate new`).
name: Release
on:
@@ -84,9 +87,64 @@ jobs:
permissions:
contents: read
# The gates test what `dotnet build` produces; this job tests what ships. It
# publishes the app exactly as the shared workflow does (same restore, build
# and publish commands, so the same incremental obj state) and runs the FlaUI
# suite against that published gclo.exe. v1.0.1 passed every gate and crashed
# at startup because its published resource index was stale (#87); nothing is
# published until this passes.
smoke:
name: Smoke test the published app
needs: verify
runs-on: windows-latest
timeout-minutes: 30
permissions:
contents: read
steps:
- name: Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
# No NuGet cache: a release workflow must not consume runtime-generated
# caches (zizmor cache-poisoning); the locked restore is deterministic.
- name: Set up .NET SDK
uses: actions/setup-dotnet@a98b56852c35b8e3190ac28c8c2271da59106c68 # v6.0.0
with:
global-json-file: global.json
- name: Restore (locked)
run: dotnet restore gclo.slnx -p:Platform=x64 --locked-mode
- name: Build Release (as the shared workflow does before publishing)
run: dotnet build gclo.slnx -c Release -p:Platform=x64 -warnaserror --no-restore
- name: Publish app (the shared workflow's exact command)
env:
TAG: ${{ github.ref_name }}
run: >-
$version = $env:TAG.Substring(1);
dotnet publish gclo/gclo.csproj -c Release -p:Platform=x64 -r win-x64 --self-contained
"-p:Version=$version" -p:RestoreLockedMode=true -p:WindowsPackageType=None
-p:WindowsAppSDKSelfContained=true -p:PublishTrimmed=false -o publish/app
- name: Run the UI suite against the published exe
env:
GCLO_UITEST_EXE: ${{ github.workspace }}\publish\app\gclo.exe
GCLO_UITEST_ARTIFACTS: ${{ github.workspace }}\TestResults\smoke
run: dotnet test gclo.UiTests/gclo.UiTests.csproj --logger "trx;LogFileName=smoke.trx" --results-directory TestResults
- name: Upload smoke test diagnostics
if: failure()
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: smoke-test-diagnostics
path: TestResults
if-no-files-found: warn
release:
name: Release
needs: [verify, gates]
needs: [verify, gates, smoke]
uses: KofTwentyTwo/standards/.github/workflows/release-velopack.yml@e8ab30f8c60df437440ffd786c87678207246f5c # main 2026-10-09 (pre-1.0 draft, standards#5)
permissions:
contents: write # create and publish the GitHub release
@@ -106,7 +164,77 @@ jobs:
gclo.Engine.Tests
gclo.Cli.Tests
cli-project: gclo.Cli/gclo.Cli.csproj
sign: false # standards exception EX-0002 (#57): true once the Azure Trusted Signing identity is validated
# Authenticode (Azure Artifact Signing, formerly Trusted Signing) over OIDC: the
# shared workflow signs every published exe/dll and vpk signs Setup.exe and the
# update stub with the same identity. The identity lives in the `release`
# environment's variables (AZURE_CLIENT_ID, AZURE_TENANT_ID,
# AZURE_SUBSCRIPTION_ID, TRUSTED_SIGNING_ENDPOINT, TRUSTED_SIGNING_ACCOUNT,
# TRUSTED_SIGNING_PROFILE, docs/RELEASING.md) and is granted only to this
# repository's v* tags through a federated credential (#57, closes EX-0002).
sign: true
# The shipped artifacts carry valid Authenticode signatures: every exe inside the
# installer, the portable zip and the CLI zip, and Setup.exe itself, verify with
# `signtool verify /pa /all` and show the publisher the certificate profile was
# validated for. Runs on what was actually published, so a signing step that
# silently produced unsigned files fails the run (and the release is then
# handled per "A broken release" in docs/RELEASING.md), not a later user.
verify-signatures:
name: Verify signatures on the published assets
needs: release
runs-on: windows-latest
timeout-minutes: 15
permissions:
contents: read
env:
TAG: ${{ github.ref_name }}
K22_VERSION: ${{ needs.release.outputs.version }}
K22_CHANNEL: ${{ needs.release.outputs.prerelease == 'true' && 'dev' || 'stable' }}
EXPECTED_SUBJECT: ${{ vars.TRUSTED_SIGNING_SUBJECT }}
steps:
- name: Download the published assets
shell: pwsh
env:
GH_TOKEN: ${{ github.token }}
GH_REPO: ${{ github.repository }}
run: |
New-Item -ItemType Directory -Force assets | Out-Null
gh release download $env:TAG --dir assets --pattern "gclo-$env:K22_CHANNEL-Setup.exe" --pattern "gclo-$env:K22_CHANNEL-Portable.zip" --pattern "gclo-cli-win-x64-$env:K22_VERSION.zip"
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
Expand-Archive assets/gclo-$env:K22_CHANNEL-Portable.zip -DestinationPath assets/portable
Expand-Archive assets/gclo-cli-win-x64-$env:K22_VERSION.zip -DestinationPath assets/cli
- name: signtool verify /pa /all on every shipped executable
shell: pwsh
run: |
if ([string]::IsNullOrEmpty($env:EXPECTED_SUBJECT))
{
Write-Output '::error::TRUSTED_SIGNING_SUBJECT is not set in the release environment (docs/RELEASING.md).'
exit 1
}
$signtool = Get-ChildItem "${env:ProgramFiles(x86)}\Windows Kits\10\bin" -Recurse -Filter signtool.exe |
Where-Object { $_.FullName -match '\\x64\\' } | Sort-Object FullName -Descending | Select-Object -First 1
$files = @(Get-Item assets/gclo-$env:K22_CHANNEL-Setup.exe) + @(Get-ChildItem assets/portable, assets/cli -Recurse -Include *.exe, *.dll |
Where-Object { $_.Name -like 'gclo*' -or $_.Name -in 'Update.exe' })
$failed = 0
foreach ($f in $files)
{
& $signtool.FullName verify /pa /all /v $f.FullName | Out-Null
$sig = Get-AuthenticodeSignature -LiteralPath $f.FullName
$subject = $sig.SignerCertificate.Subject
$timestamped = $null -ne $sig.TimeStamperCertificate
if ($LASTEXITCODE -ne 0 -or $sig.Status -ne 'Valid' -or -not $timestamped -or $subject -notlike "*$env:EXPECTED_SUBJECT*")
{
Write-Output "::error file=$($f.Name)::signature status '$($sig.Status)', timestamped=$timestamped, subject '$subject' (expected '*$env:EXPECTED_SUBJECT*', signtool exit $LASTEXITCODE)"
$failed++
}
else
{
Write-Output "ok $($f.Name) $subject (timestamped)"
}
}
if ($failed -gt 0) { exit 1 }
Write-Output "All $($files.Count) shipped executables carry a valid, timestamped signature by '$env:EXPECTED_SUBJECT'."
# Scoop and Chocolatey (#9), stable releases only. The repository is its own
# Scoop bucket (bucket/gclo.json) and ships the Chocolatey package source
@@ -136,13 +264,14 @@ jobs:
- name: Require the publishing secrets
shell: pwsh
env:
DEPS_PAT: ${{ secrets.DEPS_PAT }}
RELEASE_APP_CLIENT_ID: ${{ vars.RELEASE_APP_CLIENT_ID }}
RELEASE_APP_PRIVATE_KEY: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
CHOCO_API_KEY: ${{ secrets.CHOCO_API_KEY }}
run: |
$missing = @('DEPS_PAT', 'CHOCO_API_KEY') | Where-Object { [string]::IsNullOrEmpty((Get-Item -Path "env:$_" -ErrorAction SilentlyContinue).Value) }
$missing = @('RELEASE_APP_CLIENT_ID', 'RELEASE_APP_PRIVATE_KEY', 'CHOCO_API_KEY') | Where-Object { [string]::IsNullOrEmpty((Get-Item -Path "env:$_" -ErrorAction SilentlyContinue).Value) }
if ($missing)
{
Write-Output "::error::Missing in the release environment: $($missing -join ', '). Add them (docs/RELEASING.md) and re-run this job."
Write-Output "::error::Missing in the release environment (or repository variables): $($missing -join ', '). Add them (docs/RELEASING.md) and re-run this job."
exit 1
}
@@ -173,10 +302,25 @@ jobs:
CHOCO_API_KEY: ${{ secrets.CHOCO_API_KEY }}
run: choco push (Get-ChildItem artifacts/chocolatey/*.nupkg | Select-Object -First 1).FullName --source https://push.chocolatey.org/ --api-key $env:CHOCO_API_KEY
# protect-main requires signed commits and a DCO sign-off. The action only
# signs with a bot token (a PAT is explicitly unsupported), so the PR is
# opened with a short-lived token of the release GitHub App: GitHub signs
# the commit, its author is the App's [bot] user (exempt from the DCO
# check), and the PR still triggers the required checks (#81, #85).
- name: Mint a release App token
id: app
uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
with:
client-id: ${{ vars.RELEASE_APP_CLIENT_ID }}
private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
permission-contents: write
permission-pull-requests: write
- name: Open a PR with the updated package manifests
uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
with:
token: ${{ secrets.DEPS_PAT }}
token: ${{ steps.app.outputs.token }}
sign-commits: true
base: main
branch: packaging/v${{ needs.release.outputs.version }}
delete-branch: true
+8 -2
View File
@@ -62,9 +62,15 @@ gh attestation verify .\gclo-stable-Setup.exe --repo KofTwentyTwo/gclo --signer-
# 3. Dependencies: the SBOM is attested too
gh attestation verify .\gclo-cli-win-x64-<version>.zip --repo KofTwentyTwo/gclo --signer-repo KofTwentyTwo/standards --predicate-type https://cyclonedx.org/bom
# 4. Publisher: Setup.exe and every gclo executable are Authenticode-signed (Azure
# Artifact Signing, SHA-256, RFC 3161 timestamp) by KofTwentyTwo
signtool verify /pa /all /v .\gclo-stable-Setup.exe
Get-AuthenticodeSignature .\gclo-stable-Setup.exe | Format-List Status, SignerCertificate, TimeStamperCertificate
```
The binaries are not yet Authenticode-signed (standards exception [EX-0002](https://github.com/KofTwentyTwo/standards/blob/main/exceptions/register.md#ex-0002), [#57](https://github.com/KofTwentyTwo/gclo/issues/57)), so step 2 is the origin check until `Get-AuthenticodeSignature` can be.
Windows checks step 4 for you: a signed installer carries the publisher name in the
SmartScreen and UAC prompts instead of "Unknown publisher".
## Getting a token
@@ -110,7 +116,7 @@ On launch, gclo shows a brief branded splash, then the **Quick Sync** connect ca
**Settings** (File > Settings…) let you set a default GitHub token (stored in the Windows Credential Manager), the default target folder (with a folder picker), the default parallelism, and the theme (System, Light, or Dark); an Advanced section toggles the startup splash and its duration.
**Activity log:** View > Activity log… shows the tail of today's log and links to the logs folder. Logs live under `%LOCALAPPDATA%\gclo\logs`, one file per day; they record run parameters and per-repo failures and never contain your token (see [SECURITY.md](SECURITY.md)).
**Activity log:** View > Activity log… shows the tail of today's log and links to the logs folder. Logs live under `%LOCALAPPDATA%\KofTwentyTwo\gclo\logs`, one file per day; they record run parameters and per-repo failures and never contain your token (see [SECURITY.md](SECURITY.md)).
**Updates:** Help > Check for updates… downloads and applies the latest release for your channel. Self-update is only available in installed builds (not the portable zip or a local debug build).
+7 -5
View File
@@ -110,8 +110,10 @@ is a vulnerability: please report it through the channel above.
[README](README.md#verifying-a-release).
- Self-update downloads only from this repository's GitHub Releases and verifies each
package against the release's `releases.<channel>.json` feed.
- The binaries are **not yet Authenticode-signed**: KofTwentyTwo standards exception
[EX-0002](https://github.com/KofTwentyTwo/standards/blob/main/exceptions/register.md#ex-0002)
(tracked here as [#57](https://github.com/KofTwentyTwo/gclo/issues/57)). Until they
are, expect a SmartScreen prompt on first install, and prefer the checksum and
attestation checks over trusting a download by its name.
- Setup.exe, the update stub and every gclo executable and library are
**Authenticode-signed** with Azure Artifact Signing (SHA-256, RFC 3161 timestamp) in
the release workflow, over OIDC with an identity that only this repository's release
tags can use; no signing key or secret exists outside Azure. The workflow verifies
the published assets with `signtool verify /pa /all` and fails if any shipped
executable is unsigned or signed by another publisher. Check the publisher yourself
with `Get-AuthenticodeSignature` (README, "Verifying a release").
+25 -25
View File
@@ -1,28 +1,28 @@
{
"version": "1.0.0",
"description": "Git Clone Large Organizations: clone or update every repository of a GitHub organization or user account, in parallel (command-line edition)",
"homepage": "https://github.com/KofTwentyTwo/gclo",
"license": "MIT",
"notes": [
"gclo needs a GitHub personal access token: set GITHUB_TOKEN, or pass --token-env, --token-file, or --token-stdin.",
"The desktop app is a separate download: https://github.com/KofTwentyTwo/gclo/releases"
],
"architecture": {
"64bit": {
"url": "https://github.com/KofTwentyTwo/gclo/releases/download/v1.0.0/gclo-cli-win-x64.zip",
"hash": "42805ca95a4f4d306df04f47a2b9aba54eee3df11cda8e3f201fe5a58311feee"
}
},
"bin": "gclo.exe",
"checkver": "github",
"autoupdate": {
"architecture": {
"64bit": {
"url": "https://github.com/KofTwentyTwo/gclo/releases/download/v$version/gclo-cli-win-x64-$version.zip",
"hash": {
"url": "$baseurl/SHA256SUMS"
}
}
}
"version": "1.0.1",
"description": "Git Clone Large Organizations: clone or update every repository of a GitHub organization or user account, in parallel (command-line edition)",
"homepage": "https://github.com/KofTwentyTwo/gclo",
"license": "MIT",
"notes": [
"gclo needs a GitHub personal access token: set GITHUB_TOKEN, or pass --token-env, --token-file, or --token-stdin.",
"The desktop app is a separate download: https://github.com/KofTwentyTwo/gclo/releases"
],
"architecture": {
"64bit": {
"url": "https://github.com/KofTwentyTwo/gclo/releases/download/v1.0.1/gclo-cli-win-x64-1.0.1.zip",
"hash": "641ae4100022fba3fe489f8abe6ccc43186c070087d3edbf3a7891d5dc7428f7"
}
},
"bin": "gclo.exe",
"checkver": "github",
"autoupdate": {
"architecture": {
"64bit": {
"url": "https://github.com/KofTwentyTwo/gclo/releases/download/v$version/gclo-cli-win-x64-$version.zip",
"hash": {
"url": "$baseurl/SHA256SUMS"
}
}
}
}
}
+80 -4
View File
@@ -64,13 +64,80 @@ its first submission cannot be automated; see below.
| Job | Runs for | Needs | Publishes |
| --- | -------- | ----- | --------- |
| `release` (shared workflow) | every tag | nothing beyond `GITHUB_TOKEN` | the GitHub Release: Setup, portable, full/delta packages, feed, CLI zip, SBOMs, `SHA256SUMS`, provenance and SBOM attestations |
| `packages` | stable only | `DEPS_PAT` (fine-grained token: contents and pull requests, write, this repository, ≤ 90 days), `CHOCO_API_KEY` (chocolatey.org) | the Chocolatey package pushed to chocolatey.org, and a `build(packaging): …` pull request against `main` with `bucket/gclo.json` and `packaging/chocolatey` pointed at the release |
| `release` (shared workflow) | every tag | the signing identity, as `release`-environment **variables** (no secret exists): `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_SUBSCRIPTION_ID`, `TRUSTED_SIGNING_ENDPOINT`, `TRUSTED_SIGNING_ACCOUNT`, `TRUSTED_SIGNING_PROFILE` (see "Code signing") | the GitHub Release: Setup, portable, full/delta packages, feed, CLI zip, SBOMs, `SHA256SUMS`, provenance and SBOM attestations; every exe/dll and Setup.exe Authenticode-signed |
| `verify-signatures` | every tag | `TRUSTED_SIGNING_SUBJECT` (`release`-environment variable: the publisher name on the certificate, as validated by Azure) | nothing; fails the run when a shipped executable is unsigned, untimestamped or signed by another publisher |
| `packages` | stable only | `RELEASE_APP_PRIVATE_KEY` (private key of the release GitHub App, see below) plus the repository variable `RELEASE_APP_CLIENT_ID`, `CHOCO_API_KEY` (chocolatey.org) | the Chocolatey package pushed to chocolatey.org, and a `build(packaging): …` pull request against `main` with `bucket/gclo.json` and `packaging/chocolatey` pointed at the release |
| `winget` | stable only, once the repository variable `WINGET_PACKAGE_ID` is set (`KofTwentyTwo.gclo`, after the one-time manual submission below) | `WINGET_TOKEN` (fine-grained token that can fork and open pull requests on public repositories, ≤ 90 days); missing → the job fails | a manifest update PR on [microsoft/winget-pkgs](https://github.com/microsoft/winget-pkgs) |
| `nuget` | only when the repository variable `NUGET_PUBLISH` is `true` | `NUGET_API_KEY` (nuget.org, push rights for `gclo.Engine`) | `gclo.Engine` on nuget.org |
Why `DEPS_PAT`: a pull request opened with the default `GITHUB_TOKEN` triggers no
status checks, so the packaging PR could never satisfy `main`'s required checks.
Why a GitHub App: `main` requires signed commits, a DCO sign-off, and the full set
of status checks. A pull request opened with the default `GITHUB_TOKEN` triggers
no checks, and the action that opens the PR cannot sign commits with a personal
access token. With a short-lived token minted from the App, GitHub signs the
commit, its author is the App's `[bot]` user (exempt from the DCO check), and the
checks run. Create the App once (the same pattern the standards repository uses):
GitHub App installed **only on this repository**, permissions Contents and Pull
requests **write**, no ruleset bypass. Store its client id as the Actions variable
`RELEASE_APP_CLIENT_ID` and its private key (`.pem`) as `RELEASE_APP_PRIVATE_KEY`
in the `release` environment; never as a repository secret or a committed file.
## Code signing
Every release is Authenticode-signed with **Azure Artifact Signing** (formerly Trusted
Signing): the shared workflow signs every published `.exe`/`.dll` (app and CLI) before
packing, and `vpk pack` signs `Setup.exe` and the update stub with the same identity
(`--azureTrustedSignFile`). Always SHA-256 with an RFC 3161 timestamp from
`http://timestamp.acs.microsoft.com`. `SHA256SUMS`, the Velopack feed and the
attestations are produced after signing, so they describe the signed files. The
`verify-signatures` job then downloads what was published and runs
`signtool verify /pa /all` on Setup.exe and every gclo executable (ADR
[0008](adr/0008-azure-artifact-signing.md)).
There is **no signing secret**: the release job logs in to Azure over GitHub OIDC
(`azure/login`) as an Entra application whose federated credential trusts only this
repository's `release` environment, and that application holds only the
*Artifact Signing Certificate Profile Signer* role on the certificate profile.
The identity is configuration, not a secret, so it lives in `release`-environment
variables:
| Variable | Value |
| --- | --- |
| `AZURE_TENANT_ID` | the Entra tenant GUID (not the directory domain) |
| `AZURE_CLIENT_ID` | the application (client) id of `gclo-release-signing` |
| `AZURE_SUBSCRIPTION_ID` | the subscription that holds the signing account |
| `TRUSTED_SIGNING_ENDPOINT` | the account's regional endpoint, e.g. `https://eus.codesigning.azure.net` |
| `TRUSTED_SIGNING_ACCOUNT` | the signing account name (`kof22signing`) |
| `TRUSTED_SIGNING_PROFILE` | the certificate profile name (`releases`) |
| `TRUSTED_SIGNING_SUBJECT` | the validated publisher name on the certificate, checked by `verify-signatures` |
A missing variable fails the Azure login, and the run with it; nothing unsigned is
published. The Azure side (application, federated credential, role assignment) is
administered interactively by the owner; `.github/scripts/Set-ReleaseSigning.ps1`
records the exact steps and is idempotent.
### Signing locally
Only for a one-off (for example re-signing a hotfix build by hand); releases are
signed in CI. You need SignTool (Windows SDK), the .NET 8 runtime, the
[Microsoft.ArtifactSigning.Client](https://www.nuget.org/packages/Microsoft.ArtifactSigning.Client)
package (the `dlib`), and an identity holding the *Certificate Profile Signer* role:
```powershell
# One-time: the dlib, and a metadata file with the same values as the variables above
nuget install Microsoft.ArtifactSigning.Client -x -OutputDirectory $env:LOCALAPPDATA\ArtifactSigning
@{ Endpoint = 'https://eus.codesigning.azure.net'; CodeSigningAccountName = 'kof22signing'; CertificateProfileName = 'releases' } |
ConvertTo-Json | Set-Content $env:LOCALAPPDATA\ArtifactSigning\metadata.json
# Sign in as an authorized identity (the dlib uses the Azure CLI / Azure PowerShell credential)
az login --tenant <tenant GUID>
# Sign and verify
$signtool = Get-ChildItem "${env:ProgramFiles(x86)}\Windows Kits\10\bin" -Recurse -Filter signtool.exe | Where-Object FullName -match '\\x64\\' | Sort-Object FullName -Descending | Select-Object -First 1
& $signtool sign /v /fd SHA256 /tr http://timestamp.acs.microsoft.com /td SHA256 `
/dlib "$env:LOCALAPPDATA\ArtifactSigning\Microsoft.ArtifactSigning.Client\bin\x64\Azure.CodeSigning.Dlib.dll" `
/dmdf "$env:LOCALAPPDATA\ArtifactSigning\metadata.json" .\gclo.exe
& $signtool verify /pa /all /v .\gclo.exe
```
## First winget submission (one-time, manual)
@@ -148,11 +215,20 @@ Both install the same asset, `gclo-cli-win-x64-<version>.zip`, by URL and SHA-25
- **Gates** — the full `ci` workflow, exactly as a pull request runs it,
including the FlaUI end-to-end suite. If a gate fails, fix the cause on
`main` and cut a new patch version; never reuse the tag.
- **Smoke test the published app** — publishes the app with the shared
workflow's exact commands and runs the FlaUI suite against that published
`gclo.exe`. The gates test what `dotnet build` produces; this tests what
ships (1.0.1 passed every gate and crashed at startup, #87). Nothing is
published until it passes.
- **Release** (shared workflow): locked restore, Release build with warnings
as errors, tests with the 100% coverage gate, publish, Velopack pack, SBOMs,
`SHA256SUMS`, provenance, a **draft** GitHub Release with every asset and
generated notes, then **publish** — releases are immutable, so everything
lands while the release is still a draft.
- **Verify signatures on the published assets** — `signtool verify /pa /all`
on Setup.exe and every gclo executable inside the portable and CLI zips,
checking the publisher name and the timestamp. A failure here means a
published release is unsigned: handle it as "A broken release".
- **Scoop and Chocolatey**, **winget**, **NuGet** — the publishers described
above; each fails loudly when it cannot publish.
+3 -1
View File
@@ -47,7 +47,9 @@ and hash; `PackagingManifestTests` keeps both manifests valid and in agreement.
- Stable releases are consumable via `scoop bucket add gclo <repo>` with no external
account; prereleases never touch package managers.
- The generated manifest pull request targets `main` and goes through the normal
gates (with `DEPS_PAT` it also gets status checks).
gates: it is opened with a short-lived release GitHub App token, so its commit
is signed by GitHub, exempt from the DCO check as a bot, and runs the required
status checks (#85).
- Security: a new distribution channel; both channels verify the asset hash
(threat model T2), and the hash they pin is the one `SHA256SUMS` attests.
- Follow-up: `CHOCO_API_KEY` and the first Chocolatey moderation (#7).
+60
View File
@@ -0,0 +1,60 @@
# 0008. Authenticode-sign releases with Azure Artifact Signing over GitHub OIDC
- Status: accepted
- Date: 2026-10-10
- Supersedes: KofTwentyTwo standards exception EX-0002 for this repository
## Context
K22-REL-05 requires Windows executables and installers to be Authenticode-signed.
Until now gclo shipped unsigned (exception EX-0002, #57): users saw "Unknown
publisher" in SmartScreen and UAC, and the only origin check was the build-provenance
attestation, which proves which workflow built a file, not who publishes it.
KofTwentyTwo now has an Azure Artifact Signing (formerly Trusted Signing) account
with a completed publisher identity validation and an active Public Trust
certificate profile. The standards' shared `release-velopack.yml` already carries
the signing steps behind its `sign` input: `azure/login` over OIDC, then
`azure/artifact-signing-action` over every published `.exe`/`.dll`, then `vpk pack
--azureTrustedSignFile` so Setup.exe and the update stub are signed with the same
identity.
## Decision
- Turn the shared workflow's `sign` input on. Signing happens after publish and
before packing; `SHA256SUMS`, the Velopack feed and the attestations are
computed over the signed files. SHA-256 digests and RFC 3161 timestamps
(`http://timestamp.acs.microsoft.com`) always.
- Authenticate with **GitHub OIDC**, never a secret: an Entra application
(`gclo-release-signing`) with a federated credential whose subject is
`repo:KofTwentyTwo/gclo:environment:release`, so only a job running in the
tag-restricted `release` environment can obtain a token. The application holds
exactly one role, *Artifact Signing Certificate Profile Signer*, scoped to the
certificate profile. Owner or Contributor on the subscription grants no signing
right and is not given.
- The identity is configuration, not a secret: tenant, client and subscription ids,
endpoint, account and profile names are `release`-environment variables. Missing
values fail the Azure login, and nothing unsigned is published.
- A caller-side `verify-signatures` job downloads the published Setup.exe, portable
and CLI zips and runs `signtool verify /pa /all` plus `Get-AuthenticodeSignature`
on every gclo executable, checking status, timestamp and the validated publisher
name (`TRUSTED_SIGNING_SUBJECT`). It cannot stop a publish that already happened,
but it turns a silently unsigned release into a failed run handled by the broken-
release runbook; the shared workflow is asked to verify before publishing
(standards#22 follow-up).
- Local signing is documented for one-off needs only (SignTool + the
`Microsoft.ArtifactSigning.Client` dlib + an authorized Azure sign-in); releases
are signed in CI.
- The Azure configuration is scripted in `.github/scripts/Set-ReleaseSigning.ps1`
(idempotent, run interactively by the owner) so it can be audited and repeated.
## Consequences
- SmartScreen and UAC show the validated publisher; Velopack's installer and update
stub are signed, so silent self-update no longer rests on TLS plus the GitHub
account alone.
- Releases depend on Azure being reachable and the certificate profile being
active; a signing outage fails the release rather than shipping unsigned.
- No PFX, private key or client secret exists anywhere; nothing to rotate except
the federated credential if the repository or environment is renamed.
- EX-0002 closes for gclo once the first signed release verifies.
+4 -1
View File
@@ -26,7 +26,7 @@ GitHub.
| GitHub REST API | Lists organizations and repositories | Untrusted input (responses are parsed), authenticated by the PAT |
| Git remotes (`github.com`) | Clone and fetch over HTTPS via libgit2 | Untrusted input (repository content, including file paths) |
| Windows Credential Manager | Stores saved-account and default tokens | Trusted store; boundary is the Windows user account |
| Local data directory | `%LOCALAPPDATA%\gclo` (or `GCLO_DATA_DIR`): settings, accounts, logs | Trusted; same user |
| Local data directory | `%LOCALAPPDATA%\KofTwentyTwo\gclo` (or `GCLO_DATA_DIR`): settings, accounts, logs. Deliberately outside the Velopack install root `%LOCALAPPDATA%\gclo`, which Setup.exe deletes on reinstall (#91) | Trusted; same user |
| Target folder | Where repositories are written; may already contain repositories | Partly untrusted (pre-existing content, `.git` config) |
| WSL default distribution | Runs `git clone` for the "Clone in WSL" recovery | Semi-trusted (user-installed Linux environment) |
| Update feed | GitHub Releases of this repository, `releases.<channel>.json` | Untrusted until verified (HTTPS, package hashes, attestations) |
@@ -111,3 +111,6 @@ flowchart LR
| --- | --- | --- | --- |
| 2026-10-09 | v1.0.1 | James Maes (@KofTwentyTwo) | Initial model, covering the path-recovery, WSL clone, vault scoping, package-manager, and SBOM changes of 1.0.1 |
| 2026-10-09 | v1.0.1 | James Maes (@KofTwentyTwo) | T11 updated: releases build in the shared standards workflow; publishing tokens moved to the `release` environment (#76) |
| 2026-10-10 | v1.0.2 | James Maes (@KofTwentyTwo) | T11: the packaging PR is opened with a short-lived release GitHub App token (contents + pull requests on this repository, no bypass) instead of a long-lived PAT; the commit is GitHub-signed (#85) |
| 2026-10-10 | v1.0.2 | James Maes (@KofTwentyTwo) | Local data directory moved to `%LOCALAPPDATA%\KofTwentyTwo\gclo`: the Velopack install root is deleted by Setup.exe, which destroyed accounts.json and settings.json (#91) |
| 2026-10-10 | v1.0.2 | James Maes (@KofTwentyTwo) | T2/T11: releases are Authenticode-signed with Azure Artifact Signing over GitHub OIDC (no signing secret; federated credential bound to this repository's `release` environment; signer role scoped to the certificate profile) and the published assets are verified with `signtool verify /pa /all` (#57, ADR 0008) |
+15 -2
View File
@@ -128,18 +128,31 @@ public sealed class ActivityLogTests : IDisposable
[Fact]
public void DefaultDirectory_IsLocalAppDataGcloLogs()
public void DefaultDirectory_IsLocalAppDataKofTwentyTwoGcloLogs()
{
var log = new FileActivityLog();
string expected = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
"gclo", "logs");
"KofTwentyTwo", "gclo", "logs");
Assert.Equal(expected, log.LogDirectory);
}
[Fact]
public void DefaultDirectory_IsNotInsideTheVelopackInstallRoot()
{
// Setup.exe deletes %LOCALAPPDATA%\gclo (the install root) on reinstall (#91).
string installRoot = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "gclo");
Assert.False(
new FileActivityLog().LogDirectory.StartsWith(installRoot + Path.DirectorySeparatorChar, StringComparison.OrdinalIgnoreCase));
}
[Fact]
public void Directory_IsCreatedLazily_OnFirstWriteNotInConstructor()
{
+44
View File
@@ -0,0 +1,44 @@
/*
* Copyright (c) 2026 James Maes (KofTwentyTwo)
* SPDX-License-Identifier: MIT
*/
using gclo.ViewModels;
namespace gclo.Engine.Tests;
/// <summary>
/// Where gclo keeps its per-user data. The default must stay outside the Velopack
/// install root (%LOCALAPPDATA%\gclo): Setup.exe uninstalls an existing install
/// first and deletes that folder, which destroyed accounts.json and settings.json
/// in 1.0.2-beta.1 (#91).
/// </summary>
public sealed class GcloPathsTests
{
/// <summary>The default root is %LOCALAPPDATA%\KofTwentyTwo\gclo.</summary>
[Fact]
public void DefaultDataRoot_IsLocalAppDataKofTwentyTwoGclo()
{
string expected = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
"KofTwentyTwo", "gclo");
Assert.Equal(expected, GcloPaths.DefaultDataRoot);
}
/// <summary>The default root is never the install root nor anything under it.</summary>
[Fact]
public void DefaultDataRoot_IsNotTheVelopackInstallRoot()
{
string installRoot = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "gclo");
Assert.NotEqual(installRoot, GcloPaths.DefaultDataRoot, StringComparer.OrdinalIgnoreCase);
Assert.False(
GcloPaths.DefaultDataRoot.StartsWith(installRoot + Path.DirectorySeparatorChar, StringComparison.OrdinalIgnoreCase));
}
}
+4 -2
View File
@@ -25,14 +25,16 @@ public sealed class FileActivityLog : IActivityLog
/// <summary>Creates a log that writes under <paramref name="directory"/>.</summary>
/// <param name="directory">
/// Folder for the log files; defaults to %LOCALAPPDATA%\gclo\logs when null or blank.
/// Folder for the log files; defaults to %LOCALAPPDATA%\KofTwentyTwo\gclo\logs
/// when null or blank (the same data root as the app; never the Velopack
/// install root %LOCALAPPDATA%\gclo, which Setup.exe deletes, #91).
/// </param>
public FileActivityLog(string? directory = null)
{
LogDirectory = string.IsNullOrWhiteSpace(directory)
? Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
"gclo", "logs")
"KofTwentyTwo", "gclo", "logs")
: directory;
}
+1 -1
View File
@@ -12,7 +12,7 @@ namespace gclo.ViewModels;
/// <summary>
/// Persists account profiles as JSON at accounts.json under
/// <see cref="GcloPaths.DataRoot"/> (default %LOCALAPPDATA%\gclo) and their
/// <see cref="GcloPaths.DataRoot"/> (default %LOCALAPPDATA%\KofTwentyTwo\gclo) and their
/// tokens in an <see cref="ITokenVault"/>; the file holds metadata only and never a
/// token. Unlike <see cref="AppSettings"/>, accounts are primary user data, so write
/// failures in <see cref="Save"/>, <see cref="Delete"/>, and
+1 -1
View File
@@ -11,7 +11,7 @@ namespace gclo.ViewModels;
/// <summary>
/// User preferences persisted as JSON at settings.json under
/// <see cref="GcloPaths.DataRoot"/> (default %LOCALAPPDATA%\gclo, overridable via
/// <see cref="GcloPaths.DataRoot"/> (default %LOCALAPPDATA%\KofTwentyTwo\gclo, overridable via
/// GCLO_DATA_DIR). Uses Environment.GetFolderPath (not Windows.Storage.ApplicationData)
/// so the same path works whether the app runs packaged or unpackaged.
/// </summary>
+19 -8
View File
@@ -8,17 +8,23 @@ namespace gclo.ViewModels;
/// <summary>
/// The single seam for where gclo keeps its per-user data (settings, accounts,
/// logs). Defaults to %LOCALAPPDATA%\gclo; the GCLO_DATA_DIR environment variable
/// overrides it so UI tests (and portable setups) can point the whole app at an
/// isolated directory without touching the real profile. Components that accept
/// an explicit directory (test seams) are unaffected — this only feeds defaults.
/// logs). Defaults to %LOCALAPPDATA%\KofTwentyTwo\gclo; the GCLO_DATA_DIR
/// environment variable overrides it so UI tests (and portable setups) can point
/// the whole app at an isolated directory without touching the real profile.
/// Components that accept an explicit directory (test seams) are unaffected —
/// this only feeds defaults.
/// </summary>
/// <remarks>
/// The data root must never be the Velopack install root (%LOCALAPPDATA%\gclo):
/// Setup.exe uninstalls an existing install first and deletes that whole folder,
/// which destroyed the accounts and settings stored there (#91).
/// </remarks>
public static class GcloPaths
{
/// <summary>
/// Root directory for gclo's per-user data: GCLO_DATA_DIR when set and
/// non-empty, otherwise %LOCALAPPDATA%\gclo. Read on every access so a
/// value set before launch always wins over any cached default.
/// non-empty, otherwise <see cref="DefaultDataRoot"/>. Read on every access so
/// a value set before launch always wins over any cached default.
/// </summary>
public static string DataRoot =>
Environment.GetEnvironmentVariable("GCLO_DATA_DIR") is { Length: > 0 } dir
@@ -27,7 +33,12 @@ public static class GcloPaths
/// <summary>%LOCALAPPDATA%\gclo: the root used when GCLO_DATA_DIR is not set.</summary>
/// <summary>
/// %LOCALAPPDATA%\KofTwentyTwo\gclo: the root used when GCLO_DATA_DIR is not
/// set. Outside the Velopack install root on purpose (see the type remarks).
/// </summary>
public static string DefaultDataRoot =>
Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "gclo");
Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
"KofTwentyTwo", "gclo");
}
+7
View File
@@ -12,6 +12,13 @@
<UseWinUI>true</UseWinUI>
<WinUISDKReferences>false</WinUISDKReferences>
<EnableMsixTooling>true</EnableMsixTooling>
<!-- gclo ships only unpackaged and self-contained (Velopack). Fixing both here keeps
every build and publish on one configuration: the resource index (gclo.pri)
is generated incrementally in obj, and a framework-dependent build followed by
a self-contained publish left a stale index without the WinUI theme resources,
which crashed 1.0.1 at startup (0xc000027b). -->
<WindowsPackageType>None</WindowsPackageType>
<WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>
<Nullable>enable</Nullable>
<ImplicitUsings>disable</ImplicitUsings>
<!-- Velopack must run before any XAML starts, so the app supplies its own Main (Program.cs). -->
+2 -2
View File
@@ -6,7 +6,7 @@
<package xmlns="http://schemas.microsoft.com/packaging/2015/06/nuspec.xsd">
<metadata>
<id>gclo</id>
<version>1.0.0</version>
<version>1.0.1</version>
<title>gclo (Git Clone Large Organizations)</title>
<authors>James Maes</authors>
<owners>KofTwentyTwo</owners>
@@ -35,7 +35,7 @@ A GitHub personal access token is required: set `GITHUB_TOKEN`, or use `--token-
The desktop app (WinUI 3) is a separate download from the GitHub Releases page.
]]></description>
<releaseNotes>https://github.com/KofTwentyTwo/gclo/releases/tag/v1.0.0</releaseNotes>
<releaseNotes>https://github.com/KofTwentyTwo/gclo/releases/tag/v1.0.1</releaseNotes>
</metadata>
<files>
<file src="tools\**" target="tools" />
@@ -11,8 +11,8 @@ $toolsDir = Split-Path -Parent $MyInvocation.MyCommand.Definition
$packageArgs = @{}
$packageArgs.packageName = 'gclo'
$packageArgs.unzipLocation = $toolsDir
$packageArgs.url64bit = 'https://github.com/KofTwentyTwo/gclo/releases/download/v1.0.0/gclo-cli-win-x64.zip'
$packageArgs.checksum64 = '42805ca95a4f4d306df04f47a2b9aba54eee3df11cda8e3f201fe5a58311feee'
$packageArgs.url64bit = 'https://github.com/KofTwentyTwo/gclo/releases/download/v1.0.1/gclo-cli-win-x64-1.0.1.zip'
$packageArgs.checksum64 = '641ae4100022fba3fe489f8abe6ccc43186c070087d3edbf3a7891d5dc7428f7'
$packageArgs.checksumType64 = 'sha256'
Install-ChocolateyZipPackage @packageArgs