Custos

Configuration

Custos uses a hybrid configuration model:

  1. Gate Logic (*.gate.config.json): Defines what the gate does (URLs, conditions). Managed by engineers.
  2. Execution Context (Environment Variables): Defines how the tool runs (licensing, secrets, Git context). Managed by operators.

Environment variables follow two core principles: The Override Hierarchy and the "WHERE vs. WHAT" model for secrets.

Principle 1: The Override Hierarchy

The system uses a simple, predictable override protocol. For any given setting, the tool looks for variables in this order:

  1. Tool-Specific (CUSTOS_*): An environment variable starting with CUSTOS_ is the most specific and will always be used if present.
  2. Universal (3SC_*): If a CUSTOS_* variable is not found, the tool looks for a corresponding 3SC_* variable.
  3. Hard-coded Default: If neither is set, the tool falls back to a safe, built-in default value.

Principle 2: "WHERE vs. WHAT" for Secrets Management

This concept separates the connection to a vault from the secret being requested.

  • The "WHERE" (The Connection): These variables tell the tool where your secrets vault is and how to authenticate. You can define a global "WHERE" using 3SC_VAULT_* variables, and then override it for a specific task (like Git) using CUSTOS_GIT_VAULT_* variables.

  • The "WHAT" (The Secret Name): These variables tell the tool what specific secret to retrieve from the vault. For example, CUSTOS_GIT_PAT_SECRET_NAME tells the tool to ask the vault for the secret that holds the Git Personal Access Token.

The Golden Rule: If you define a "WHERE" for a task (either globally or with a scope-specific override), the tool will require you to provide the corresponding "WHAT".

Core Configuration

Variable (CUSTOS_*) Fallback (3SC_*) Required? Purpose
CUSTOS_CONFIG_NAME Yes The name of the configuration file to use (e.g., production for production.gate.config.json).
CUSTOS_LICENSE_SERVER_URL 3SC_LICENSE_SERVER_URL Yes The full URL of the 3SC License Server.
CUSTOS_LICENSE_TIMEOUT_SECONDS 3SC_LICENSE_TIMEOUT_SECONDS No Timeout in seconds for license server requests.
CUSTOS_LICENSE_RETRY_INTERVAL_SECONDS 3SC_LICENSE_RETRY_INTERVAL_SECONDS No Time in seconds to wait between license retry attempts.

Git Configuration

Variable (CUSTOS_*) Fallback (3SC_*) Required? Purpose
CUSTOS_GIT_REPO_URL 3SC_GIT_REPO_URL Conditional¹ The full HTTPS URL of the Git repository for remote clones.
CUSTOS_GIT_BRANCH 3SC_GIT_BRANCH No The specific branch to clone. Defaults to the remote's default.
CUSTOS_GIT_SUBDIRECTORY 3SC_GIT_SUBDIRECTORY No Path to a specific project within a monorepo to scope the operation.
CUSTOS_FORCE_UNSAFE_GIT_PUSH 3SC_FORCE_UNSAFE_GIT_PUSH No Must be true to allow git push from an unsafe CI environment.
CUSTOS_GIT_PAT 3SC_GIT_PAT Conditional² A Personal Access Token provided directly. (Not Recommended)
CUSTOS_GIT_PAT_SECRET_NAME Conditional³ The "WHAT": The name of the secret in a vault for the Git PAT.
CUSTOS_GIT_VAULT_TYPE 3SC_VAULT_TYPE No The scoped "WHERE": Overrides the Vault provider for Git operations only.
CUSTOS_GIT_VAULT_URL 3SC_VAULT_URL Conditional The scoped "WHERE": The endpoint for the vault used for the Git PAT.
CUSTOS_GIT_AZURE_CLIENT_ID 3SC_AZURE_CLIENT_ID Conditional The scoped "WHERE": Azure SP Client ID for the Git PAT vault.
CUSTOS_GIT_AZURE_CLIENT_SECRET 3SC_AZURE_CLIENT_SECRET Conditional The scoped "WHERE": Azure SP Client Secret for the Git PAT vault.
CUSTOS_GIT_AZURE_TENANT_ID 3SC_AZURE_TENANT_ID Conditional The scoped "WHERE": Azure Tenant ID for the Git PAT vault.
CUSTOS_GIT_AWS_ACCESS_KEY_ID 3SC_AWS_ACCESS_KEY_ID Conditional The scoped "WHERE": AWS Access Key ID for the Git PAT vault.
CUSTOS_GIT_AWS_SECRET_ACCESS_KEY 3SC_AWS_SECRET_ACCESS_KEY Conditional The scoped "WHERE": AWS Secret Access Key for the Git PAT vault.
CUSTOS_GIT_GOOGLE_APPLICATION_CREDENTIALS GOOGLE_APPLICATION_CREDENTIALS Conditional The scoped "WHERE": Path to GCP service account key for the Git PAT vault.
CUSTOS_GIT_VAULT_TOKEN 3SC_VAULT_TOKEN Conditional The scoped "WHERE": The HashiCorp Vault token for the Git PAT vault.

¹ Required only if the tool needs to perform a remote git clone to find the config file. ² Required for private repositories if not using a Vault. ³ Required for private repositories if CUSTOS_GIT_VAULT_TYPE or 3SC_VAULT_TYPE is set.

