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
15 changes: 15 additions & 0 deletions docs/REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,7 @@ the template excludes, add the line `!<entry>` to your list.
| `CLAUDE.md` | `@AGENTS.md` shim |
| `docs/REFERENCE.md` | This reference |
| `scripts/workflow-caller-pin-contract.test.sh` (*tenant*) | Runs in each tenant's required CI and rejects malformed, divergent, or rolled-back reusable-workflow pins, and a version comment that does not name the tag of the pinned commit |
| `scripts/fixtures/own-publisher.yaml` (*tenant*) | Direct-action compatibility input used by the portable caller and approval checks; sync it with those checks |
| `scripts/publish-pin-approved.sh`, `scripts/publish-pin-approved.test.sh` (*tenant*) | The check a tenant's required CI runs to refuse a changed publisher identity until Platform approves it for that tenant. Legacy revisions use the existing approved set; maintained publishers require an exact canonical approval. The default `ci.yaml` runs the `publish-pin-approved` job and includes it in `ci-required-checks`; this unregistered template runs its tests only. Older tenants that own `ci.yaml` add the job themselves |
| `zizmor.yml` | GitHub Actions pinning policy enforced by the security scan |

Expand Down Expand Up @@ -230,6 +231,20 @@ or authorize a tenant's caller pin.
> name — `publish-app` pins the built image digest into the container with that
> name (`app-name: ${{ github.event.repository.name }}` in `cd.yaml`).

## Staging a publisher migration

Existing tenants keep their own `deploy/` tree and CI workflow. Land the updated portable caller
check, approval check, their tests and `scripts/fixtures/own-publisher.yaml` while keeping the
current publisher unchanged. The required approval job executes the checker from its base revision,
so the guard update must merge in the consumer before a later PR changes its publishing job.

After that consumer’s base contains the updated checks, switch its publisher in a separate PR.
Keep support for both `deploy/deployment.yaml` and `deploy/base/deployment.yaml`: template sync does
not move tenant-owned manifests. The prepared direct-action contract accepts either fixed path or
the exact file-selection expression in the compatibility fixture. The existing reusable-workflow
caller still requires its original Platform approval; the new direct caller retains immutable pins,
a minimal signing job, credential-free checkout and an unskippable publisher.

## Validate locally

Native required CI also inspects workflow startup failures at the pull-request
Expand Down
38 changes: 38 additions & 0 deletions scripts/fixtures/own-publisher.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
name: 🚀 CD

on:
push:
tags:
- "v*"

permissions: {}

