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_SIGNING_KEY`	Path to a PEM private key a run signs in to the credential broker with when the runner has no identity of its own. A GitHub Actions OIDC token or a GitLab ID token is used first. `epack run --key` sets it to the key the run signs with. Used with `EPACK_PIPELINE_ID`.	—

Runs (Full Edition)

Variable	Description	Default
`EPACK_CHECK`	Set to `1` to make `epack run` a check: it signs in, verifies the lock, secrets, credentials, and publishers, reports the result, and collects nothing. Same as `--check`.	—
`EPACK_PIPELINE_ID`	The configuration a run belongs to. A run that signs in with `EPACK_SIGNING_KEY` names its configuration with it, and stored secrets are scoped by it. A job with no folder that runs a configuration by name signs in for it with the job's GitLab ID token or the key.	—
`EPACK_TRUSTED_PUBLISHERS`	Comma-separated GitHub owners trusted for this process. A configuration fetched from a remote may only run collectors, tools, and remote adapters from trusted publishers. Same as `--trust-publisher`.	—

Output & Logging

Variable	Description	Default
`NO_COLOR`	Disable colored output. Set to any non-empty value.	—
`EPACK_NO_UPDATE_NOTIFIER`	Turn off the daily check for a newer epack release. Set to any non-empty value. The check runs only at a terminal and never in CI mode.	—

For more detail, pass -v or --verbose; for machine-readable output, pass --json. See Global CLI Flags.

Paths & Caching

Path	Contents
`~/.epack/update-check.json`	When epack last checked for a newer release and what it found, readable only by you
`~/.epack/config.yaml`	Your user settings: the default remote and the publishers you trust
`~/.epack/keys/`	Signing keys from `epack key create`, readable only by you
`~/.epack/remotes.lock`, `~/.epack/utilities.lock`	Pins for the remote adapters and utilities installed for you
`.epack/` in a project	The project's installed collectors, tools, and remotes, and its hooks
`$XDG_CACHE_HOME/epack`	The component catalog cache. Defaults to `~/.cache/epack`, or `%LOCALAPPDATA%\epack\cache` on Windows

Collectors (Full Edition)

Variable	Description	Default
`GITHUB_TOKEN`	GitHub API token for the GitHub collector (classic PAT or short-lived installation token).	—
`EPACK_PARALLEL`	Maximum concurrent collector runs for `collect` and `collector run`: `0` picks automatically, `1` runs them one at a time. Same as `--parallel`.	`0`
`EPACK_COLLECTOR_OUTPUT_DIR`	Runner-provided staging directory for collector file artifacts.	Set per collector run

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.2.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@^0.2.0
    config:
      level: audit     # trust | audit | internal; defaults to trust
      regions:
        - us-east-1
        - us-west-2
    secrets:
      - AWS_ACCESS_KEY_ID
      - AWS_SECRET_ACCESS_KEY
      - name: AWS_REGION
        optional: true   # passed through when set, never required

# 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

# Control mappings link evidence to profile requirements
mappings:
  - path: mappings/control-mappings.yaml

# Remotes configuration
remotes:
  locktivity:
    source: locktivity/epack-remote-locktivity@^0.2.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. An adapter installed for the user, outside a project, takes the same overrides from EPACK_INSECURE_REMOTE_ENDPOINT and EPACK_INSECURE_REMOTE_AUTH_ENDPOINT.

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.

Control Mappings Configuration

Control mappings record which evidence in a pack supports which profile requirement (evidencepack/control-mapping@v1). They are publisher assertions: content problems surface as build warnings, never failures, and mappings never affect verification or validation results.

epack.yaml

            # Control mappings are always local files
mappings:
  - path: mappings/control-mappings.yaml
          

Mapping fields

Field	Type	Description
`path`	string	Local file path relative to project root. Mappings describe this publisher's evidence and are never fetched from a registry.

Note: Each mapping file is locked by digest in epack.lock.yaml, verified under --frozen, and sealed into built packs as artifacts/<name>.json with YAML input emitted as deterministic JSON.

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.2.0
    target:
      workspace: myorg
      environment: prod
    insecure_endpoint: https://registry.example.com  # optional custom endpoint
    auth:
      mode: browser         # 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 \| object	Environment variables to pass through to the adapter. A bare name is required: `epack run --check` reports it when unset. `{name: X, optional: true}` is passed through only when set
`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
`browser`	Browser sign-in with `epack remote login`; the browser returns to epack on this machine	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.2.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 \| object	Environment variables to pass as secrets. A bare name is required: `epack run --check` reports it when not ready. `{name: X, optional: true}` is passed through only when set. Values come from the environment first, then from the keychain a laptop filled with `epack secret set`
`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, GITLAB_CI, CODEBUILD_BUILD_ID, JENKINS_URL, BUILDKITE, or TF_BUILD env)
`-h`, `--help`	Show help
`epack version`	Show version information