Insipio

Configuration

Insipio is configured through a combination of a JSON configuration file and environment variables. Environment variables always take precedence over values set in the file.

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 (INSIPIO_*): An environment variable starting with INSIPIO_ is the most specific and will always be used if present.
  2. Universal (3SC_*): If an INSIPIO_* variable is not found, the tool looks for a corresponding 3SC_* variable.
  3. Value in insipio/config.json: If no environment variable is set, the tool uses the value from the configuration file.
  4. Hard-coded Default: If the setting is not present anywhere, the tool falls back to a safe, built-in default.

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 INSIPIO_GIT_VAULT_* variables.

  • The "WHAT" (The Secret Name): These variables tell the tool what specific secret to retrieve from the vault. For example, INSIPIO_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

These variables control the primary logic of the analysis engine.

Variable (INSIPIO_*) Fallback (3SC_*) Required? Purpose
INSIPIO_FROM No Overrides the fromCommit baseline defined in the config file.
INSIPIO_MODE No Overrides the analysis mode (e.g., Strict, Simulation, Standard).
INSIPIO_VALIDATE_ONLY No If true, runs the full analysis but does not push tags to Git.
INSIPIO_NO_OP 3SC_NO_OP No If true, the tool runs but performs no actions. Useful for disabling the tool in specific environments.
INSIPIO_LICENSE_SERVER_URL 3SC_LICENSE_SERVER_URL Yes The full URL of the 3SC License Server.
INSIPIO_LICENSE_TIMEOUT_SECONDS 3SC_LICENSE_TIMEOUT_SECONDS No Timeout in seconds for license server requests.
INSIPIO_LICENSE_RETRY_INTERVAL_SECONDS 3SC_LICENSE_RETRY_INTERVAL_SECONDS No Time in seconds to wait between license retry attempts.
INSIPIO_LOG_LEVEL 3SC_LOG_LEVEL No The logging level. Defaults to Information.

Tagging Configuration

These variables allow you to override the naming conventions for generated Git tags.

Variable (INSIPIO_*) Required? Purpose Example
INSIPIO_TAG_TEMPLATE No Template for the semantic version tag. v{0}.{1}.{2}
INSIPIO_MARKETING_TAG_TEMPLATE No Template for the marketing version tag. release-{0}.{1}
INSIPIO_START_TAG No The initial tag to apply if no tags exist. v0.0.0

Language Selection

You must explicitly enable the language analyzers relevant to your project. At least one must be set to true.

Variable (INSIPIO_*) Default Purpose
INSIPIO_LANGUAGE_CSHARP false Enable analysis for C# (.NET).
INSIPIO_LANGUAGE_JAVA false Enable analysis for Java.
INSIPIO_LANGUAGE_PYTHON false Enable analysis for Python.
INSIPIO_LANGUAGE_JAVASCRIPT false Enable analysis for JavaScript.
INSIPIO_LANGUAGE_TYPESCRIPT false Enable analysis for TypeScript.
INSIPIO_LANGUAGE_GO false Enable analysis for Go.
INSIPIO_LANGUAGE_CPP false Enable analysis for C++.
INSIPIO_LANGUAGE_RUST false Enable analysis for Rust.
INSIPIO_LANGUAGE_KOTLIN false Enable analysis for Kotlin.
INSIPIO_LANGUAGE_PHP false Enable analysis for PHP.
INSIPIO_LANGUAGE_DART false Enable analysis for Dart.
INSIPIO_LANGUAGE_RUBY false Enable analysis for Ruby.
INSIPIO_LANGUAGE_SWIFT false Enable analysis for Swift.

Git Configuration

