Release Manifest & Distribution

Use your BigHammer reader role to mirror entitled container images, Helm charts, and code packages into your registries. Start with Step 1 — customer profile onboarding; then run the mirror workflow once per release.

Mirror — do not consume from BigHammer catalog long-term

BigHammer catalog artifacts may be archived or removed after a retention period. Always mirror into your Google Artifact Registry (and your private PyPI/npm repos if entitled) and treat those copies as your source of truth.

Step 1 — Customer profile registry (onboarding)

Before you can pull or mirror any artifact, BigHammer registers a customer profile for your organization. That profile defines who you are, what you are entitled to pull, and how your CI authenticates to the shared BigHammer release catalog.

BigHammer uses the profile to provision your dedicated IAM reader role:

arn:aws:iam::<bh-aws-account-id>:role/bh-artifact-reader-<customer_id>

You do not get a separate copy of the catalog at BigHammer. Access is scoped to entitled charts, images, and packages only.

What you submit

Send the following to your BigHammer contact. They map it to a CustomerProfile (apiVersion: bighammer.io/v1).

Organization and contacts

Field	Example	Notes
Customer ID	`<customer-id>`	Stable kebab-case name; becomes part of the reader role
Display name	Example Corp	Legal or team name
Technical contact	`devops@example.com`	Handoff and entitlement changes
Security / billing contacts	Optional emails	Escalation and quota notices

GCP deployment

Field	Example
Primary cloud	`gcp`
GCP project ID	`<your-gcp-project>`
Region(s)	`<your-gcp-region>`
GKE cluster name	`<your-gke-cluster>` (if known)

CI trust (choose at least one)

Your mirror pipeline must assume the reader role. Tell BigHammer which method you use:

Method	What you provide
GitHub Actions OIDC	GitHub org + repo path(s), e.g. `<your-github-org>/bh-platform-deploy`
GitLab CI OIDC	GitLab project path (+ host if self-managed)
AWS cross-account	Your AWS account ID; BigHammer sends ExternalId via secure channel

Artifact entitlements

Field	Typical value (GCP)
Version channel	`stable`, `rc`, or `lts`
Helm charts	`bighammer`, `bh-gateway`, `bhrabbitmq`
Container images	`platform_release` (full chart image set) or named allowlist
Code packages (optional)	Entitled PyPI / npm package names

Target registries (your GCP project)

Confirm GAR repository names you will mirror into:

Artifact	GAR format	Example ID
Container images	`DOCKER`	`bh-docker-public`
Helm OCI charts	`DOCKER`	`bh-helm-release`
Python packages	`PYTHON`	`bh-pypi-mirror`
npm packages	`NPM`	`bh-npm-mirror`

Intake example (GCP)

Reference structure — BigHammer completes and stores the profile on your behalf:

apiVersion: bighammer.io/v1
kind: CustomerProfile

metadata:
  customer_id: <customer-id>
  display_name: Example Corp (GCP)

deployment:
  primary_cloud: gcp
  platform:
    gcp:
      project_id: <your-gcp-project>
      region: <your-gcp-region>
      gke_cluster_name: <your-gke-cluster>

artifact_access:
  aws_reader_role:
    enabled: true
    trust:
      github_oidc:
        - organization: <your-github-org>
          repositories:
            - <your-github-org>/bh-platform-deploy

artifact_entitlements:
  version_channel: stable
  helm_charts:
    - name: bighammer
    - name: bh-gateway
    - name: bhrabbitmq
  container_images:
    mode: platform_release
  codeartifact:
    pypi_packages:
      - <entitled-pypi-package>

What BigHammer returns (handoff pack)

After your profile is active, you receive:

Item	Example
Reader role ARN	`arn:aws:iam::<bh-aws-account-id>:role/bh-artifact-reader-<customer-id>`
AWS region	`<bh-catalog-aws-region>` (from handoff pack)
Release manifest	Pinned chart versions, image tags, package versions
Entitlements summary	Charts, images, and packages in scope
Trust runbook	GitHub OIDC, GitLab OIDC, or AWS `AssumeRole` + `ExternalId`
Source URIs	BigHammer ECR and CodeArtifact endpoints (mirror pull only)
Egress limits	Monthly direct-pull quota on the reader role

Store ExternalId in a secrets manager — never commit it to Git.

Onboarding checklist

Step	Done
Intake submitted (org, GCP project, CI trust, entitlements)	☐
GAR repos created in your project (Docker, Helm OCI, Python/npm if entitled)	☐
Handoff pack received (reader role ARN + release manifest)	☐
Test assume-role from CI (dry pull or `aws sts get-caller-identity`)	☐

