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.2.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. A run on a laptop has no CI identity to present, so a remote whose adapter supports credentials.resolve resolves the managed credentials with your epack remote login sign-in instead.

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

2. Sign in and confirm the remote

Sign in from your terminal. epack opens the remote's sign-in page in your browser, and once you allow epack there, the browser returns to epack on this machine. The adapter keeps the session, so later commands need no token. 

# Sign in with your browser
epack remote login locktivity

# Over SSH: forward a port when you connect, then open the printed link on your own computer
epack remote login locktivity --port 8400 --no-browser

Outside a project, epack installs the adapter for your user from the catalog, verifies it, and pins it in ~/.epack/remotes.lock. Run epack remote update to move that pin to the newest release. Inside a project that names the remote, the adapter pinned in epack.lock.yaml is used.

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. Run a configuration a remote generated

A remote can hand over a whole configuration: epack.yaml, its hooks, profile files, and the lock. epack run fetches one by name from the remote you last signed in to, installs the locked components, collects, runs tools, signs, and pushes. A configuration that arrives without a lock is locked by its first run or check. When the newest revision needs something this machine lacks, such as a variable or a newer epack, the run lists what is missing and where to add it, and runs the newest earlier revision that works here. 

# Fetch the configuration into ./northwind-production and run it
epack run northwind-production

# Keep the variables it lists in your keychain, for this configuration only
cd northwind-production && epack secret setup

# Check sign-in, the lock, variables, credentials, and publishers without collecting
epack run --check

# Fetch it without running, or pick up a newer revision
epack remote clone northwind-production

The variables a configuration lists under secrets come from your environment first and from your keychain second. epack secret setup asks for each missing value, hidden, and approves it for the components that read it. When a later revision changes one of those components, the check says so and epack secret approve shows the change before the value is used again. The check never prompts, and a CI job never reads the keychain. See epack secret.

A fetched configuration may only run collectors, tools, and remote adapters from publishers you trust. In a terminal, epack asks once for each new publisher and remembers your answer in ~/.epack/config.yaml. Signing in to a remote trusts its adapter's publisher. In a job, pass --trust-publisher or set EPACK_TRUSTED_PUBLISHERS.

A run from a terminal signs the pack in your browser, as you. For runs with nobody at the keyboard, give the machine a key with epack key create. Once the remote approves it, runs from this machine sign with it. See CI/CD for runners you manage.

6. 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.2.0
    target:
      workspace: myorg
      environment: prod

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