---
description: |
  Packer can publish metadata for completed builds to the HCP Packer registry. Learn how to connect Packer to the HCP Packer registry.
page_title: Connect to the HCP Packer registry overview
---

⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️
> [!IMPORTANT]  
> **Documentation Update:** Product documentation previously located in `/website` has moved to the [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs) repository, where all product documentation is now centralized. Please make contributions directly to `web-unified-docs`, since changes to `/website` in this repository will not appear on developer.hashicorp.com.
⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️

# Connect to the HCP Packer Registry

This topic provides an overview of how to connect JSON and HCL2 templates to the HCP Packer registry and provides a full list of HCP Packer environment variables. Refer to the
[Packer Template Configuration](/hcp/docs/packer/store-image-metadata/packer-template-configuration) page in the HCP
Packer documentation for configuration details and examples.

# Introduction

The HCP Packer registry bridges the gap between artifact factories and artifact deployments, allowing development and
security teams to work together to create, manage, and consume artifacts in a centralized way.

The HCP Packer Registry stores metadata about your artifact, including when they were created, where the artifact
exists on the external platform, and what (if any) git commit is associated with your build. You can use the registry
to track information about the artifact your Packer builds produce, clearly designate which artifact are appropriate
for test and production environments, and query for the right artifact to use in both Packer and Terraform
configurations.

You can use HCP Packer with both JSON and HCL2 templates. If you are using JSON templates, we recommend getting started with
the [HCP Packer environment variables](#hcp-packer-environment-variables) and then migrating to HCL when possible.

## Requirements

Packer version 1.9.1 or newer is required to use the `HCP_PROJECT_ID` environment variable, which lets Packer connect to specific projects in HCP. Your builds will fail if you configure them to send mulit-project metadata using Packer versions older than 1.9.1.

## HCP Packer environment variables

The following environment variables let you configure Packer to push artifact metadata to an active registry without
changing your template. You can use environment variables with both JSON and HCL2 templates.
Refer to [Basic Configuration With Environment Variables](/hcp/docs/packer/store-image-metadata/packer-template-configuration#basic-configuration-with-environment-variables)
in the HCP Packer documentation for complete instructions and examples.

You must set authentication environment variables to connect to HCP Packer, you can either directly set a client ID and secret, or (on Packer versions 1.14.2 and later) use an HCP certificate file

For client ID and secret, you set the following environemnt variables

- `HCP_CLIENT_ID`          - The HCP client ID of a HashiCorp Cloud Platform service principle that Packer can use to
authenticate to an HCP Packer Registry.

- `HCP_CLIENT_SECRET`      - The HCP client secret of the HashiCorp Cloud Platform service principle that Packer
can use to authenticate to an HCP Packer Registry.

For certificate based auth simply specify the location of the valid HCP certificate file in the `HCP_CRED_FILE` environment variable, or place it in the default location for the HCP SDK, `~/.config/hcp/cred_file.json`

See the following HCP docs for more information on [Workload Identity Federation](https://developer.hashicorp.com/hcp/docs/hcp/iam/service-principal/workload-identity-federation) and certificate authentication

- `HCP_PACKER_BUCKET_NAME` - The name of the HCP Packer Bucket where you want HCP Packer to store artifact metadata
from builds associated with your template. HCP Packer automatically creates the bucket if it does not already exist.
If your HCL2 template contains an `hcp_packer_registry` block, the bucket name specified in the configuration will be
overwritten by this environment variable.

You can set these additional environment variables to control how metadata is pushed to the registry.

- `HCP_PACKER_BUILD_FINGERPRINT` - A unique identifier assigned to each version. To reuse a fingerprint that is
associated with an existing incomplete version you must set this environment variable. Refer to
[Version Fingerprinting](#version-fingerprinting) for usage details.

- `HCP_PACKER_REGISTRY`    -  When set, Packer does not push artifact metadata to HCP Packer from an otherwise
configured template. Allowed values are [0|OFF].

- `HCP_ORGANIZATION_ID` - The ID of the HCP organization linked to your service principal. This is environment
variable is not required and available for the sole purpose of keeping parity with the HCP SDK authentication options.
Its use may change in a future release.

- `HCP_PROJECT_ID`  - The ID of the HCP project to use. This is useful if your service principal has access to multiple
projects, as by default Packer will pick the one created first as target.

-> **Note**: The HCP_PROJECT_ID environment variable must be set if you're authenticating with a project-level service
principal, otherwise Packer will attempt to get the list of projects for an organization and error due to a lack of
permissions for a project-level service principal. This is supported starting with Packer 1.9.3; older versions of
Packer do not support using project-level service principals.

## HCP Packer registry block

The only metadata that Packer can infer from a template with the basic configuration are the build name and build fingerprint.
For HCL2 templates, we recommend adding the `hcp_packer_registry` block to your template so that you can customize
the metadata that Packer sends to the registry.

The `hcp_packer_registry` block is only available for HCL2 Packer templates. There is no [`PACKER_CONFIG`](/packer/docs/configure#packer-s-config-file) equivalent for JSON.

Refer to [`hcp_packer_registry`](/packer/docs/templates/hcl_templates/blocks/build/hcp_packer_registry) for a full list
of configuration arguments. Refer to [Custom Configuration](/hcp/docs/packer/store-image-metadata/packer-template-configuration#custom-configuration)
in the HCP Packer documentation for information and examples about how to customize artifact metadata.

## Version fingerprinting

Packer uses a unique fingerprint for tracking the completion of builds associated to a version. By default a fingerprint
is automatically generated by Packer during each invocation of `packer build`, unless a fingerprint is manually provided
via the `HCP_PACKER_BUILD_FINGERPRINT` environment variable.

In versions before 1.9.0, this fingerprint was computed from the Git SHA of the current HEAD in which your template is
stored. If you were running builds using a non Git managed template, you had to set the `HCP_PACKER_BUILD_FINGERPRINT`
environment variable prior to invoking `packer build`.
Starting with Packer 1.9.0, fingerprint generation does not rely on Git at all, and instead Packer now generates
a Unique Lexicographically sortable Identifier (ULID) as the fingerprint for every `packer build` invocation.

### Fingerprints and incomplete versions

When you build a template with Packer, there's always a chance that it does not succeed because of a network issue,
a provisioning failure, or some upstream error. When that happens, Packer will output the generated fingerprint
associated with the incomplete version so that you can resume building that version using the `HCP_PACKER_BUILD_FINGERPRINT`
environment variable; a version can be resumed until it is marked as complete. This environment variable is necessary
for resuming an incomplete version, otherwise Packer will create a new version for the build.

There are two alternatives for when and how to set your own fingerprint:

* You can set it prior to invoking `packer build` for the first time on this template. This will require the
fingerprint to be unique, otherwise Packer will attempt to continue the version with the same fingerprint.
* You can invoke `packer build` on the template, and if it fails, you can then get the fingerprint from the output of
the command and set it for subsequent runs, Packer will then continue building this version.

The first alternative is recommended for CI environments, as you can use environment variables from the CI to generate
a unique, deterministic, fingerprint, and then re-use this in case the step fails for any reason. This will let you
continue building the same version, rather than creating a new one on each invocation.

The second alternative is good for local builds, as you can interact with the build environment directly, and therefore
can decide if you want to continue building a version by setting the fingerprint provided by Packer in case of failure.

Please note that in all cases, a version can only be continued if it has not completed yet. Once a version is
complete, it cannot be modified, and you will have to create a new one.
