Skopeo Container Image Promotion & Provenance Gate

id: skopeo-container-image-promotion-and-provenance-gate
namespace: company.platform

inputs:
  - id: source_image
    type: STRING
    displayName: Staging Source Image Reference
    description: Remote container image reference in the staging or development
      registry (e.g. docker.io/library/alpine:3.20.0 or
      staging.registry.internal/app:v1.2.0).
    defaults: "docker.io/library/alpine:3.20.0"

  - id: destination_image
    type: STRING
    displayName: Production Destination Image Reference
    description: Target container image reference in the production registry.
    defaults: "localhost:5000/production/alpine:3.20.0"

  - id: require_provenance_labels
    type: BOOL
    displayName: Require Git SHA Provenance Labels
    description: When true, rejects promotion if the image lacks standard OCI build
      provenance labels (org.opencontainers.image.revision or vcs-ref).
    defaults: false

  - id: dry_run
    type: BOOL
    displayName: Dry Run (Audit Only)
    description: When true, inspects manifests and evaluates immutability policies
      without executing the skopeo copy promotion step.
    defaults: true

  - id: enforce_gate
    type: BOOL
    displayName: Enforce Gate on Policy Failure
    description: Automatically fails the execution if tag hijack or provenance
      violations are detected, halting automated CD deployment pipelines.
    defaults: true

  - id: notify_slack
    type: BOOL
    displayName: Send Slack Alert
    description: Dispatches high-priority security notifications to Slack on tag
      hijack or policy rejection. Requires the SLACK_WEBHOOK_URL secret.
    defaults: false

triggers:
  - id: on_staging_image_push
    type: io.kestra.plugin.core.trigger.Webhook
    description: Webhook trigger invoked by container build systems (e.g. GitHub
      Actions, GitLab CI) upon completing staging image publication.
    key: "{{ secret('CONTAINER_PROMOTION_WEBHOOK_KEY') }}"
    disabled: true

  - id: scheduled_registry_promotion_sweep
    type: io.kestra.plugin.core.trigger.Schedule
    description: Scheduled batch sweep for pending release candidates.
    cron: "0 2 * * 1-5"
    disabled: true