jobs:
publish:
name: Publish
# The upstream template has no application to publish; its ID survives renames.
if: github.repository_id != '1253884448'
runs-on: ubuntu-latest
timeout-minutes: 60
concurrency:
group: publish-${{ github.repository }}
cancel-in-progress: false
permissions:
contents: read
packages: write
id-token: write
steps:
- name: 🔒 Harden runner
uses: step-security/harden-runner@1d88384fd173af6ecb012dfd0264a306b711241a # v2.22.4
with:
egress-policy: audit
- name: 📥 Checkout
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: 📦 Publish signed application
id: publish
uses: devantler-tech/.github/actions/publish-app@3cab796adef97dcde0c55724866a0b19397aba39 # v21.6.2
with:
app-name: ${{ github.event.repository.name }}
app-manifest: ${{ hashFiles('deploy/base/deployment.yaml') != '' && 'base/deployment.yaml' || 'deployment.yaml' }}
60 changes: 60 additions & 0 deletions scripts/publish-pin-approved.sh
Original file line number Diff line number Diff line change
Expand Up @@ -32,8 +32,61 @@ fail() {
[ "$#" -eq 2 ] || fail 'usage: publish-pin-approved.sh <base-cd.yaml> <head-cd.yaml>'

# One complete publisher identity, not just a SHA that could belong to another repository.
publish_manifest_choice=$(cat <<'EXPRESSION'
${{ hashFiles('deploy/base/deployment.yaml') != '' && 'base/deployment.yaml' || 'deployment.yaml' }}
EXPRESSION
)
export publish_manifest_choice

publish_identity() {
[ -f "$1" ] || fail "no cd.yaml at $1"
yq eval-all -e '[.] | length == 1' "$1" >/dev/null ||
fail "$1 must contain exactly one publisher document"
if yq eval -e '.jobs.publish | has("steps")' "$1" >/dev/null 2>&1; then
# A direct action signs as this repository, independently of the action's
# revision. Retain a minimal, tag-only, credential-free execution frame;
# the required caller-pin check binds its SHA to the catalogue release.
# Workflow-level env and defaults can also change the action's execution.
# shellcheck disable=SC2016
yq eval -e '
(keys - ["name", "on", "permissions", "jobs"] | length) == 0
and (.permissions | length) == 0
and (.["on"] | keys | join(",")) == "push"
and (.["on"].push | keys | join(",")) == "tags"
and (.["on"].push.tags | length) == 1
and .["on"].push.tags[0] == "v*"
and (.jobs | keys | join(",")) == "publish"
and (.jobs.publish | keys | sort | join(",")) == "concurrency,if,name,permissions,runs-on,steps,timeout-minutes"
and .jobs.publish.if == "github.repository_id != '\''1253884448'\''"
and .jobs.publish."runs-on" == "ubuntu-latest"
and .jobs.publish."timeout-minutes" == 60
and .jobs.publish.concurrency.group == "publish-${{ github.repository }}"
and .jobs.publish.concurrency."cancel-in-progress" == false
and (.jobs.publish.permissions | length) == 3
and .jobs.publish.permissions.contents == "read"
and .jobs.publish.permissions.packages == "write"
and .jobs.publish.permissions."id-token" == "write"
and (.jobs.publish.steps | length) == 3
and (.jobs.publish.steps[0] | keys | sort | join(",")) == "name,uses,with"
and (.jobs.publish.steps[0].uses | test("^step-security/harden-runner@[0-9a-f]{40}$"))
and (.jobs.publish.steps[0].with | length) == 1
and .jobs.publish.steps[0].with."egress-policy" == "audit"
and (.jobs.publish.steps[1] | keys | sort | join(",")) == "name,uses,with"
and (.jobs.publish.steps[1].uses | test("^actions/checkout@[0-9a-f]{40}$"))
and (.jobs.publish.steps[1].with | length) == 1
and .jobs.publish.steps[1].with."persist-credentials" == false
and (.jobs.publish.steps[2] | keys | sort | join(",")) == "id,name,uses,with"
and .jobs.publish.steps[2].id == "publish"
and (.jobs.publish.steps[2].uses | test("^devantler-tech/[.]github/actions/publish-app@[0-9a-f]{40}$"))
and (.jobs.publish.steps[2].with | keys | sort | join(",")) == "app-manifest,app-name"
and .jobs.publish.steps[2].with."app-name" == "${{ github.event.repository.name }}"
and (.jobs.publish.steps[2].with."app-manifest" == "base/deployment.yaml"
or .jobs.publish.steps[2].with."app-manifest" == "deployment.yaml"
or .jobs.publish.steps[2].with."app-manifest" == strenv(publish_manifest_choice))
' "$1" >/dev/null || fail "$1 does not retain the minimal own-release signing contract"
yq eval -r '.jobs.publish.steps[2].uses' "$1"
return
fi
uses=$(yq eval -r '.jobs.publish.uses // ""' "$1") ||
fail "could not read the publish-app.yaml pin from $1"
# Validate the whole reference first: a bare SHA, or another workflow pinned by SHA, is not a
Expand All @@ -51,6 +104,13 @@ base_identity=$(publish_identity "$1")
head_identity=$(publish_identity "$2")
head_pin=${head_identity##*@}

case "$head_identity" in
devantler-tech/.github/actions/publish-app@*)
printf 'Publisher signs as the own release workflow; shared-workflow revision approval does not apply.\n'
exit 0
;;
esac

if [ "$base_identity" = "$head_identity" ]; then
printf 'publish-app.yaml pin unchanged at %s; nothing to check.\n' "$head_pin"
exit 0
Expand Down
51 changes: 51 additions & 0 deletions scripts/publish-pin-approved.test.sh
Original file line number Diff line number Diff line change
Expand Up @@ -164,6 +164,57 @@ expect 'canonical columns are bound by header, not position' 0 'is approved' "$w
rm "$work/canonical.tsv"
expect 'an unreadable canonical set fails closed' 1 'could not read' "$work/ok.tsv" "$candidate" example-tenant .github

# Exercise the direct caller contract, including the old-to-own identity transition.
# Shared-publisher approval records remain mandatory for every legacy case above.
cp "$script_dir/fixtures/own-publisher.yaml" "$work/own.yaml"
cd_file base.yaml "$main_pin" .github
status=0
output=$(PUBLISH_PIN_CONSUMER=example-tenant PUBLISH_PIN_APPROVED_SET="$work/missing.tsv" \
sh "$subject" "$work/base.yaml" "$work/own.yaml" 2>&1) || status=$?
if [ "$status" -eq 0 ] && printf '%s\n' "$output" | grep -Fq 'own release workflow'; then
pass=$((pass + 1))
else
printf 'FAIL: direct caller transition (exit %s)\n%s\n' "$status" "$output" >&2
failures=$((failures + 1))
fi
for manifest in deployment.yaml base/deployment.yaml; do
MANIFEST=$manifest yq eval '.jobs.publish.steps[2].with."app-manifest" = strenv(MANIFEST)' \
"$work/own.yaml" >"$work/fixed-path.yaml"
if sh "$subject" "$work/base.yaml" "$work/fixed-path.yaml" >"$work/result" 2>&1; then
pass=$((pass + 1))
else
printf 'FAIL: supported manifest path refused: %s\n' "$manifest" >&2
cat "$work/result" >&2
failures=$((failures + 1))
fi
done
for mutation in \
'.env.BASH_ENV = "publisher-hook.sh"' \
'.defaults.run.shell = "bash -e {0}"' \
'.jobs.publish.steps[2].uses = "other-owner/repo/action@aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"' \
'.jobs.publish.steps[2].uses = "devantler-tech/.github/actions/publish-app@main"' \
'.jobs.publish.steps[1].with."persist-credentials" = true' \
'.jobs.publish.steps[2].if = "false"' \
'.jobs.publish.steps[2].with."app-manifest" = "other/deployment.yaml"' \
'.jobs.publish.permissions.issues = "write"' \
'.jobs.publish.steps += [.jobs.publish.steps[2]]' \
'.jobs.shadow = .jobs.publish' \
'.jobs.publish.uses = "devantler-tech/.github/.github/workflows/publish-app.yaml@aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"'; do
yq eval "$mutation" "$work/own.yaml" >"$work/unsafe.yaml"
if sh "$subject" "$work/base.yaml" "$work/unsafe.yaml" >"$work/result" 2>&1; then
printf 'FAIL: unsafe own caller accepted: %s\n' "$mutation" >&2
failures=$((failures + 1))
else
if grep -Fq 'minimal own-release signing contract' "$work/result"; then
pass=$((pass + 1))
else
printf 'FAIL: own caller refused for the wrong reason: %s\n' "$mutation" >&2
cat "$work/result" >&2
failures=$((failures + 1))
fi
fi
done

printf 'publish-pin-approved: %s passed, %s failed\n' "$pass" "$failures"
completed=1
[ "$failures" -eq 0 ]
10 changes: 10 additions & 0 deletions scripts/workflow-caller-contract.test.sh
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,8 @@ tenant_ignored() {

[ -f "$portable_contract" ] ||
fail 'the portable workflow-caller pin contract is missing'
[ -f "$repo_root/scripts/fixtures/own-publisher.yaml" ] ||
fail 'the direct publisher compatibility fixture is missing'
grep -Fqx 'scripts/workflow-caller-contract.test.sh' "$template_sync_ignore" ||
fail 'the scaffold-only workflow-caller contract must stay tenant-ignored'
if grep -Fqx 'scripts/workflow-caller-pin-contract.test.sh' "$template_sync_ignore"; then
Expand Down Expand Up @@ -77,6 +79,9 @@ validate_contract() {
reference_file=$5
ignore_file=$6
dependabot_file=$7
if tenant_ignored "$ignore_file" scripts/fixtures/own-publisher.yaml; then
fail 'the portable caller fixture must reach tenants through template sync'
fi

yq eval -e '.jobs.publish.uses | test("^devantler-tech/[.]github/[.]github/workflows/publish-app[.]yaml@[0-9a-f]{40}$")' \
"$cd_file" >/dev/null ||
Expand Down Expand Up @@ -280,6 +285,11 @@ run_mutation 'template-sync ignore-entry merge disabled' template-sync \
'.jobs."template-sync".with."merge-template-ignore-entries" = false'
run_mutation 'template-sync ignore-entry merge removed' template-sync \
'del(.jobs."template-sync".with."merge-template-ignore-entries")'
# The sed append address is literal; it must not expand as a shell variable.
# shellcheck disable=SC2016
run_mutation 'portable caller fixture excluded from template sync' ignore \
'$a\
scripts/fixtures/own-publisher.yaml'
run_mutation 'required scaffold invocation removed' validation \
'del(.jobs."validate-scaffold".steps[] | select(.run == "sh scripts/workflow-caller-contract.test.sh"))'
run_mutation 'reference ownership table marker removed' reference \
Expand Down
Loading
Loading