Generated banner for Push To Registry
Generated logo for Push To Registry

Push To Registry

HashiCorpOfficialPublished by HashiCorp

  • Skill
  • Tool integration
  • Cloud and DevOps
  • MPL-2.0
  • No issues found

From the author

Push Packer build metadata to HCP Packer registry for tracking and managing image lifecycle. Use when integrating Packer builds with HCP Packer for version control and governance.
— the description by HashiCorp

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides the configuration patterns and authentication steps required to push build metadata from Packer to the HCP Packer registry. By integrating with the registry, teams can track image versions, manage lifecycles, and ensure governance across their infrastructure builds. The process involves adding an hcp_packer_registry block to Packer templates and configuring service principal credentials, enabling seamless artifact discovery in downstream workflows like Terraform deployments.

What it does

  • Configures Packer templates to push build metadata to the HCP Packer registry.
  • Defines bucket and build-level labels for enhanced image tracking.
  • Provides authentication procedures using HCP service principals.
  • Demonstrates CI/CD integration for automated image builds.
  • Shows how to query registry artifacts for use in Terraform configurations.

When to use it

  • When you need to track and manage the lifecycle of machine images.
  • When integrating image builds into a centralized governance and versioning system.
  • When automating image distribution across multiple cloud environments.
  • When you want to dynamically reference the latest verified images in Terraform.

Advantages

  • Enables centralized visibility into image versions and build history.
  • Supports automated image lifecycle management and governance.
  • Facilitates consistent image consumption in infrastructure-as-code workflows.
  • Adds minimal overhead to the build process.

Usage examples

“How do I configure my Packer template to send build metadata to HCP Packer?”
The agent provides the hcp_packer_registry block structure to include in your build file, specifying the required bucket_name and optional labels.
“What environment variables are needed for HCP Packer authentication in CI/CD?”
The agent lists the required HCP_CLIENT_ID, HCP_CLIENT_SECRET, HCP_ORGANIZATION_ID, and HCP_PROJECT_ID variables.
“How can I use an image from the HCP Packer registry in my Terraform code?”
The agent provides a data source example using hcp_packer_artifact to retrieve the external identifier for an image based on its channel and bucket.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/hashicorp/push-to-registry/download
  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip push-to-registry.zip -d .agents/skills

Documentation by HashiCorp

Push to HCP Packer Registry

Configure Packer templates to push build metadata to HCP Packer registry.

Reference: HCP Packer Registry

Note: HCP Packer is free for basic use. Builds push metadata only (not actual images), adding minimal overhead (<1 minute).

Basic Registry Configuration

packer {
  required_version = ">= 1.7.7"
}

variable "image_name" {
  type    = string
  default = "web-server"
}

locals {
  timestamp = regex_replace(timestamp(), "[- TZ:]", "")
}

source "amazon-ebs" "ubuntu" {
  region        = "us-west-2"
  instance_type = "t3.micro"

  source_ami_filter {
    filters = {
      name = "ubuntu/images/*ubuntu-jammy-22.04-amd64-server-*"
    }
    most_recent = true
    owners      = ["099720109477"]
  }

  ssh_username = "ubuntu"
  ami_name     = "${var.image_name}-${local.timestamp}"
}

build {
  sources = ["source.amazon-ebs.ubuntu"]

  hcp_packer_registry {
    bucket_name = var.image_name
    description = "Ubuntu 22.04 base image for web servers"

    bucket_labels = {
      "os"   = "ubuntu"
      "team" = "platform"
    }

    build_labels = {
      "build-time" = local.timestamp
    }
  }

  provisioner "shell" {
    inline = [
      "sudo apt-get update",
      "sudo apt-get upgrade -y",
    ]
  }
}

Authentication

Set environment variables before building:

export HCP_CLIENT_ID="your-service-principal-client-id"
export HCP_CLIENT_SECRET="your-service-principal-secret"
export HCP_ORGANIZATION_ID="your-org-id"
export HCP_PROJECT_ID="your-project-id"

packer build .
Create HCP Service Principal
  1. Navigate to HCP → Access Control (IAM)

  2. Create Service Principal

  3. Grant "Contributor" role on project

  4. Generate client secret

  5. Save client ID and secret

Registry Configuration Options

bucket_name (required)

The image identifier. Must stay consistent across builds!

bucket_name = "web-server"  # Keep this constant
bucket_labels (optional)

Metadata at bucket level. Updates with each build.

bucket_labels = {
  "os"        = "ubuntu"
  "team"      = "platform"
  "component" = "web"
}
build_labels (optional)

Metadata for each iteration. Immutable after build completes.

build_labels = {
  "build-time" = local.timestamp
  "git-commit" = var.git_commit
}

CI/CD Integration

GitHub Actions
name: Build and Push to HCP Packer

on:
  push:
    branches: [main]

env:
  HCP_CLIENT_ID: ${{ secrets.HCP_CLIENT_ID }}
  HCP_CLIENT_SECRET: ${{ secrets.HCP_CLIENT_SECRET }}
  HCP_ORGANIZATION_ID: ${{ secrets.HCP_ORGANIZATION_ID }}
  HCP_PROJECT_ID: ${{ secrets.HCP_PROJECT_ID }}

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-packer@main

      - name: Build and push
        run: |
          packer init .
          packer build \
            -var "git_commit=${{ github.sha }}" \
            .

Querying in Terraform

data "hcp_packer_artifact" "ubuntu" {
  bucket_name  = "web-server"
  channel_name = "production"
  platform     = "aws"
  region       = "us-west-2"
}

