Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 85 additions & 7 deletions docs/github-repo-config.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,20 +6,21 @@ drift apart across dozens of repos.

Four functions in the `DotfilesHelpers` module:

| Function | Purpose |
| ------------------------- | ------------------------------------------------------ |
| `Get-GitHubRepoBaseline` | The desired state — a single, editable source of truth |
| `Get-GitHubRepoConfig` | Read-only audit of one, several or all repositories |
| `Set-GitHubRepoConfig` | Remediation, with `-WhatIf` dry runs |
| `Get-GitHubAppCredential` | Reads a GitHub App ID and private key from 1Password |
| Function | Purpose |
| ------------------------- | ----------------------------------------------------------------- |
| `Get-GitHubRepoBaseline` | The desired state — a single, editable source of truth |
| `Get-GitHubRepoConfig` | Read-only audit of one, several or all repositories |
| `Set-GitHubRepoConfig` | Remediation, with `-WhatIf` dry runs |
| `Get-GitHubAppCredential` | Reads a GitHub App ID and private key from 1Password or PEM file |

## Requirements

- The [GitHub CLI](https://cli.github.com/) (`gh`), authenticated with
`gh auth login`. All authentication is delegated to `gh`; no token is read,
stored or logged by these functions.
- The [1Password CLI](https://developer.1password.com/docs/cli/) (`op`), only
when rolling out GitHub App credentials.
when rolling out GitHub App credentials from 1Password. Not needed when the
key is read from a file with `-PrivateKeyPath`.

Your `gh` token needs these fine-grained permissions:

Expand Down Expand Up @@ -236,6 +237,50 @@ Unlike archived repositories — which reject writes and are therefore excluded
by default — forks are perfectly writable, so excluding them is a judgement
call rather than a technical constraint.

### Repositories that publish releases

`-HasRelease` keeps only the active, non-fork repositories that cut releases —
the ones that need the Automation App credential for the shared release-please
workflow. A repository qualifies when it has either:

- a root `release-please-config.json`, or
- at least one published (non-draft) release whose tag looks like a version
(`^v?\d+\.\d+`, so `v1.2.0` and `1.2` but not `v1`)

Data or state snapshots stored as releases, such as `db-2026-01-01` or
`news-state`, do not count. Each result records why it qualified on
`ReleaseEvidence`, and the number of repositories kept is reported on the
information stream:

```powershell
Get-GitHubRepoConfig -All -HasRelease -Check AppCredential |
Select-Object Repository, ReleaseEvidence, DriftCount
```

`-HasRelease` cannot be combined with `-IncludeArchived`. A repository whose
release list cannot be read (token, network or rate-limit trouble) is left out
with a warning and counted in the filter summary, never dropped silently.

### Logging

`Set-GitHubRepoConfig` writes one line per repository (what was applied,
previewed or skipped, by setting name) and a closing summary to the PowerShell
information stream. It is shown by default; silence it with
`-InformationAction SilentlyContinue` or capture it with
`-InformationVariable log`. Secret values are never logged — only the names of
the variables and secrets that were written. `-Verbose` adds per-step detail.

```text
DevSecNinja/docker: applied 2 of 2 change(s) [AppCredential/AUTOMATION_APP_ID, AppCredential/AUTOMATION_APP_PRIVATE_KEY]
DevSecNinja/blog: already compliant
Summary: 2 repositories, 1 already compliant, 0 not fully evaluated, 0 archived, 1 changed (2 change(s) applied), 0 item(s) skipped.
```

A repository with no drift in the categories that could be read, but with a
category that could not (`SkippedChecks`), is reported as `no drift found; not
evaluated [...]` rather than as compliant. Under `-WhatIf`, items skipped for
want of a credential are listed as skipped, not counted as previewed.

`-Check` selects what to audit; `-Category` selects what to remediate.
Repository names may be bare (`docker`), qualified (`DevSecNinja/docker`) or a
full URL. Bare names are qualified with `-Owner`, which defaults to
Expand Down Expand Up @@ -287,6 +332,29 @@ $env:OP_GITHUB_APP_ID_REF = 'op://Work/Bot/app-id'
$env:OP_GITHUB_APP_KEY_REF = 'op://Work/Bot/private-key'
```

### Reading the key from a file

Without 1Password, or for a one-off rotation, read the key straight from the
file GitHub issues (App settings → **General** → **Private keys** →
**Generate a private key**) and pass the App ID explicitly:

```powershell
$cred = Get-GitHubAppCredential -AppId 3563533 -PrivateKeyPath ~/Downloads/automation-app.2026-11-14.private-key.pem
```

The file must hold exactly one unencrypted RSA private key, in PKCS#1
(`-----BEGIN RSA PRIVATE KEY-----`, what GitHub issues) or PKCS#8
(`-----BEGIN PRIVATE KEY-----`) form; the extension does not matter. The key is
parsed, not just pattern-matched, so a block with a garbled or non-RSA body is
rejected too. A
certificate (`-----BEGIN CERTIFICATE-----`), a passphrase-protected key, an
empty file or anything else is rejected with a message saying why. Errors name
the file, never its contents.

The key is converted to a `SecureString` as soon as it is validated, exactly as
with 1Password, and only the key block is kept. Delete the downloaded file once
the rollout is done.

### Where the credential is stored

By default the credential goes into a GitHub Actions **environment** named
Expand Down Expand Up @@ -339,6 +407,16 @@ $cred = Get-GitHubAppCredential
Get-GitHubRepoConfig -All -Check AppCredential | Set-GitHubRepoConfig -AppCredential $cred -WhatIf
```

To roll the key out to just the repositories that publish releases, from a
downloaded key file:

```powershell
Get-GitHubRepoConfig -All -HasRelease -Check AppCredential |
Set-GitHubRepoConfig -AppCredential (Get-GitHubAppCredential -AppId 3563533 -PrivateKeyPath <file>) -WhatIf
```

Drop `-WhatIf` once the preview looks right.

Remediation creates the environment, enables custom branch policies, pins it to
the default branch, then writes the variable and secret into it — in that order,
since each step depends on the previous one.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,67 @@ function Test-GitHubPagesWorkflow {
return $false
}

function Get-GitHubReleaseEvidence {
<#
.SYNOPSIS
Explain why a repository counts as one that publishes releases.
.DESCRIPTION
The Automation App credential is needed by repositories that cut
releases through the shared release-please workflow. A repository
qualifies when it has a root release-please-config.json, or at least
one published release whose tag looks like a version (v1.2, 1.2.3).

Data or state snapshots stored as GitHub releases - tags such as
db-2026-01-01 or news-state - do not look like versions, so they do
not qualify a repository on their own.

The config file is checked first because it is one cheap call and is
conclusive. Releases are then read a page of 100 at a time, newest
first, stopping at the first versioned one, so a repository whose
version release sits behind many data releases still qualifies.
.PARAMETER Repository
Repository in 'owner/name' form.
.PARAMETER VersionPattern
Regex a release tag must match to count as a version release.
.OUTPUTS
String describing the evidence, or $null when there is none. Throws
when the release list cannot be read, so an API, network or rate-limit
failure is never mistaken for "no releases".
#>
[CmdletBinding()]
[OutputType([string])]
param(
[Parameter(Mandatory = $true)][string]$Repository,

[Parameter(Mandatory = $false)]
[string]$VersionPattern = '^v?\d+\.\d+'
)

$config = Invoke-GitHubApi -Endpoint "repos/$Repository/contents/release-please-config.json" -AllowFailure
if ($null -ne $config) {
return 'release-please-config.json'
}

$pageSize = 100
for ($page = 1; ; $page++) {
$releases = Invoke-GitHubApi -Endpoint "repos/$Repository/releases?per_page=$pageSize&page=$page" -AllowFailure
if ($null -eq $releases) {
throw "Could not list releases for $Repository (page $page). Check the gh token, network access and API rate limit."
}
$releases = @($releases)

$versioned = @($releases | Where-Object {
$null -ne $_ -and -not $_.draft -and [string]$_.tag_name -match $VersionPattern
})
if ($versioned.Count -gt 0) {
return "release $($versioned[0].tag_name)"
}
if ($releases.Count -lt $pageSize) {
return $null
}
}
}

# SIG # Begin signature block
# MIIfEQYJKoZIhvcNAQcCoIIfAjCCHv4CAQExDzANBglghkgBZQMEAgEFADB5Bgor
# BgEEAYI3AgEEoGswaTA0BgorBgEEAYI3AgEeMCYCAwEAAAQQH8w7YFlLCE63JNLG
Expand Down
Loading
Loading