Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 36 ยท Post-processors and Pipelines

Tagging and Pushing Container Images in a Pipeline

Chain docker-tag, docker-push and manifest post-processors correctly, log in to registries safely, choose immutable tags and record image digests for deployment.

Building a container image with Packer is only half the job. The image must get a name, reach a registry and be recorded so that deployment uses exactly that image. This lesson ties together the container post-processors and the habits that make the pipeline safe: ordered chains, secret-free login, immutable tags and digests.

Docker and registries are not reachable from this site. HCL is read-only; JavaScript stand-ins model tag rules and chain validation.

The standard chain

HCL
build {
  sources = ["source.docker.app"]

  provisioner "shell" {
    script = "scripts/install-app.sh"
  }

  post-processors {
    post-processor "docker-tag" {
      repository = "registry.example.com/team/app"
      tags       = [var.version, "sha-${var.git_sha}"]
    }
    post-processor "docker-push" {}
    post-processor "manifest" {
      output = "packer-manifest.json"
    }
  }
}

Rules to remember:

  1. docker-tag and docker-push belong in one post-processors sequence (see post-processors overview). docker-push pushes every tag the previous step created.
  2. docker-tag needs the source to have commit = true; with export_path there is no image to tag.
  3. force = true on docker-tag allows re-tagging an existing tag. Avoid it for release tags.
  4. manifest last, so it records the final artifact.

Logging in without leaking secrets

docker-push can log in itself, but it is usually cleaner to authenticate once in the pipeline before Packer runs:

Terminal
echo "$REGISTRY_TOKEN" | docker login registry.example.com -u "$REGISTRY_USER" --password-stdin
packer build -var "version=1.4.0" -var "git_sha=$GIT_SHA" .

If you do configure login in the template, use variables marked sensitive = true and supply them from the environment (PKR_VAR_registry_password), never from a committed file. Prefer short-lived tokens from your CI provider (for example an OIDC-issued token) over personal passwords.

Tag strategy

Tag Mutable? Use
1.4.0 Should be immutable A release; never overwrite
1.4, 1 Moves Convenience for consumers who accept patch updates
sha-a1b2c3d Immutable Trace an image to the commit
latest Moves Local experiments only; avoid in production manifests
main / branch names Moves Preview environments

Deploy by digest (app@sha256:...) when you need an exact, tamper-proof reference: tags are pointers and can be moved, digests cannot. Record the digest in the manifest custom_data or in your deployment repository.

Multi-architecture note

The Docker builder builds for the architecture of the Docker host. To publish amd64 and arm64, build on both (two sources or two runners) and combine them into a manifest list with docker buildx imagetools create in a shell-local step or in the CI job after Packer. If you need many architectures and no shared provisioning, a Dockerfile with BuildKit is simpler.

Scanning before pushing

Put vulnerability scanning between tag and push if possible, or scan after push and fail the pipeline before promotion. Tools such as Trivy or Grype can run in a shell-local step:

HCL
post-processor "shell-local" {
  inline = ["trivy image --exit-code 1 --severity HIGH,CRITICAL registry.example.com/team/app:${var.version}"]
}

A non-zero exit fails the build, so a vulnerable image never reaches the push step. Remember that failing after docker-tag still leaves the local tag; clean up the runner or use ephemeral runners.

flowchart LR
  B["Build + provision"] --> T["docker-tag"] --> S["scan"] --> P["docker-push"] --> M["manifest with digest"]

Scan before push so a bad image is never published.

Try it: validate a tag chain

JS Tag policy checker (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Try it: model a push gate

JS Scan gate before push (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The CVE ids above are placeholders, not real vulnerabilities.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why must docker-tag and docker-push share one post-processors block?

    Separate blocks run in parallel from the original artifact, so the push would have nothing tagged.
  2. 2. Which reference identifies an image most exactly?

    Digests are content addresses and cannot be moved.
  3. 3. Where should registry credentials come from in CI?

    Keep secrets out of Git and out of templates.
  4. 4. What is a sensible place for a vulnerability scan?

    Failing before the push prevents publishing a vulnerable image.

Summary

  • Chain docker-tag, optional scan, docker-push and manifest in one ordered sequence.
  • Log in before the build with short-lived credentials; mark template secrets sensitive.
  • Keep release and commit tags immutable; deploy by digest when you need certainty.
  • Scan before pushing and fail the pipeline on severe findings.

Next: Validating templates