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
28 changes: 26 additions & 2 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 All @@ -103,14 +104,14 @@ never re-synced, so a tenant still carrying these from an older sync can delete
| `stacks/` | The Go and .NET stack sources the scaffold copies once; the copies are then yours |
| `scripts/scaffold.sh` (+ its test) | One-shot stack and tenancy scaffold; its test scaffolds every combination and checks what each leaves |
| `.github/workflows/validate-stacks.yaml` | Scaffolds each stack as a tenant, then builds, tests, lints, renders `deploy/`, builds the image and checks it serves `GET /` under the restricted container settings |
| `.github/workflows/validate-scaffold.yaml` | Renders `deploy/`, schema-validates every resource, applies the live Platform/shared Kyverno policies, and exercises a pinned Kubernetes API. The live checks prove the template publishes through the pinned signing workflow; Platform still wires the private GHCR pull credential to the tenant identity and cosign-verifying OCI source; and Flux consumes that source while impersonating and targeting the managed `restricted` namespace for both KRO and manual registrations. They then prove the Deployment passes Pod Security `restricted`, the tenant identity can reconcile every rendered kind, and cluster-scoped or interactive privileges remain denied. It gates template PRs, re-validates `main` after every merge, and rechecks upstream drift every day at 06:17 UTC (or on manual dispatch), keeping one tracking issue open while that scheduled check fails on `main`; structural mutation tests keep every layer fail-closed. The workflow no-ops in tenants and is scaffold-time only |
| `.github/workflows/validate-scaffold.yaml` | Renders `deploy/`, schema-validates every resource, applies the live Platform/shared Kyverno policies, and exercises a pinned Kubernetes API. The live checks prove the template publishes through the pinned signing workflow; Platform pulls the public tenant artifact without a credential through a cosign-verifying OCI source; and Flux consumes that source while impersonating and targeting the managed `restricted` namespace for both KRO and manual registrations. They then prove the Deployment passes Pod Security `restricted`, the tenant identity can reconcile every rendered kind, and cluster-scoped or interactive privileges remain denied. It gates template PRs, re-validates `main` after every merge, and rechecks upstream drift every day at 06:17 UTC (or on manual dispatch), keeping one tracking issue open while that scheduled check fails on `main`; structural mutation tests keep every layer fail-closed. The workflow no-ops in tenants and is scaffold-time only |
| `scripts/rename-placeholders.sh` (+ its test) | One-shot rename of the placeholder app to your tenant name |
| `scripts/agent-instructions.test.sh` | Fails closed if the one-time agent scaffold loses its ownership, dependency-bot, external-code, exact-head review, pinned-merge, or user-path evaluation boundaries, or regains a retired rule |
| `scripts/workflow-caller-contract.test.sh` | Keeps the portable caller-pin contract wired into tenant CI while validating template-only publisher, release, ownership, and scaffold invariants |
| `scripts/tenant-ci-contract.test.sh` | Keeps default tenant PR CI least-privilege and fail-closed over both the image build and rendered manifests |
| `scripts/pod-security-admission*.test.sh` | Proves the rendered Deployment is accepted at Pod Security `restricted` while unsafe mutations are denied, and pins that live gate against structural bypasses |
| `scripts/tenant-rbac*.test.sh` | Proves the Platform tenant reconciliation identity can manage every rendered scaffold resource while cluster-scoped and interactive privileges stay denied |
| `scripts/platform-tenant-envelope*.test.sh` | Binds the template's signed publisher and those workload-level models to Platform's live KRO and manual tenant registrations: private GHCR pull identity, cosign-verifying OCI source, managed Pod Security namespace, `tenant-edit` ServiceAccount binding, Flux source/impersonation/target namespace, and the exact OpenBao policy and Kubernetes-auth role that let the renamed tenant read and seed only its own app secrets |
| `scripts/platform-tenant-envelope*.test.sh` | Binds the template's signed publisher and those workload-level models to Platform's live KRO and manual tenant registrations: credential-free GHCR pull, cosign-verifying OCI source, managed Pod Security namespace, `tenant-edit` ServiceAccount binding, Flux source/impersonation/target namespace, and the exact OpenBao policy and Kubernetes-auth role that let the renamed tenant read and seed only its own app secrets |
| `scripts/platform-network-floor*.test.sh` | Binds Platform's generated default-deny, DNS, and standard NetworkPolicy floor to the scaffold's required Gateway, namespace, CNPG, Kubernetes API, and DNS paths, reporting a check that cannot read its input separately from a policy verdict |
| `scripts/platform-vpa-floor*.test.sh` | Uses Kyverno to evaluate Platform's Deployment GeneratingPolicy and keeps the scaffold's initial CPU request at or above the generated VPA floor, with mutation coverage |

Expand Down Expand Up @@ -226,10 +227,33 @@ The Platform approval and verification policy must be deployed before a live
tenant adopts that caller. This compatibility check does not activate publishing
or authorize a tenant's caller pin.

The envelope check also accepts the minimal direct `actions/publish-app` caller
frame validated by the portable approval check. It instantiates the generic
Tenant's exact own-release rule with a fixed sample repository and release tag,
then compares that producer with the decoded rule. A shared-only default or an
explicit shared-publisher revision cannot authorize this producer. Execution
environment overrides and branch publication remain refused. This offline
compatibility check neither switches the starter's publisher nor proves that a
real release was signed, admitted or reconciled.

> **Convention:** the Deployment's container `name` MUST equal the repository
> 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 ]
Loading
Loading