Variable (INSIPIO_*) Fallback (3SC_*) Required? Purpose
INSIPIO_GIT_REPO_URL 3SC_GIT_REPO_URL Yes¹ The full HTTPS URL of the Git repository for remote clones.
INSIPIO_GIT_BRANCH 3SC_GIT_BRANCH Yes¹ The specific branch to clone and commit to.
INSIPIO_GIT_SUBDIRECTORY 3SC_GIT_SUBDIRECTORY No Path to a specific project within a monorepo to scope the operation.
INSIPIO_FORCE_UNSAFE_GIT_PUSH 3SC_FORCE_UNSAFE_GIT_PUSH No Must be set to true to allow git push from an unsafe CI environment.
INSIPIO_GIT_PAT 3SC_GIT_PAT Conditional² A Personal Access Token provided directly. (Not Recommended)
INSIPIO_GIT_PAT_SECRET_NAME Conditional³ The "WHAT": The name of the secret in a vault for the Git PAT.
INSIPIO_GIT_VAULT_TYPE 3SC_VAULT_TYPE No The scoped "WHERE": Overrides the Vault provider for Git operations only.
INSIPIO_GIT_VAULT_URL 3SC_VAULT_URL Conditional The scoped "WHERE": The endpoint for the vault used for the Git PAT.
INSIPIO_GIT_AZURE_CLIENT_ID 3SC_AZURE_CLIENT_ID Conditional The scoped "WHERE": Azure SP Client ID for the Git PAT vault.
INSIPIO_GIT_AZURE_CLIENT_SECRET 3SC_AZURE_CLIENT_SECRET Conditional The scoped "WHERE": Azure SP Client Secret for the Git PAT vault.
INSIPIO_GIT_AZURE_TENANT_ID 3SC_AZURE_TENANT_ID Conditional The scoped "WHERE": Azure Tenant ID for the Git PAT vault.
INSIPIO_GIT_AWS_ACCESS_KEY_ID 3SC_AWS_ACCESS_KEY_ID Conditional The scoped "WHERE": AWS Access Key ID for the Git PAT vault.
INSIPIO_GIT_AWS_SECRET_ACCESS_KEY 3SC_AWS_SECRET_ACCESS_KEY Conditional The scoped "WHERE": AWS Secret Access Key for the Git PAT vault.
INSIPIO_GIT_GOOGLE_APPLICATION_CREDENTIALS GOOGLE_APPLICATION_CREDENTIALS Conditional The scoped "WHERE": Path to GCP service account key for the Git PAT vault.
INSIPIO_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. ² Required for private repositories if not using a Vault. ³ Required for private repositories if INSIPIO_GIT_VAULT_TYPE or 3SC_VAULT_TYPE is set.

Observability (Firehose) Configuration

Variable (INSIPIO_*) Fallback (3SC_*) Required? Purpose
INSIPIO_LOG_ENDPOINT_URL 3SC_LOG_ENDPOINT_URL No The URL for the Firehose endpoint. Feature disabled if not set.
INSIPIO_LOG_ENDPOINT_TOKEN 3SC_LOG_ENDPOINT_TOKEN Conditional¹ A direct authentication token for the endpoint.
INSIPIO_LOG_ENDPOINT_TOKEN_SECRET_NAME Conditional² The "WHAT": The name of the secret in a vault for the token.
INSIPIO_LOG_VAULT_TYPE 3SC_VAULT_TYPE No The scoped "WHERE": Overrides the Vault provider for Logging operations only.
INSIPIO_LOG_VAULT_URL 3SC_VAULT_URL Conditional The scoped "WHERE": The endpoint for the vault used for the Firehose token.
INSIPIO_LOG_AZURE_CLIENT_ID 3SC_AZURE_CLIENT_ID Conditional The scoped "WHERE": Azure SP Client ID for the Firehose token vault.
INSIPIO_LOG_AZURE_CLIENT_SECRET 3SC_AZURE_CLIENT_SECRET Conditional The scoped "WHERE": Azure SP Client Secret for the Firehose token vault.
INSIPIO_LOG_AZURE_TENANT_ID 3SC_AZURE_TENANT_ID Conditional The scoped "WHERE": Azure Tenant ID for the Firehose token vault.
INSIPIO_LOG_AWS_ACCESS_KEY_ID 3SC_AWS_ACCESS_KEY_ID Conditional The scoped "WHERE": AWS Access Key ID for the Firehose token vault.
INSIPIO_LOG_AWS_SECRET_ACCESS_KEY 3SC_AWS_SECRET_ACCESS_KEY Conditional The scoped "WHERE": AWS Secret Access Key for the Firehose token vault.
INSIPIO_LOG_GOOGLE_APPLICATION_CREDENTIALS GOOGLE_APPLICATION_CREDENTIALS Conditional The scoped "WHERE": Path to GCP service account key for the Firehose token vault.
INSIPIO_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 (INSIPIO_LOG_VAULT_TYPE or 3SC_VAULT_TYPE) is configured.

Licensing & Degraded Mode

  • If a valid license cannot be acquired, Insipio runs in a Degraded Mode.
  • In this mode, it performs the full semantic analysis and logs its findings to the console, but it will not generate any artifacts or push any tags to your Git repository.