tasks:
  - id: inspect_staging_manifest
    type: io.kestra.plugin.skopeo.cli.SkopeoCLI
    description: Inspects raw OCI manifest headers, layer counts, and image labels
      without pulling heavy layer tarballs.
    commands:
      - "skopeo inspect --raw {{ secret('STAGING_REGISTRY_USERNAME') != '' ?
        ('--creds ' ~ secret('STAGING_REGISTRY_USERNAME') ~ ':' ~
        secret('STAGING_REGISTRY_PASSWORD')) : '--no-creds' }} docker://{{
        inputs.source_image }} > staging_raw.json"
      - "skopeo inspect {{ secret('STAGING_REGISTRY_USERNAME') != '' ? ('--creds
        ' ~ secret('STAGING_REGISTRY_USERNAME') ~ ':' ~
        secret('STAGING_REGISTRY_PASSWORD')) : '--no-creds' }} docker://{{
        inputs.source_image }} > staging_inspect.json"
    outputFiles:
      - staging_raw.json
      - staging_inspect.json

  - id: inspect_production_target
    type: io.kestra.plugin.skopeo.cli.SkopeoCLI
    description: Queries the target production repository to verify tag presence and
      capture existing cryptographic digests.
    allowFailure: true
    commands:
      - "skopeo inspect {{ secret('PRODUCTION_REGISTRY_USERNAME') != '' ?
        ('--creds ' ~ secret('PRODUCTION_REGISTRY_USERNAME') ~ ':' ~
        secret('PRODUCTION_REGISTRY_PASSWORD')) : '--no-creds' }} docker://{{
        inputs.destination_image }} > prod_inspect.json || echo
        '{\"tag_exists\": false}' > prod_inspect.json"
    outputFiles:
      - prod_inspect.json

  - id: evaluate_promotion_policies
    type: io.kestra.plugin.scripts.python.Script
    description: Evaluates tag immutability, cryptographic digest parity, OCI
      provenance labels, and multi-architecture metadata.
    containerImage: python:3.11-slim
    beforeCommands:
      - pip install kestra
    inputFiles:
      staging_inspect.json: "{{
        outputs.inspect_staging_manifest.outputFiles['staging_inspect.json'] }}"
      prod_inspect.json: "{{
        outputs.inspect_production_target.outputFiles['prod_inspect.json'] }}"
    env:
      REQUIRE_PROVENANCE: "{{ inputs.require_provenance_labels }}"
      SOURCE_IMAGE: "{{ inputs.source_image }}"
      DEST_IMAGE: "{{ inputs.destination_image }}"
      DRY_RUN: "{{ inputs.dry_run }}"
    script: |
      import os
      import json
      from kestra import Kestra

      with open("staging_inspect.json") as f:
          staging = json.load(f)

      try:
          with open("prod_inspect.json") as f:
              prod = json.load(f)
      except Exception:
          prod = {"tag_exists": False}

      digest = staging.get("Digest", "")
      labels = staging.get("Labels") or {}
      created = staging.get("Created", "")
      arch = staging.get("Architecture", "")
      os_name = staging.get("Os", "")
      layers = staging.get("Layers", [])
      layers_count = len(layers)

      git_sha = labels.get("org.opencontainers.image.revision", labels.get("vcs-ref", ""))
      source_url = labels.get("org.opencontainers.image.source", labels.get("url", ""))

      prod_digest = prod.get("Digest")
      tag_already_exists = prod_digest is not None

      require_provenance = os.environ.get("REQUIRE_PROVENANCE", "false").lower() == "true"
      dry_run = os.environ.get("DRY_RUN", "true").lower() == "true"

      verdict = "APPROVED_PROMOTION"
      details = []

      if tag_already_exists and prod_digest != digest:
          verdict = "REJECTED_TAG_HIJACK"
          details.append(f"CRITICAL IMMUTABILITY VIOLATION: Tag exists in destination with DIFFERENT digest ({prod_digest[:19]}... vs staging {digest[:19]}...). Overwrite blocked.")
      elif require_provenance and not git_sha:
          verdict = "REJECTED_MISSING_PROVENANCE"
          details.append("Security Policy Failure: Image lacks required 'org.opencontainers.image.revision' (Git commit SHA) build provenance label.")
      elif layers_count == 0:
          verdict = "REJECTED_EMPTY_MANIFEST"
          details.append("Manifest Error: Image reports 0 filesystem layers.")
      else:
          if tag_already_exists and prod_digest == digest:
              details.append(f"Idempotent verification: Destination already contains identical image digest ({digest[:19]}...).")
          else:
              details.append(f"Image passed all security policies: Git SHA '{git_sha or 'unspecified'}', arch '{os_name}/{arch}', digest '{digest[:19]}...'.")

      if dry_run and verdict == "APPROVED_PROMOTION":
          details.append("DRY RUN: Copy step bypassed.")

      print(f"Promotion Gate Verdict: {verdict} - {'; '.join(details)}")

      Kestra.outputs({
          "verdict": verdict,
          "staging_digest": digest,
          "prod_digest": prod_digest or "NOT_FOUND",
          "git_sha": git_sha or "NONE",
          "architecture": f"{os_name}/{arch}",
          "layer_count": layers_count,
          "tag_already_exists": tag_already_exists,
          "is_dry_run": dry_run,
          "summary": " ".join(details)
      })

  - id: route_promotion_decision
    type: io.kestra.plugin.core.flow.Switch
    description: Routes artifact promotion execution, security isolation, or
      provenance hold based on policy verdict.
    value: "{{ outputs.evaluate_promotion_policies.vars.verdict }}"
    cases:
      APPROVED_PROMOTION:
        - id: check_execute_copy
          type: io.kestra.plugin.core.flow.If
          description: Executes Skopeo copy when dry_run is false and destination does not
            already match.
          condition: "{{ not inputs.dry_run and
            outputs.evaluate_promotion_policies.vars.staging_digest !=
            outputs.evaluate_promotion_policies.vars.prod_digest }}"
          then:
            - id: promote_image_to_production
              type: io.kestra.plugin.skopeo.cli.SkopeoCLI
              description: Atomically copies the container image directly between registries
                without local Docker daemon privileges.
              commands:
                - "skopeo copy {{ secret('STAGING_REGISTRY_USERNAME') != '' ?
                  ('--src-creds ' ~ secret('STAGING_REGISTRY_USERNAME') ~ ':' ~
                  secret('STAGING_REGISTRY_PASSWORD')) : '--src-no-creds' }} {{
                  secret('PRODUCTION_REGISTRY_USERNAME') != '' ? ('--dest-creds
                  ' ~ secret('PRODUCTION_REGISTRY_USERNAME') ~ ':' ~
                  secret('PRODUCTION_REGISTRY_PASSWORD')) : '--dest-no-creds' }}
                  docker://{{ inputs.source_image }} docker://{{
                  inputs.destination_image }}"

        - id: persist_promotion_receipt
          type: io.kestra.plugin.core.storage.Write
          description: Persists cryptographic promotion receipt to internal storage for
            compliance and audit logs.
          extension: .json
          content: |
            {
              "verdict": "APPROVED_PROMOTION",
              "sourceImage": "{{ inputs.source_image }}",
              "destinationImage": "{{ inputs.destination_image }}",
              "sourceDigest": "{{ outputs.evaluate_promotion_policies.vars.staging_digest }}",
              "gitSha": "{{ outputs.evaluate_promotion_policies.vars.git_sha }}",
              "architecture": "{{ outputs.evaluate_promotion_policies.vars.architecture }}",
              "dryRun": {{ inputs.dry_run }},
              "executionId": "{{ execution.id }}"
            }

        - id: log_promotion_complete
          type: io.kestra.plugin.core.log.Log
          description: Logs audit record confirming successful image verification and
            promotion status.
          message: "PROMOTION SUCCESS: {{ outputs.evaluate_promotion_policies.vars.summary
            }}"

      REJECTED_TAG_HIJACK:
        - id: log_security_breach
          type: io.kestra.plugin.core.log.Log
          description: Emits critical security alert on detected tag immutability violation.
          message: "SECURITY ALERT: {{ outputs.evaluate_promotion_policies.vars.summary
            }}"

        - id: persist_security_incident_manifest
          type: io.kestra.plugin.core.storage.Write
          description: Stores security violation manifest containing colliding digests and
            source metadata.
          extension: .json
          content: |
            {
              "verdict": "REJECTED_TAG_HIJACK",
              "sourceImage": "{{ inputs.source_image }}",
              "destinationImage": "{{ inputs.destination_image }}",
              "stagingDigest": "{{ outputs.evaluate_promotion_policies.vars.staging_digest }}",
              "conflictingProdDigest": "{{ outputs.evaluate_promotion_policies.vars.prod_digest }}",
              "executionId": "{{ execution.id }}",
              "actionTaken": "PROMOTION_BLOCKED"
            }

        - id: check_slack_alert
          type: io.kestra.plugin.core.flow.If
          description: Sends Slack notification to SecOps on detected container tag
            collision.
          condition: "{{ inputs.notify_slack }}"
          then:
            - id: notify_slack_secops
              type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
              description: Posts high-severity tag hijack alert to Slack.
              url: "{{ secret('SLACK_WEBHOOK_URL') }}"
              payload: |
                {
                  "text": "🚨 *Container Tag Immutability Breach Blocked* | Execution `{{ execution.id }}`\n• *Target:* `{{ inputs.destination_image }}`\n• *Existing Prod Digest:* `{{ outputs.evaluate_promotion_policies.vars.prod_digest }}`\n• *Conflicting Staging Digest:* `{{ outputs.evaluate_promotion_policies.vars.staging_digest }}`\n• *Action:* Promotion Aborted"
                }

      REJECTED_MISSING_PROVENANCE:
        - id: log_provenance_failure
          type: io.kestra.plugin.core.log.Log
          description: Logs rejection notice due to missing build provenance metadata.
          message: "PROVENANCE REJECTION: {{
            outputs.evaluate_promotion_policies.vars.summary }}"

        - id: persist_provenance_rejection
          type: io.kestra.plugin.core.storage.Write
          description: Records unprovenanced build metadata for developer review.
          extension: .json
          content: |
            {
              "verdict": "REJECTED_MISSING_PROVENANCE",
              "sourceImage": "{{ inputs.source_image }}",
              "stagingDigest": "{{ outputs.evaluate_promotion_policies.vars.staging_digest }}",
              "executionId": "{{ execution.id }}"
            }

  - id: enforce_promotion_gate
    type: io.kestra.plugin.core.flow.If
    description: Fails the pipeline execution if enforce_gate is enabled and the
      promotion was rejected.
    condition: "{{ inputs.enforce_gate and
      outputs.evaluate_promotion_policies.vars.verdict != 'APPROVED_PROMOTION'
      }}"
    then:
      - id: fail_promotion_pipeline
        type: io.kestra.plugin.core.execution.Fail
        description: Halts continuous deployment pipeline execution on container
          security policy rejection.
        errorMessage: "Container promotion gate tripped: {{
          outputs.evaluate_promotion_policies.vars.summary }}"

