Guide

Use Remotes

Configure remote registries, then push and pull Evidence Packs with repeatable release metadata.

Prerequisites

  • epack full CLI installed (built with -tags components)
  • An epack.yaml in your project root
  • A pack file to publish (for example packs/evidence.epack)

1. Configure a remote in epack.yaml

Add a remote under remotes:. This follows the CLI's supported config shape.

epack.yaml
credential_sets:
  locktivity_push: credset_def456

remotes:
  locktivity:
    source: locktivity/epack-remote-locktivity@^0.1.0
    insecure_endpoint: https://registry.example.com
    target:
      workspace: myorg
      environment: prod
    credentials:
      - locktivity_push
    release:
      labels: [monthly]
    runs:
      sync: true

For managed runners, credential_sets let epack resolve short-lived access tokens from a Locktivity-managed broker before invoking the remote adapter. For local development, adapters may still support interactive login or direct environment-based auth.

If you need a non-default credential broker for managed credentials, set EPACK_INSECURE_CREDENTIAL_BROKER_URL.

2. Confirm remote configuration and auth status

Check that your remote is recognized and see current authentication state.

# List configured remotes
epack remote list

# Check one remote
epack remote whoami locktivity

# Or check all configured remotes
epack remote whoami

3. Push a pack to a remote

Use epack push <remote> <pack> to publish releases.

# Basic push
epack push locktivity packs/evidence.epack

# Add release labels
epack push locktivity packs/evidence.epack \
  --label soc2 \
  --label february

# Use an environment override and notes
epack push locktivity packs/evidence.epack \
  --env staging \
  --notes "Staging validation release"

Useful push flags:

  • --workspace override target workspace
  • --no-runs skip run ledger sync
  • --dry-run preview without uploading
  • --detach run push in the background
  • -y, --yes non-interactive mode

4. Pull packs from a remote

Use epack pull <remote> [ref] to download latest or specific releases.

# Pull latest release
epack pull locktivity

# Pull a specific version
epack pull locktivity v1.2.3

# Pull by release ID or digest
epack pull locktivity --release rel_abc123
epack pull locktivity --digest sha256:abc123...

# Control output location
epack pull locktivity -o ./packs/vendor.epack

Useful pull flags:

  • --env apply environment remote overrides
  • --workspace override target workspace
  • --force overwrite existing output file
  • --verify=false skip post-download verification
  • --dry-run preview without downloading
  • --detach run pull in the background

5. Use per-environment remote overrides

Keep one named remote and vary its target or labels by environment.

epack.yaml
remotes:
  locktivity:
    source: locktivity/epack-remote-locktivity@^0.1.0
    target:
      workspace: myorg
      environment: prod

environments:
  staging:
    remotes:
      locktivity:
        target:
          environment: staging
        release:
          labels: [staging]