Only after Step 1 is complete, proceed to mirror artifacts (Steps 2–4 below).

Mirrored URIs (examples):

us-docker.pkg.dev/<project>/bh-docker-public/<service>:<tag>
oci://us-docker.pkg.dev/<project>/bh-helm-release/bighammer:<version>
https://<your-gcp-region>-python.pkg.dev/<project>/bh-pypi-mirror/simple/
https://<your-gcp-region>-npm.pkg.dev/<project>/bh-npm-mirror/

Steps 2–4 — Mirror workflow

Step	Environment	Action
1	You → BigHammer	Complete customer profile intake; receive handoff pack
2	Your CI ↔ BH AWS	Assume `bh-artifact-reader-<customer_id>`
3	Your CI ← BH catalog	Pull entitled images, charts, and code packages
4	Your CI → Your GAR	Mirror to your Docker, Helm OCI, Python, and npm repos

Release manifest

BigHammer sends a release manifest per upgrade. Pin every version in your mirror CI — do not use floating tags.

# release-manifest.yaml (your repo)
release: "2026-06"
channel: stable

charts:
  bighammer: "<chart-version>"
  bh-gateway: "<chart-version>"
  bhrabbitmq: "<chart-version>"

images:
  bh-ui: "<tag-from-release-manifest>"
  bh-catalog-api: "<tag-from-release-manifest>"
  bh-audit-api: "<tag-from-release-manifest>"
  bh-keycloak: "<tag-from-release-manifest>"

packages:
  pypi:
    <entitled-pypi-package-1>: "<package-version-from-manifest>"
    <entitled-pypi-package-2>: "<package-version-from-manifest>"
  npm:
    <entitled-npm-package>: "<package-version-from-manifest>"

CI authentication

Credential	Used for
BH reader role	Pull from BH ECR and CodeArtifact
GCP (WIF or SA)	Push to your GAR repos

Assume reader role (GitHub Actions)

permissions:
  id-token: write
  contents: read

- uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: arn:aws:iam::<bh-aws-account-id>:role/bh-artifact-reader-<customer_id>
    aws-region: <bh-catalog-aws-region>

GitLab: OIDC + aws sts assume-role-with-web-identity with BH_ARTIFACT_READER_ROLE_ARN.
AWS CI: aws sts assume-role with role ARN and ExternalId from your handoff.

GCP (push to GAR)

- uses: google-github-actions/auth@v3
  with:
    workload_identity_provider: projects/<NUM>/locations/global/workloadIdentityPools/<POOL>/providers/<PROVIDER>
    service_account: <mirror-sa>@<project>.iam.gserviceaccount.com

CI service account: roles/artifactregistry.writer on your mirror repos.

Mirror container images

Source (BH):

<bh-aws-account-id>.dkr.ecr.<bh-catalog-aws-region>.amazonaws.com/<bh-catalog-docker-repo>/<service>:<tag>

Target (your GAR):

<region>-docker.pkg.dev/<project>/bh-docker-public/<service>:<tag>

aws ecr get-login-password --region <bh-catalog-aws-region> | \
  docker login --username AWS --password-stdin <bh-aws-account-id>.dkr.ecr.<bh-catalog-aws-region>.amazonaws.com

gcloud auth configure-docker <your-gcp-region>-docker.pkg.dev --quiet

SERVICE=bh-ui
TAG=<tag-from-release-manifest>
BH=<bh-aws-account-id>.dkr.ecr.<bh-catalog-aws-region>.amazonaws.com/<bh-catalog-docker-repo>
GAR=<your-gcp-region>-docker.pkg.dev/<project>/bh-docker-public

docker pull $BH/$SERVICE:$TAG
docker tag  $BH/$SERVICE:$TAG $GAR/$SERVICE:$TAG
docker push $GAR/$SERVICE:$TAG

Repeat for each entitled image in the release manifest.

Mirror Helm charts

Source (BH):

oci://<bh-aws-account-id>.dkr.ecr.<bh-catalog-aws-region>.amazonaws.com/gcp/bh-helm-release/<chart>:<version>

Target (your GAR):

oci://<region>-docker.pkg.dev/<project>/bh-helm-release/<chart>:<version>

BH_ECR=<bh-aws-account-id>.dkr.ecr.<bh-catalog-aws-region>.amazonaws.com
GAR_HELM=oci://<your-gcp-region>-docker.pkg.dev/<project>/bh-helm-release
CHART=bighammer
VER=<chart-version>

aws ecr get-login-password --region <bh-catalog-aws-region> | \
  helm registry login --username AWS --password-stdin $BH_ECR

helm pull oci://$BH_ECR/gcp/bh-helm-release/$CHART --version $VER

