Configuration

Precedence

Settings are applied in this order (highest to lowest priority):

Command-line flags — Always win
Environment variables — Override config file
Config file (epack.yaml) — Project-level settings
Defaults — Built-in defaults

Environment Variables

Signing

Variable	Description	Default
`EPACK_OIDC_TOKEN`	OIDC token for keyless signing in CI. Required for non-interactive environments.	—
`EPACK_SIGSTORE_URL`	Custom Fulcio URL for private Sigstore instances.	`https://fulcio.sigstore.dev`
`EPACK_REKOR_URL`	Custom Rekor URL for private transparency logs.	`https://rekor.sigstore.dev`
`EPACK_TUF_ROOT`	Custom TUF root for private Sigstore instances.	—

Output & Logging

Variable	Description	Default
`NO_COLOR`	Disable colored output. Set to any non-empty value.	—
`EPACK_DEBUG`	Enable debug logging. Set to `true` or `1`.	`false`
`EPACK_LOG_FORMAT`	Log format: `text` or `json`.	`text`

Paths & Caching

Variable	Description	Default
`EPACK_CACHE_DIR`	Directory for downloaded collectors and tools.	`~/.cache/epack`
`EPACK_CONFIG_DIR`	Directory for global configuration.	`~/.config/epack`
`EPACK_DATA_DIR`	Directory for persistent data.	`~/.local/share/epack`

Collectors (Full Edition)

Variable	Description	Default
`GITHUB_TOKEN`	GitHub API token for the GitHub collector (classic PAT or short-lived installation token).	—
`EPACK_COLLECTOR_TIMEOUT`	Default timeout for collectors.	`60s`
`EPACK_PARALLEL_COLLECTORS`	Maximum concurrent collectors.	`4`

Configuration File

epack looks for epack.yaml in the current directory or any parent directory.

Minimal example

epack.yaml

            stream: myorg/prod

Full example (Full Edition)

epack.yaml

            # Evidence stream identifier
stream: myorg/prod

# Output path (optional)
output: evidence.epack

# Target platforms for lockfile
platforms:
  - linux/amd64
  - darwin/arm64

# Optional Locktivity-managed credential refs resolved at runtime
credential_sets:
  github_repo: credset_abc123
  locktivity_push: credset_def456

# Collectors configuration
collectors:
  github:
    source: locktivity/epack-collector-github@^0.1.0
    config:
      organization: myorg
      include_patterns:
        - api-*
        - web-*
    credentials:
      - github_repo
    # For manual setups, use secrets instead:
    # secrets:
    #   - GITHUB_TOKEN

  aws:
    source: locktivity/epack-collector-aws@v1
    config:
      regions:
        - us-east-1
        - us-west-2
    secrets:
      - AWS_ACCESS_KEY_ID
      - AWS_SECRET_ACCESS_KEY

# Tools configuration
tools:
  ask:
    source: locktivity/epack-tool-ask@v1
    secrets:
      - OPENAI_API_KEY

  validate:
    source: locktivity/epack-tool-validate@v1
    config:
      profile: profiles/soc2-basic.yaml
      overlays:
        - profiles/overlays/production.yaml

# Profiles for compliance validation
profiles:
  - source: locktivity/soc2-basic@v1
  - path: profiles/custom-policy.yaml

# Overlays customize profiles per environment
overlays:
  - path: profiles/overlays/production.yaml

# Remotes configuration
remotes:
  locktivity:
    source: locktivity/epack-remote-locktivity@^0.1.0
    insecure_endpoint: https://registry.example.com
    auth:
      insecure_endpoint: https://auth.example.com
    target:
      workspace: myorg
      environment: prod
    credentials:
      - locktivity_push
    release:
      labels: [monthly, soc2]
      source:
        git:
          sha_env: GITHUB_SHA
          repo_env: GITHUB_REPOSITORY
        ci:
          run_url_env: GITHUB_RUN_URL
    runs:
      sync: true

# Per-environment overrides
environments:
  staging:
    remotes:
      locktivity:
        target:
          environment: staging
          

Custom remote endpoints are declared with insecure_endpoint (and optionally auth.insecure_endpoint). The insecure_ prefix serves as explicit acknowledgment. epack validates these values, blocks them in strict production mode, and passes them to the adapter as trusted explicit env.

Profiles Configuration

Profiles define compliance requirements for validation. They can be sourced from the registry or from local files. Overlays customize profiles for specific environments.

epack.yaml

            # Registry-sourced profile with version pinning
profiles:
  - source: locktivity/soc2-basic@v1

# Local profile file
profiles:
  - path: profiles/custom-policy.yaml

# Overlays modify profiles for specific environments
overlays:
  - path: profiles/overlays/production.yaml
  - path: profiles/overlays/us-region.yaml
          