Observability (Firehose) Configuration

Variable (CUSTOS_*) Fallback (3SC_*) Required? Purpose
CUSTOS_LOG_ENDPOINT_URL 3SC_LOG_ENDPOINT_URL No The URL for the Firehose endpoint. Feature disabled if not set.
CUSTOS_LOG_ENDPOINT_TOKEN 3SC_LOG_ENDPOINT_TOKEN Conditional¹ A direct authentication token for the endpoint.
CUSTOS_LOG_ENDPOINT_TOKEN_SECRET_NAME Conditional² The "WHAT": The name of the secret in a vault for the token.
CUSTOS_LOG_VAULT_TYPE 3SC_VAULT_TYPE No The scoped "WHERE": Overrides the Vault provider for Logging operations only.
CUSTOS_LOG_VAULT_URL 3SC_VAULT_URL Conditional The scoped "WHERE": The endpoint for the vault used for the Firehose token.
CUSTOS_LOG_AZURE_CLIENT_ID 3SC_AZURE_CLIENT_ID Conditional The scoped "WHERE": Azure SP Client ID for the Firehose token vault.
CUSTOS_LOG_AZURE_CLIENT_SECRET 3SC_AZURE_CLIENT_SECRET Conditional The scoped "WHERE": Azure SP Client Secret for the Firehose token vault.
CUSTOS_LOG_AZURE_TENANT_ID 3SC_AZURE_TENANT_ID Conditional The scoped "WHERE": Azure Tenant ID for the Firehose token vault.
CUSTOS_LOG_AWS_ACCESS_KEY_ID 3SC_AWS_ACCESS_KEY_ID Conditional The scoped "WHERE": AWS Access Key ID for the Firehose token vault.
CUSTOS_LOG_AWS_SECRET_ACCESS_KEY 3SC_AWS_SECRET_ACCESS_KEY Conditional The scoped "WHERE": AWS Secret Access Key for the Firehose token vault.
CUSTOS_LOG_GOOGLE_APPLICATION_CREDENTIALS GOOGLE_APPLICATION_CREDENTIALS Conditional The scoped "WHERE": Path to GCP service account key for the Firehose token vault.
CUSTOS_LOG_VAULT_TOKEN 3SC_VAULT_TOKEN Conditional The scoped "WHERE": The HashiCorp Vault token for the Firehose token vault.

¹ Required if URL is set and not using a Vault. ² Required if URL is set and a Vault (CUSTOS_LOG_VAULT_TYPE or 3SC_VAULT_TYPE) is configured.

Control Point Configuration

Variable (CUSTOS_*) Fallback (3SC_*) Required? Purpose
CUSTOS_CP_BEFORE_DECISION_URL No Webhook invoked before the final gate decision is made. Feature disabled if not set.
CUSTOS_CP_WEBHOOK_TOKEN Conditional¹ A direct authentication token for all Control Point webhooks.
CUSTOS_CP_WEBHOOK_TOKEN_SECRET_NAME Conditional² The "WHAT": The name of the secret in a vault for the webhook token.
CUSTOS_CP_VAULT_TYPE 3SC_VAULT_TYPE No The scoped "WHERE": Overrides the Vault provider for Control Point operations only.
CUSTOS_CP_VAULT_URL 3SC_VAULT_URL Conditional The scoped "WHERE": The endpoint for the vault used for the Control Point token.
CUSTOS_CP_AZURE_CLIENT_ID 3SC_AZURE_CLIENT_ID Conditional The scoped "WHERE": Azure SP Client ID for the Control Point token vault.
CUSTOS_CP_AZURE_CLIENT_SECRET 3SC_AZURE_CLIENT_SECRET Conditional The scoped "WHERE": Azure SP Client Secret for the Control Point token vault.
CUSTOS_CP_AZURE_TENANT_ID 3SC_AZURE_TENANT_ID Conditional The scoped "WHERE": Azure Tenant ID for the Control Point token vault.
CUSTOS_CP_AWS_ACCESS_KEY_ID 3SC_AWS_ACCESS_KEY_ID Conditional The scoped "WHERE": AWS Access Key ID for the Control Point token vault.
CUSTOS_CP_AWS_SECRET_ACCESS_KEY 3SC_AWS_SECRET_ACCESS_KEY Conditional The scoped "WHERE": AWS Secret Access Key for the Control Point token vault.
CUSTOS_CP_GOOGLE_APPLICATION_CREDENTIALS GOOGLE_APPLICATION_CREDENTIALS Conditional The scoped "WHERE": Path to GCP service account key for the Control Point token vault.
CUSTOS_CP_VAULT_TOKEN 3SC_VAULT_TOKEN Conditional The scoped "WHERE": The HashiCorp Vault token for the Control Point token vault.

¹ Required if URL is set and not using a Vault. ² Required if URL is set and a Vault (CUSTOS_CP_VAULT_TYPE or 3SC_VAULT_TYPE) is configured.

Licensing & Degraded Mode

  • If a valid license cannot be acquired, Custos runs in a Degraded Mode.
  • In this mode, it will bypass all gate logic and immediately return a PASS (exit code 0), ensuring that licensing issues do not block your pipeline. A warning will be logged to the console.