Gate signed provider publication

IlyaasK · IlyaasK · commit f7597f98ff1a · 2026-07-30T10:28:59.000-04:00
Require protected release approval before importing the Registry key, signing the prepared checksum, and publishing retry-safe GitHub Release assets.
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -1,13 +1,27 @@
-name: Release preparation
+name: Release
 
 on:
   push:
     tags:
       - "v*"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Stable version to prepare without publishing
+        required: true
+        default: v0.0.1
+        type: string
 
 permissions:
   contents: read
 
+env:
+  RELEASE_TAG: ${{ inputs.version || github.ref_name }}
+
+defaults:
+  run:
+    shell: bash
+
 concurrency:
   group: release-${{ github.ref }}
   cancel-in-progress: false
@@ -31,8 +45,13 @@ jobs:
         run: |
           test -s LICENSE
 
-          if [[ ! "$GITHUB_REF_NAME" =~ ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then
-            echo "Release tags must use stable semantic version format vMAJOR.MINOR.PATCH." >&2
+          if [[ ! "$RELEASE_TAG" =~ ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then
+            echo "Release versions must use stable semantic version format vMAJOR.MINOR.PATCH." >&2
+            exit 1
+          fi
+
+          if [ "$GITHUB_EVENT_NAME" = "workflow_dispatch" ] && [ "$GITHUB_REF" != "refs/heads/main" ]; then
+            echo "Manual release preflight must run from main." >&2
             exit 1
           fi
 
@@ -47,6 +66,15 @@ jobs:
             exit 1
           fi
 
+      - name: Create local preflight tag
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          if git show-ref --verify --quiet "refs/tags/${RELEASE_TAG}"; then
+            echo "Release version ${RELEASE_TAG} already exists." >&2
+            exit 1
+          fi
+          git tag "$RELEASE_TAG" "$GITHUB_SHA"
+
       - name: Set up Go
         uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6.5.0
         with:
@@ -60,18 +88,18 @@ jobs:
           version: v2.17.0
           args: release --clean --skip=publish,sign
         env:
-          GORELEASER_CURRENT_TAG: ${{ github.ref_name }}
+          GORELEASER_CURRENT_TAG: ${{ env.RELEASE_TAG }}
 
       - name: Verify release artifacts
         run: |
-          version="${GITHUB_REF_NAME#v}"
+          version="${RELEASE_TAG#v}"
           cp terraform-registry-manifest.json "dist/terraform-provider-kernel_${version}_manifest.json"
           bash scripts/check-release-artifacts.sh "$version"
 
       - name: Upload release artifacts
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: release-${{ github.ref_name }}-${{ github.run_id }}
+          name: release-${{ env.RELEASE_TAG }}-${{ github.run_id }}
           path: |
             dist/*.zip
             dist/*_manifest.json
@@ -80,3 +108,166 @@ jobs:
           retention-days: 7
           compression-level: 0
           overwrite: true
+
+  preflight:
+    name: Verify protected release path
+    if: github.event_name == 'workflow_dispatch'
+    needs: prepare
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      actions: read
+      contents: read
+      deployments: read
+    environment:
+      name: release
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Check release protections
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_REVIEWERS: ${{ vars.RELEASE_REVIEWERS }}
+          RELEASE_RULESET_ID: ${{ vars.RELEASE_RULESET_ID }}
+        run: bash scripts/check-release-protections.sh
+
+      - name: Download release artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh run download "$GITHUB_RUN_ID" \
+            --repo "$GITHUB_REPOSITORY" \
+            --name "release-${RELEASE_TAG}-${GITHUB_RUN_ID}" \
+            --dir dist
+
+      - name: Verify downloaded checksums
+        run: |
+          version="${RELEASE_TAG#v}"
+          checksum="dist/terraform-provider-kernel_${version}_SHA256SUMS"
+          test -s "$checksum"
+          (cd dist && sha256sum --check "$(basename "$checksum")")
+
+      - name: Sign and verify checksums
+        env:
+          EXPECTED_GPG_FINGERPRINT: ${{ vars.GPG_FINGERPRINT }}
+          GPG_PRIVATE_KEY: ${{ secrets.GPG_PRIVATE_KEY }}
+          PASSPHRASE: ${{ secrets.PASSPHRASE }}
+        run: bash scripts/sign-release-checksum.sh "${RELEASE_TAG#v}"
+
+  publish:
+    name: Sign and publish release
+    if: github.event_name == 'push'
+    needs: prepare
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      actions: read
+      contents: write
+      deployments: read
+    environment:
+      name: release
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Check release protections
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_REVIEWERS: ${{ vars.RELEASE_REVIEWERS }}
+          RELEASE_RULESET_ID: ${{ vars.RELEASE_RULESET_ID }}
+        run: bash scripts/check-release-protections.sh
+
+      - name: Download release artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh run download "$GITHUB_RUN_ID" \
+            --repo "$GITHUB_REPOSITORY" \
+            --name "release-${GITHUB_REF_NAME}-${GITHUB_RUN_ID}" \
+            --dir dist
+
+      - name: Check publication preconditions
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          tag_commit="$(gh api "repos/${GITHUB_REPOSITORY}/commits/${GITHUB_REF_NAME}" --jq .sha)"
+          if [ "$tag_commit" != "$GITHUB_SHA" ]; then
+            echo "The release tag no longer points to the workflow commit." >&2
+            exit 1
+          fi
+
+          release="$(
+            gh api --paginate --slurp "repos/${GITHUB_REPOSITORY}/releases?per_page=100" |
+              jq -c --arg tag "$GITHUB_REF_NAME" '[.[][] | select(.tag_name == $tag)][0] // empty'
+          )"
+          if [ -n "$release" ]; then
+            if [ "$(jq -r .draft <<<"$release")" = "true" ]; then
+              echo "An existing draft release must be inspected and removed before retrying ${GITHUB_REF_NAME}." >&2
+            else
+              echo "A published release already exists for ${GITHUB_REF_NAME}." >&2
+            fi
+            exit 1
+          fi
+
+          version="${GITHUB_REF_NAME#v}"
+          checksum="dist/terraform-provider-kernel_${version}_SHA256SUMS"
+          test -s "$checksum"
+          (cd dist && sha256sum --check "$(basename "$checksum")")
+
+      - name: Sign and verify checksums
+        env:
+          EXPECTED_GPG_FINGERPRINT: ${{ vars.GPG_FINGERPRINT }}
+          GPG_PRIVATE_KEY: ${{ secrets.GPG_PRIVATE_KEY }}
+          PASSPHRASE: ${{ secrets.PASSPHRASE }}
+        run: bash scripts/sign-release-checksum.sh "${GITHUB_REF_NAME#v}"
+
+      - name: Create draft release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          first_release_url="https://github.com/${GITHUB_REPOSITORY}/blob/${GITHUB_SHA}/docs/first-release.md"
+          manifest="dist/terraform-provider-kernel_${version}_manifest.json"
+          checksum="dist/terraform-provider-kernel_${version}_SHA256SUMS"
+          signature="${checksum}.sig"
+          notes=()
+          if [ "$GITHUB_REF_NAME" = "v0.0.1" ]; then
+            notes=(--notes "First-release guidance: [supported surface and imports](${first_release_url}).")
+          fi
+
+          tag_commit="$(gh api "repos/${GITHUB_REPOSITORY}/commits/${GITHUB_REF_NAME}" --jq .sha)"
+          if [ "$tag_commit" != "$GITHUB_SHA" ]; then
+            echo "The release tag no longer points to the workflow commit." >&2
+            exit 1
+          fi
+
+          gh release create "$GITHUB_REF_NAME" \
+            dist/terraform-provider-kernel_"${version}"_*.zip \
+            "$manifest" \
+            "$checksum" \
+            "$signature" \
+            --repo "$GITHUB_REPOSITORY" \
+            --verify-tag \
+            --draft \
+            --generate-notes \
+            "${notes[@]}" \
+            --title "$GITHUB_REF_NAME"
+
+      - name: Publish release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          tag_commit="$(gh api "repos/${GITHUB_REPOSITORY}/commits/${GITHUB_REF_NAME}" --jq .sha)"
+          if [ "$tag_commit" != "$GITHUB_SHA" ]; then
+            echo "The release tag no longer points to the workflow commit." >&2
+            exit 1
+          fi
+
+          gh release edit "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" --draft=false
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -1,6 +1,6 @@
 # Kernel Terraform Provider Architecture
 
-This document records the durable-only architecture, the implemented v0 baseline, and the target scope for the first public v1 of the Kernel Terraform provider.
+This document records the durable-only architecture, the initial public v0.0.1 surface, and the target scope for a future v1 of the Kernel Terraform provider.
 
 ## First Principles
 
@@ -42,7 +42,7 @@ Import:
 
 ## v1 Target Scope
 
-The first public v1 should make durable Kernel configuration production-ready without turning Terraform into a runtime control plane. Core items are release-blocking unless the release notes explicitly defer them with an upstream API or SDK blocker.
+A future v1 should broaden production-ready durable Kernel configuration without turning Terraform into a runtime control plane.
 
 Resources require stable identity, refresh, delete, import, and, where applicable, project-scoping and sensitive-state semantics. Data sources require stable identity, deterministic exact lookup, and, where applicable, masked sensitive metadata, pagination, and project scoping. Tooling experiments require deterministic regeneration and must preserve the handwritten lifecycle boundary.
 
@@ -268,4 +268,4 @@ Release checklist:
 - Runtime operations are absent from Terraform resources.
 - Import behavior is documented.
 - API and SDK blockers are either resolved or explicitly deferred.
-- Release process, signing, licensing, and versioning are complete before the first public v1 publication.
+- Release process, signing, licensing, and versioning are complete before the first public v0.0.1 publication.
diff --git a/docs/first-release.md b/docs/first-release.md
@@ -1,6 +1,6 @@
 # First Public Release
 
-The first published Kernel Terraform provider version will be v1. This
+The first published Kernel Terraform provider version will be v0.0.1. This
 repository has no earlier published tags, so this release has no provider
 upgrade or state migration path.
 
diff --git a/docs/release.md b/docs/release.md
@@ -4,7 +4,7 @@ Use this checklist before publishing a Kernel Terraform provider version.
 
 ## Release Preconditions
 
-- The repository has no published provider tags. Present v1 as the first public release, not as an upgrade or migration from v0.
+- The repository has no published provider tags. Present v0.0.1 as the first public release, not as an upgrade or migration from an earlier provider version.
 - Review the [first public release guide](first-release.md) and include its supported-surface and import guidance in the release notes.
 - Work from a clean `main` checkout after the PR stack is merged.
 - Run `bash scripts/check-docs.sh`.
@@ -28,12 +28,41 @@ Use this checklist before publishing a Kernel Terraform provider version.
 - Verify unscoped API calls send no `X-Kernel-Project-Id` header; it is sent only when a resource-level `project_id` or the provider default resolves a project.
 - Confirm `terraform-registry-manifest.json` contains protocol `["6.0"]` for Terraform Plugin Framework.
 - Confirm `LICENSE` contains the approved Apache License 2.0 text.
+- Confirm immutable GitHub Releases are enabled for the repository. The
+  publication job intentionally has no repository-administration permission to
+  inspect or change this setting.
 - Confirm GitHub private vulnerability reporting or a public security contact is configured and reflected in `SECURITY.md`.
-- Confirm there is no branch named like the release tag, for example `v1.0.0`.
+- Create a protected GitHub environment named `release`, require approval from
+  the designated release owners, prevent self-review, and disable administrator
+  bypass. Add exactly two deployment policies: the `main` branch for manual
+  preflight and tags matching `v*` for publication. Store
+  `GPG_PRIVATE_KEY` and `PASSPHRASE` as environment secrets, not repository
+  secrets. Set the environment variable `GPG_FINGERPRINT` to the fingerprint
+  registered with the Terraform Registry. Set `RELEASE_REVIEWERS` to the exact
+  comma-separated reviewer identities in `Type:name` form, such as
+  `User:octocat,Team:release-owners`. GitHub's environment API does not report
+  whether administrator bypass is disabled, so verify that setting when
+  approving a release.
+- Add a repository ruleset that restricts creation, update, and deletion of
+  `v*` tags to the designated release owners. Set the `release` environment
+  variable `RELEASE_RULESET_ID` to that active ruleset's numeric ID. The workflow
+  verifies the live environment reviewer identities, deployment policies, and
+  ruleset controls before
+  touching signing configuration. Before setting the ID, inspect the ruleset's
+  bypass list and require explicit release-owner teams or GitHub Apps; do not
+  allow repository roles or organization administrators to bypass it. GitHub
+  omits bypass actors from ruleset API responses unless the caller has ruleset
+  write access, so the least-privilege workflow cannot verify their identities
+  at runtime.
+- GitHub repository writers can create Releases through the API; GitHub does not
+  provide a separate release-publisher role. Treat every account with repository
+  write access as release-authorized, keep that group minimal, and use the
+  protected environment to restrict access to the signing key.
+- Confirm there is no branch named like the release tag, for example `v0.0.1`.
 
 ## Registry Release Assets
 
-Terraform Registry provider releases are GitHub Releases with semver tags prefixed by `v`, such as `v1.0.0`.
+Terraform Registry provider releases are GitHub Releases with semver tags prefixed by `v`, such as `v0.0.1`.
 
 Each release must include:
 
@@ -61,13 +90,34 @@ Do not replace or mutate assets for a published version. If an asset, checksum,
   platforms, checksums, manifest inclusion, and checksum signing.
 - Normal CI validates the GoReleaser configuration and registry manifest without
   building the complete platform matrix.
-- `.github/workflows/release.yml` prepares unsigned, unpublished assets for
-  stable `vMAJOR.MINOR.PATCH` tags after confirming the repository is public
-  and the tag commit is reachable from `main`. It pins GoReleaser to the pushed
-  tag, verifies the release contract, and retains the assets for seven days.
-- Real releases sign the checksum file once with the GPG key selected by
-  `GPG_FINGERPRINT`. The detached signature is named by appending `.sig` to the
-  checksum filename. Publication remains a separate release step.
+- `.github/workflows/release.yml` runs for `v*` tags. Its preparation job has
+  read-only repository access and accepts only stable `vMAJOR.MINOR.PATCH`
+  versions. It requires the Apache 2.0 license, public repository visibility,
+  and a commit reachable from `main`, then builds and verifies the unsigned
+  assets. The workflow artifact is retained for seven days. Only the protected
+  publication job receives `contents: write`.
+- Before creating a tag, run the workflow manually with the intended version.
+  Manual runs create an unpushed tag only inside the ephemeral runner, build
+  the same unsigned assets, and enter the protected `release` environment to
+  verify its reviewer, tag policy, ruleset, checksum, and GPG signing
+  configuration. They never create a remote tag or GitHub Release.
+- For the manual preflight, inspect the prepared artifact before approving the
+  protected `release` job. After approval, the job verifies the release
+  protections, checksums, and GPG signing configuration without publishing.
+- For a tag-triggered release, confirm the acceptance matrix passed and the tag
+  ruleset's bypass list still contains only designated release owners before
+  approving the protected `release` job. After approval, the job revalidates the
+  tag and checksums, requires the imported key to match `GPG_FINGERPRINT`, signs
+  the checksum file, and publishes the GitHub Release.
+- Failed-job reruns reuse the prepared artifact from the same workflow run. A
+  full rerun replaces that run's artifact and requires a fresh environment
+  approval. If publication fails or is interrupted, it may leave a draft. Any
+  existing draft stops retries until a release owner inspects and removes it
+  manually. An existing published release always stops the workflow.
+- For `v0.0.1`, GitHub includes the tagged
+  [first public release guide](first-release.md) with the generated release
+  notes. Later versions use generated release notes without first-release
+  guidance.
 
 ## Registry Setup
 
@@ -97,3 +147,4 @@ References:
 - HashiCorp Terraform provider publishing: https://developer.hashicorp.com/terraform/registry/providers/publishing
 - HashiCorp provider registry protocol: https://developer.hashicorp.com/terraform/internals/provider-registry-protocol
 - GoReleaser checksum signing: https://goreleaser.com/customization/sign/
+- GitHub deployment environments: https://docs.github.com/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments
diff --git a/scripts/check-release-protections.sh b/scripts/check-release-protections.sh
diff --git a/scripts/sign-release-checksum.sh b/scripts/sign-release-checksum.sh