Automates container image release gating, supply chain provenance verification, and cross-registry promotion using Skopeo. When deploying microservices to production Kubernetes clusters, promoting images directly by mutable tags (e.g. :v1.2.0) creates severe security and reliability risks: build tags can be maliciously or accidentally overwritten (tag hijacking), untrusted images lacking Git commit traceability slip into production, and full Docker daemons must traditionally be provisioned just to move container layers. This blueprint leverages Skopeo to inspect remote OCI image manifests without downloading gigabytes of layer data, verifies Git SHA provenance labels and cryptographic digest immutability, and performs daemonless, digest-pinned image promotion with full audit receipts. Unlike a mirror or sync workflow that overwrites the destination whenever it drifts from the source, this gate treats an existing, mismatched destination tag as a security incident to block and investigate, never to silently overwrite.

How it works

An event-driven io.kestra.plugin.core.trigger.Webhook trigger receives image publication notifications from upstream CI build pipelines (e.g. GitHub Actions, GitLab CI), with a disabled Schedule trigger available for batch release sweeps.
inspect_staging_manifest (io.kestra.plugin.skopeo.cli.SkopeoCLI) runs skopeo inspect against the source staging registry, extracting raw manifest metadata, architecture specifications, layer counts, and OCI annotations without pulling heavy image tarballs.
inspect_production_target (io.kestra.plugin.skopeo.cli.SkopeoCLI) queries the destination production registry to inspect whether the target tag already exists and reads its cryptographic digest.
evaluate_promotion_policies (io.kestra.plugin.scripts.python.Script) validates compliance rules:
- Tag Immutability & Anti-Hijack: Verifies that if the destination tag already exists, its digest matches the staging digest exactly. Any mismatch triggers an immediate REJECTED_TAG_HIJACK verdict.
- Supply Chain Provenance: Checks for standard OCI metadata labels (org.opencontainers.image.revision or vcs-ref) to verify Git commit traceability.
- Layer Integrity: Confirms the manifest contains valid filesystem layers and supported architecture metadata.
route_promotion_decision (io.kestra.plugin.core.flow.Switch) routes downstream execution:
- APPROVED_PROMOTION: Copies the image directly between registries using daemonless skopeo copy when dry_run is false, and persists an immutable promotion receipt to internal storage.
- REJECTED_TAG_HIJACK: Writes a security incident dossier, logs an alert, and dispatches an emergency notification to the SecOps Slack channel.
- REJECTED_MISSING_PROVENANCE: Records an unprovenanced build hold manifest for developer remediation.
enforce_promotion_gate (io.kestra.plugin.core.flow.If) halts pipeline execution via io.kestra.plugin.core.execution.Fail if enforce_gate is enabled and any policy failed.