gcloud auth print-access-token | \
  helm registry login <your-gcp-region>-docker.pkg.dev --username oauth2accesstoken --password-stdin

helm push ${CHART}-${VER}.tgz $GAR_HELM

Repeat for each entitled chart (bighammer, bh-gateway, bhrabbitmq, etc.).

Mirror code packages (PyPI / npm)

If your contract includes CodeArtifact entitlements, mirror entitled packages the same way as images and charts.

BigHammer source (pull only)

Type	Endpoint
PyPI	`https://bighammer-<bh-aws-account-id>.d.codeartifact.<bh-catalog-aws-region>.amazonaws.com/pypi/<bh-catalog-pypi-repo>/simple/`
npm	`https://bighammer-<bh-aws-account-id>.d.codeartifact.<bh-catalog-aws-region>.amazonaws.com/npm/<bh-catalog-npm-repo>/`

Domain: <bh-codeartifact-domain> · Account: <bh-aws-account-id> · Region: <bh-catalog-aws-region>

Only package names in your entitlement list can be downloaded with the reader role.

Mirror PyPI packages to GAR

PKG=<entitled-pypi-package>
VER=<package-version-from-manifest>
WHEEL_DIR=./wheelhouse

aws codeartifact login --tool pip \
  --domain <bh-codeartifact-domain> \
  --domain-owner <bh-aws-account-id> \
  --repository <bh-catalog-pypi-repo> \
  --region <bh-catalog-aws-region>

pip download "$PKG==$VER" -d "$WHEEL_DIR"

