Explanation

Remotes

Remote adapters enable pushing Evidence Packs to registries for distribution, versioning, and team collaboration.

What are Remotes?

Remotes are external registries where Evidence Packs can be pushed and stored. Think of them like Git remotes or Docker registries, but for compliance evidence. Each remote is backed by an adapter—an external binary that handles communication with the specific registry type.

Key Concepts

  • Remote: A named destination in your config (e.g., locktivity, s3)
  • Adapter: A binary (epack-remote-<name>) implementing the Remote Adapter Protocol
  • Target: Workspace and environment within the remote (e.g., acme/prod)
  • Release: A versioned upload with labels, notes, and metadata

Why Use Remotes?

Centralized Distribution

Push packs to a central registry where customers or internal teams can access them with proper access controls.

Version History

Each push creates a new release. Compare versions, track changes over time, and roll back if needed.

Run Ledger Sync

Automatically sync collector run results after pushing, creating a continuous record of evidence collection.

Authentication Built-in

Adapters handle authentication with the registry, supporting device code, OIDC tokens, and API keys.

The Remote Adapter Protocol

Remote adapters are external binaries that follow a JSON-over-stdin/stdout protocol, similar to Git credential helpers. This plugin architecture allows epack to support any registry type without changes to the core tool.

Adapter naming

Adapters follow the naming convention epack-remote-<name>:

  • epack-remote-locktivity — Locktivity registry
  • epack-remote-s3 — Amazon S3 storage
  • epack-remote-filesystem — Local filesystem (testing)

Protocol commands

Adapters support these commands:

Command Purpose Required
--capabilities Query adapter capabilities and features Yes
push.prepare Get presigned upload URL for pack upload Yes
push.finalize Finalize upload and create release Yes
runs.sync Sync run ledgers to remote No
auth.login Interactive authentication No
auth.whoami Query current identity No

Adapter Discovery

epack discovers adapters from multiple locations in priority order:

  1. Managed (source-based): Installed via source: field, verified via Sigstore
  2. Project-local: Found in .epack/bin/ directory
  3. System PATH: Unverified adapters found in PATH

Adapter verification status

Verified

Adapter is in the lockfile with a valid digest. Safe to execute.

Unverified

Found in PATH but not in lockfile. Use with caution.

Configuring Remotes

Remotes are configured in epack.yaml under the remotes: section:

epack.yaml
remotes:
  # Locktivity remote - managed via source
  locktivity:
    source: locktivity/epack-remote-locktivity@v1
    target:
      workspace: myorg
      environment: prod
    auth:
      mode: device_code
    release:
      labels: [monthly, soc2]
    runs:
      sync: true

  # S3 remote - adapter-only (discovered from PATH)
  s3:
    adapter: s3
    target:
      bucket: my-evidence-bucket
    runs:
      sync: false

Configuration fields

Field Type Description
source string Source reference for managed adapter (owner/repo@version)
binary string Path to external adapter binary
adapter string Adapter name (inferred from source if not set)
target object Target workspace/environment within remote
auth object Authentication settings (mode, profile)
release object Release metadata (labels, notes, source info)
runs object Run sync settings

The Push Workflow

When you run epack push, the following steps occur:

  1. 1
    Pack Verification: The pack is verified locally for integrity before upload
  2. 2
    Prepare: Adapter provides a presigned upload URL
  3. 3
    Upload: Pack is uploaded directly to storage
  4. 4
    Finalize: Release is created with labels and metadata
  5. 5
    Run Sync: Collector run results are synced (if enabled)
Terminal
# Push to configured remote
epack push locktivity packs/evidence.epack

# Push with labels
epack push locktivity packs/evidence.epack --label monthly --label soc2

# Push to staging environment
epack push locktivity packs/evidence.epack --env staging

# Push with release notes
epack push locktivity packs/evidence.epack --notes "February release"

# Push without syncing runs
epack push locktivity packs/evidence.epack --no-runs

Authentication

Adapters support multiple authentication modes:

Mode Use Case
device_code Interactive login via browser (similar to GitHub CLI)
oidc_token CI/CD workload identity (GitHub Actions, GitLab CI)
api_key API key authentication

Tokens are typically stored in the OS keychain (os_keychain), encrypted file, or passed via environment variable depending on the adapter.

Per-Environment Overrides

Use the environments: section to override remote settings for different environments:

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

environments:
  staging:
    remotes:
      locktivity:
        target:
          environment: staging
        release:
          labels: [staging]
  prod:
    remotes:
      locktivity:
        release:
          labels: [prod, soc2]

Then push using the --env flag:

epack push locktivity evidence.epack --env staging

Security Considerations

Adapter verification

  • Source-based adapters are verified via Sigstore and lockfile digests
  • External binary adapters have their digest pinned in the lockfile
  • PATH-only adapters are unverified—use with caution

Authentication security

  • Authentication is managed by the adapter, not epack
  • Tokens are stored securely (OS keychain preferred)
  • OIDC tokens provide short-lived, scoped access
Important: Only use adapters from trusted sources. An adapter has access to your credentials and can execute arbitrary code during push operations.

See Also