resource "aws_instance" "web" {
  ami           = data.hcp_packer_artifact.ubuntu.external_identifier
  instance_type = "t3.micro"

  tags = {
    PackerBucket = data.hcp_packer_artifact.ubuntu.bucket_name
  }
}

Common Issues

Authentication Failed

  • Verify HCP_CLIENT_ID and HCP_CLIENT_SECRET

  • Ensure service principal has Contributor role

  • Check organization and project IDs

Bucket Name Mismatch

  • Keep bucket_name consistent across builds

  • Don't include timestamps in bucket_name

  • Creates new bucket if name changes

Build Fails

  • Packer fails immediately if can't push metadata

  • Prevents drift between artifacts and registry

  • Check network connectivity to HCP API

Best Practices

  • Consistent bucket names - Never change for same image type

  • Meaningful labels - Use for versions, teams, compliance

  • CI/CD automation - Automate builds and registry pushes

  • Immutable build labels - Put changing data (git SHA, date) in build_labels

References

Files

SKILL.md

Push to HCP Packer Registry

Configure Packer templates to push build metadata to HCP Packer registry.

Reference: HCP Packer Registry

Note: HCP Packer is free for basic use. Builds push metadata only (not actual images), adding minimal overhead (<1 minute).

Basic Registry Configuration

packer {
  required_version = ">= 1.7.7"
}

variable "image_name" {
  type    = string
  default = "web-server"
}

locals {
  timestamp = regex_replace(timestamp(), "[- TZ:]", "")
}

source "amazon-ebs" "ubuntu" {
  region        = "us-west-2"
  instance_type = "t3.micro"

  source_ami_filter {
    filters = {
      name = "ubuntu/images/*ubuntu-jammy-22.04-amd64-server-*"
    }
    most_recent = true
    owners      = ["099720109477"]
  }

  ssh_username = "ubuntu"
  ami_name     = "${var.image_name}-${local.timestamp}"
}

build {
  sources = ["source.amazon-ebs.ubuntu"]

  hcp_packer_registry {
    bucket_name = var.image_name
    description = "Ubuntu 22.04 base image for web servers"

    bucket_labels = {
      "os"   = "ubuntu"
      "team" = "platform"
    }

    build_labels = {
      "build-time" = local.timestamp
    }
  }

  provisioner "shell" {
    inline = [
      "sudo apt-get update",
      "sudo apt-get upgrade -y",
    ]
  }
}

Authentication

Set environment variables before building:

export HCP_CLIENT_ID="your-service-principal-client-id"
export HCP_CLIENT_SECRET="your-service-principal-secret"
export HCP_ORGANIZATION_ID="your-org-id"
export HCP_PROJECT_ID="your-project-id"

packer build .
Create HCP Service Principal
  1. Navigate to HCP → Access Control (IAM)

  2. Create Service Principal

  3. Grant "Contributor" role on project

  4. Generate client secret

  5. Save client ID and secret

Registry Configuration Options

bucket_name (required)

The image identifier. Must stay consistent across builds!

bucket_name = "web-server"  # Keep this constant
bucket_labels (optional)

Metadata at bucket level. Updates with each build.

bucket_labels = {
  "os"        = "ubuntu"
  "team"      = "platform"
  "component" = "web"
}
build_labels (optional)

Metadata for each iteration. Immutable after build completes.

build_labels = {
  "build-time" = local.timestamp
  "git-commit" = var.git_commit
}

CI/CD Integration

GitHub Actions
name: Build and Push to HCP Packer

on:
  push:
    branches: [main]

env:
  HCP_CLIENT_ID: ${{ secrets.HCP_CLIENT_ID }}
  HCP_CLIENT_SECRET: ${{ secrets.HCP_CLIENT_SECRET }}
  HCP_ORGANIZATION_ID: ${{ secrets.HCP_ORGANIZATION_ID }}
  HCP_PROJECT_ID: ${{ secrets.HCP_PROJECT_ID }}

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: hashicorp/setup-packer@main

      - name: Build and push
        run: |
          packer init .
          packer build \
            -var "git_commit=${{ github.sha }}" \
            .

Querying in Terraform

data "hcp_packer_artifact" "ubuntu" {
  bucket_name  = "web-server"
  channel_name = "production"
  platform     = "aws"
  region       = "us-west-2"
}

resource "aws_instance" "web" {
  ami           = data.hcp_packer_artifact.ubuntu.external_identifier
  instance_type = "t3.micro"

  tags = {
    PackerBucket = data.hcp_packer_artifact.ubuntu.bucket_name
  }
}

Common Issues

Authentication Failed

  • Verify HCP_CLIENT_ID and HCP_CLIENT_SECRET

  • Ensure service principal has Contributor role

  • Check organization and project IDs

Bucket Name Mismatch

  • Keep bucket_name consistent across builds

  • Don't include timestamps in bucket_name

  • Creates new bucket if name changes

Build Fails

  • Packer fails immediately if can't push metadata

  • Prevents drift between artifacts and registry

  • Check network connectivity to HCP API

Best Practices

  • Consistent bucket names - Never change for same image type

  • Meaningful labels - Use for versions, teams, compliance

  • CI/CD automation - Automate builds and registry pushes

  • Immutable build labels - Put changing data (git SHA, date) in build_labels

References

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
HashiCorp
Publisher
HashiCorp (Official)
Source
hashicorp/agent-skills · plugins/packer/skills/push-to-registry · commit 5e30fa5
Licence
Mozilla Public License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by HashiCorp.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download push-to-registry.zip