# Upload to your GAR Python repository
twine upload --repository-url \
  "https://<your-gcp-region>-python.pkg.dev/<project>/bh-pypi-mirror/" \
  "$WHEEL_DIR"/*

Configure twine auth with a GCP access token or keyring plugin for Artifact Registry.

Mirror npm packages to GAR

PKG=<entitled-npm-package>
VER=<package-version-from-manifest>
OUT=./npm-packages

aws codeartifact login --tool npm \
  --domain <bh-codeartifact-domain> \
  --domain-owner <bh-aws-account-id> \
  --repository <bh-catalog-npm-repo> \
  --region <bh-catalog-aws-region>

mkdir -p "$OUT"
npm pack "${PKG}@${VER}" --pack-destination "$OUT"

# Publish to your GAR npm repository
npm publish "$OUT"/*.tgz \
  --registry "https://<your-gcp-region>-npm.pkg.dev/<project>/bh-npm-mirror/"

Use gcloud auth print-access-token or .npmrc with Artifact Registry credentials for the publish step.

Verify mirrored packages

# PyPI — list from your GAR simple index
curl -s "https://<your-gcp-region>-python.pkg.dev/<project>/bh-pypi-mirror/simple/<package>/"

# npm — view package metadata
npm view <entitled-npm-package> --registry https://<your-gcp-region>-npm.pkg.dev/<project>/bh-npm-mirror/

Sample mirror pipeline (GitHub Actions)

Mirror only — no cluster steps.

name: Mirror BigHammer artifacts

on:
  workflow_dispatch:
    inputs:
      chart_version: { required: true, default: "<chart-version>" }
      image_tag: { required: true, default: "<tag-from-release-manifest>" }

permissions:
  id-token: write
  contents: read

env:
  AWS_REGION: <bh-catalog-aws-region>
  BH_ROLE: arn:aws:iam::<bh-aws-account-id>:role/bh-artifact-reader-<customer_id>
  BH_ECR: <bh-aws-account-id>.dkr.ecr.<bh-catalog-aws-region>.amazonaws.com
  GAR_REGION: <your-gcp-region>
  GCP_PROJECT: <project>
  GAR_DOCKER: <your-gcp-region>-docker.pkg.dev/<project>/bh-docker-public
  GAR_HELM: oci://<your-gcp-region>-docker.pkg.dev/<project>/bh-helm-release

jobs:
  mirror:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ env.BH_ROLE }}
          aws-region: ${{ env.AWS_REGION }}

      - uses: google-github-actions/auth@v3
        with:
          workload_identity_provider: projects/<NUM>/locations/global/workloadIdentityPools/<POOL>/providers/<PROVIDER>
          service_account: <mirror-sa>@${{ env.GCP_PROJECT }}.iam.gserviceaccount.com

      - uses: google-github-actions/setup-gcloud@v3

      - name: Mirror container images
        env:
          TAG: ${{ github.event.inputs.image_tag }}
        run: |
          aws ecr get-login-password --region $AWS_REGION | docker login --username AWS --password-stdin $BH_ECR
          gcloud auth configure-docker ${{ env.GAR_REGION }}-docker.pkg.dev --quiet
          for img in bh-ui bh-catalog-api bh-audit-api bh-keycloak; do
            docker pull $BH_ECR/<bh-catalog-docker-repo>/$img:$TAG
            docker tag  $BH_ECR/<bh-catalog-docker-repo>/$img:$TAG $GAR_DOCKER/$img:$TAG
            docker push $GAR_DOCKER/$img:$TAG
          done

      - uses: azure/setup-helm@v4

      - name: Mirror Helm charts
        env:
          VER: ${{ github.event.inputs.chart_version }}
        run: |
          aws ecr get-login-password --region $AWS_REGION | helm registry login --username AWS --password-stdin $BH_ECR
          gcloud auth print-access-token | helm registry login ${{ env.GAR_REGION }}-docker.pkg.dev --username oauth2accesstoken --password-stdin
          for chart in bighammer bh-gateway bhrabbitmq; do
            helm pull oci://$BH_ECR/gcp/bh-helm-release/$chart --version $VER
            helm push ${chart}-${VER}.tgz ${{ env.GAR_HELM }}
          done

      - name: Mirror PyPI packages
        run: |
          pip install twine
          aws codeartifact login --tool pip --domain <bh-codeartifact-domain> --domain-owner <bh-aws-account-id> \
            --repository <bh-catalog-pypi-repo> --region $AWS_REGION
          mkdir -p wheelhouse
          pip download <entitled-pypi-package>==<package-version-from-manifest> -d wheelhouse
          twine upload --repository-url \
            "https://${{ env.GAR_REGION }}-python.pkg.dev/${{ env.GCP_PROJECT }}/bh-pypi-mirror/" \
            wheelhouse/*

      - name: Mirror npm packages
        run: |
          aws codeartifact login --tool npm --domain <bh-codeartifact-domain> --domain-owner <bh-aws-account-id> \
            --repository <bh-catalog-npm-repo> --region $AWS_REGION
          npm pack <entitled-npm-package>@<package-version-from-manifest>
          npm publish <entitled-npm-package>-<package-version-from-manifest>.tgz \
            --registry "https://${{ env.GAR_REGION }}-npm.pkg.dev/${{ env.GCP_PROJECT }}/bh-npm-mirror/"

Run once per release manifest change. Package names and versions must match your entitlements and release manifest.

BigHammer source URIs (reference)

Region: <bh-catalog-aws-region> · Account: <bh-aws-account-id>. Use only during the mirror job.

Artifact	Pull URI
Container image	`<bh-aws-account-id>.dkr.ecr.<bh-catalog-aws-region>.amazonaws.com/<bh-catalog-docker-repo>/<service>:<tag>`
Helm chart	`oci://<bh-aws-account-id>.dkr.ecr.<bh-catalog-aws-region>.amazonaws.com/gcp/bh-helm-release/<chart>:<version>`
PyPI package	`https://bighammer-<bh-aws-account-id>.d.codeartifact.<bh-catalog-aws-region>.amazonaws.com/pypi/<bh-catalog-pypi-repo>/simple/`
npm package	`https://bighammer-<bh-aws-account-id>.d.codeartifact.<bh-catalog-aws-region>.amazonaws.com/npm/<bh-catalog-npm-repo>/`

Checklist

Step	Done
Step 1 — Customer profile intake submitted and handoff received	☐
Reader role ARN and trust configured in CI	☐
GAR repos: Docker, Helm OCI, Python, npm (as entitled)	☐
CI SA: `artifactregistry.writer` on mirror repos	☐
`release-manifest.yaml` pinned in your repo	☐
Image mirror tested for current release	☐
Helm chart mirror tested for current release	☐
PyPI / npm mirror tested (if entitled)	☐

Topic	Link
Published chart versions	Helm Chart Release Notes
GKE Workload Identity	Workload Identity

Step 1 — Customer profile registry (onboarding)​

What you submit​

Organization and contacts​

GCP deployment​

CI trust (choose at least one)​

Artifact entitlements​

Target registries (your GCP project)​

Intake example (GCP)​

What BigHammer returns (handoff pack)​

Onboarding checklist​

Steps 2–4 — Mirror workflow​

Release manifest​

CI authentication​

Assume reader role (GitHub Actions)​

GCP (push to GAR)​

Mirror container images​

Mirror Helm charts​

Mirror code packages (PyPI / npm)​

BigHammer source (pull only)​

Mirror PyPI packages to GAR​

Mirror npm packages to GAR​

Verify mirrored packages​

Sample mirror pipeline (GitHub Actions)​

BigHammer source URIs (reference)​

Checklist​

Related​