What you get

Daemonless cross-registry container image promotion without granting privileged Docker socket access to workflow runners.
Zero-download remote manifest inspection that verifies layer structures and labels in milliseconds.
Strict tag immutability protection preventing production containers from being silently overwritten.
Automated enforcement of OCI provenance standards linking production images to verifiable Git commits.
Cryptographic promotion receipts persisted to internal storage (kestra://...) for compliance auditing.

Who it's for

Platform Engineers and DevSecOps teams establishing secure container promotion gates between staging and production clusters.
Kubernetes SREs enforcing image immutability and preventing supply-chain poisoning.
CI/CD Engineers looking to replace heavy, privileged Docker-in-Docker promotion scripts with lightweight daemonless tooling.

Why orchestrate this with Kestra

Combines container inspection, policy evaluation, and atomic cross-registry copying in a single declarative YAML workflow.
Isolates credentials and registry secrets using Kestra's encrypted secret engine instead of writing credentials to persistent build agent disks.
Provides native flow control, conditional Slack alerting, and full execution audit trails across every release.

Prerequisites

A container runtime (Docker or Kubernetes) available to the Kestra worker for executing the containerized Skopeo task.
Network connectivity to source and destination container registries.

Secrets

CONTAINER_PROMOTION_WEBHOOK_KEY: Secret authentication key for securing the incoming CI/CD Webhook trigger.
SLACK_WEBHOOK_URL: Optional Slack incoming webhook URL for dispatching security breach alerts (required only if notify_slack is enabled).
STAGING_REGISTRY_USERNAME / STAGING_REGISTRY_PASSWORD: Credentials for the source registry. Leave both set to an empty string for public, anonymously-readable registries.
PRODUCTION_REGISTRY_USERNAME / PRODUCTION_REGISTRY_PASSWORD: Credentials for the destination registry. Leave both set to an empty string for public, anonymously-writable registries (e.g. a local test registry).

Quick start

Import this blueprint into your Kestra instance.
Set the four registry secrets to empty strings for a zero-credential first run against public images, then click Execute using default inputs (alpine:3.20.0 with dry_run: true) to observe policy evaluation and manifest inspection.
Test tag immutability by setting destination_image to a different public image tag (e.g. alpine:3.19.0) to observe automated REJECTED_TAG_HIJACK detection and quarantine gating.
Configure your real STAGING_REGISTRY_USERNAME/PASSWORD and PRODUCTION_REGISTRY_USERNAME/PASSWORD secrets, then activate the on_staging_image_push webhook to connect your CI build pipeline.

How to extend

Add container vulnerability scanning (e.g. chaining io.kestra.plugin.trivy.TrivyCLI) before the promotion step to enforce zero-critical-CVE gates.
Wire Cosign signature verification (skopeo standalone-verify) to enforce cryptographic signature validation prior to registry copy.
Trigger downstream GitOps manifest synchronization (e.g. updating Helm or ArgoCD values files with the newly promoted digest).

Skopeo Container Image Promotion and Supply Chain Provenance Gate

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Secrets

Quick start

How to extend

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

New to Kestra?

Skopeo Container Image Promotion and Supply Chain Provenance Gate

How it works

What you get

Who it's for

Why orchestrate this with Kestra

Prerequisites

Secrets

Quick start

How to extend

Links

Tasks

Orchestrate with Kestra

Share this Blueprint

Create a Blueprint

More Infrastructure Blueprints

MongoDB WiredTiger Cache Pressure and Dirty Page Sentinel

MongoDB Read Model vs PostgreSQL Reconcile Guard

Run Only the Monorepo Tests Your Changed Paths Touch

MongoDB Document Validation Drift Repair Guard

MongoDB Duplicate Document Dedup Guard

Back up a MongoDB collection and prove it restores, every night

New to Kestra?