Profile fields

Field	Type	Description
`source`	string	Registry reference (`owner/repo@version`). Mutually exclusive with `path`.
`path`	string	Local file path relative to project root. Mutually exclusive with `source`.

Overlay fields

Field	Type	Description
`source`	string	Registry reference (`owner/repo@version`). Mutually exclusive with `path`.
`path`	string	Local file path relative to project root. Mutually exclusive with `source`.

Note: Profile and overlay digests are tracked in the manifest for reproducibility. Registry-sourced profiles are version-locked in epack.lock.

Remotes Configuration

Remotes define destinations where packs can be pushed. Each remote uses an adapter that implements the Remote Adapter Protocol. See Remotes concept for details.

epack.yaml

            remotes:
  # Managed remote - adapter installed via source
  locktivity:
    source: locktivity/epack-remote-locktivity@^0.1.0
    target:
      workspace: myorg
      environment: prod
    insecure_endpoint: https://registry.example.com  # optional custom endpoint
    auth:
      mode: device_code     # optional manual auth preference
      profile: default       # optional auth profile name
    verify:
      pack: true            # verify pack before upload
      strict: true          # fail on warnings
    release:
      labels: [monthly, soc2]
      notes: "Monthly compliance release"
      source:               # source control metadata
        git:
          sha_env: GITHUB_SHA
          repo_env: GITHUB_REPOSITORY
        ci:
          run_url_env: GITHUB_RUN_URL
    runs:
      sync: true             # sync run ledgers after push
      paths:                 # paths to search for runs
        - tools/**/result.json
        - runs/**/result.json
      require_success: false # fail push if run sync fails

  # External adapter - explicit absolute binary path
  s3:
    binary: /usr/local/bin/epack-remote-s3
    adapter: s3             # optional when not inferable from binary/source
    target:
      bucket: my-evidence-bucket
      prefix: packs/
    runs:
      sync: false
          

Remote 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
`endpoint`	string	Optional endpoint URL override
`auth`	object	Optional adapter-specific authentication preferences for manual flows
`secrets`	[]string	Environment variable names to pass through to the adapter
`credentials`	[]string	Managed credential refs that resolve through top-level `credential_sets`
`verify`	object	Pre-push verification (`pack`, `strict`)
`release`	object	Release metadata (`labels`, `notes`, `source`)
`runs`	object	Run sync settings (`sync`, `paths`, `require_success`)

Common adapter auth modes

Authentication modes are adapter-defined. These are common examples reported by current adapters:

Mode	Description	Use Case
`access_token`	Pre-resolved bearer token injected by the runtime	Managed runners and the Locktivity broker
`device_code`	Interactive browser-based login	Local development
`client_credentials`	Client ID and secret supplied directly to the adapter	Manual CI or service-to-service access

Environments

Use the environments: section to override settings for different deployment environments. Overrides are applied with --env <name> flag.

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]
  prod:
    remotes:
      locktivity:
        release:
          labels: [prod, soc2]
          

Terminal

            # Push using staging environment config
epack push locktivity evidence.epack --env staging

# Push using prod environment config
epack push locktivity evidence.epack --env prod
          

Configuration Schema

Top-level fields

Field	Type	Description
`stream`	string required	Evidence stream identifier (e.g., `myorg/prod`)
`output`	string	Output pack path (e.g., `evidence.epack`)
`platforms`	[]string	Target platforms for lockfile (e.g., `linux/amd64`)
`credential_sets`	map[string]string	Logical credential refs mapped to opaque broker-issued IDs
`collectors`	map[string]Collector	Collector definitions (Full Edition)
`tools`	map[string]Tool	Tool definitions (Full Edition)
`remotes`	map[string]Remote	Remote registry definitions (Full Edition)
`environments`	map[string]Environment	Per-environment config overrides (Full Edition)

Collector/Tool fields

Field	Type	Description
`source`	string required	Source reference (e.g., `owner/repo@version`)
`config`	map[string]any	Collector/tool-specific configuration
`secrets`	[]string	Environment variable names to pass as secrets
`credentials`	[]string	Managed credential refs that resolve through top-level `credential_sets`

Secrets vs. credentials: Use secrets for direct environment pass-through. Use credentials when a trusted runtime or broker resolves short-lived env bundles for the component.

Global CLI Flags

These flags apply to all commands:

Flag	Description
`-q`, `--quiet`	Suppress non-essential output
`--json`	Output in JSON format
`--no-color`	Disable colored output
`-v`, `--verbose`	Enable verbose output
`--no-redact`	Disable redaction of secrets in errors/logs
`--ci`	CI mode: disable spinners, add timestamps (auto-detected from CI/GITHUB_ACTIONS env)
`-h`, `--help`	Show help
`epack version`	Show version information