Pipedash
Configuration

Configuration

Where Pipedash finds config.toml, every TOML key and environment variable with its default, variable interpolation and precedence.

Pipedash reads one TOML file, config.toml, and a small set of environment variables. This page lists where the file lives, every key in it, every variable Pipedash reads, and which source wins.

Config file discovery

Pipedash picks the first match.

  1. PIPEDASH_CONFIG_PATH, used as given even when the file does not exist.
  2. In desktop mode, <platform config dir>/pipedash/config.toml when it exists.
  3. In server mode, /etc/pipedash/config.toml when it exists.
  4. config.toml inside the default data directory.

The default data directory is PIPEDASH_DATA_DIR when set. Otherwise it is the platform data directory plus pipedash, or .pipedash when the platform has none. The storage.data_dir key does not take part in discovery.

The desktop app sets PIPEDASH_CONFIG_PATH to <app data dir>/config.toml at startup. On first launch it writes a starter file there with data_dir filled in and default_refresh_interval = 300. In server mode, Pipedash creates a missing file with bind_addr = "0.0.0.0:8080" and data_dir = "./data".

Server mode detection

Pipedash runs in server mode when any one of these is true. Otherwise it runs in desktop mode.

SignalTest
PIPEDASH_SERVER_MODESet to any value
PIPEDASH_API_MODESet to any value
KUBERNETES_SERVICE_HOSTSet to any value
DOCKER_CONTAINERSet to any value
PIPEDASH_DATA_DIRValue starts with /data or /var

The mode changes the discovery path above and the defaults of a newly created file.

TOML reference

All sections are optional. Missing keys take the defaults below.

[general]
metrics_enabled = true
default_refresh_interval = 30

[server]
bind_addr = "127.0.0.1:8080"
cors_allow_all = true

[storage]
backend = "sqlite"

[providers.github-work]
name = "GitHub Work"
type = "github"
token = "${GITHUB_TOKEN}"
refresh_interval = 30

[providers.github-work.config]
selected_items = "hcavarsan/pipedash"

general

KeyTypeDefaultEffect
metrics_enabledbooleantrueStarts the metrics service. Collection also needs the database switch. See Metrics.
default_refresh_intervalinteger, seconds30Saved with the file. The current version does not use it to schedule polling.

server

KeyTypeDefaultEffect
bind_addrstring127.0.0.1:8080Saved, but the web server does not read it.
cors_allow_allbooleantrueSaved, but the web server does not read it.

The web server reads PIPEDASH_BIND_ADDR and PIPEDASH_CORS_ALLOW_ALL instead, with different defaults. See the variable table below.

storage

KeyTypeDefaultEffect
data_dirstringEmptyDirectory for pipedash.db and local files. Empty means the default data directory. Pipedash omits an empty value when it saves.
backendsqlite or postgressqliteStorage backend. See Storage backends.
vault_passwordstringNonePassword for encrypted tokens. Pipedash reads it and never writes it back. It wins over PIPEDASH_VAULT_PASSWORD.

storage.postgres

KeyTypeDefaultEffect
connection_stringstringEmptyPostgreSQL URL. Required when backend = "postgres". Pipedash omits an empty value when it saves.

providers.<id>

Each table key is a provider id. Pipedash stores it as the provider name and matches on it during sync.

KeyTypeDefaultEffect
namestringTable keyDisplay name shown in the UI.
typestringRequiredOne of github, gitlab, bitbucket, buildkite, jenkins, tekton, argocd. An unknown type logs a warning.
tokenstringEmptyA token reference. Empty means Pipedash looks the token up in secure storage by provider id.
refresh_intervalinteger, seconds30Saved per provider. The current version does not use it to schedule polling. See Refresh.

providers.<id>.config

A table of string values. The keys depend on the provider type, for example base_url and selected_items. selected_items is a comma-separated list of repositories or pipelines. See Providers for the keys of each provider.

On startup Pipedash adds or updates providers from the file and keeps providers that exist only in the database.

Validation

Pipedash logs these checks at startup.

LevelCondition
Errorbackend = "postgres" with an empty connection_string
ErrorA provider with an empty type or an empty table key
WarningAn unknown provider type
WarningAn empty token, which means secure storage lookup
Warningrefresh_interval = 0, which means manual refresh only

Variable interpolation

Pipedash replaces variables in every string value after it parses the TOML.

SyntaxResult
${NAME}The value of NAME. If NAME is unset, loading fails with Required environment variable not found: NAME.
${NAME:-default}The value of NAME, or default when unset. The default can contain more variables.
${NAME:-}The value of NAME, or an empty string when unset.

Names match [A-Za-z_][A-Za-z0-9_]*. Nesting stops at 10 levels with Recursive interpolation limit exceeded.

Token references

The token key holds a reference to a secret.

FormMeaning
${VAR} or ${VAR:-x}Read the environment variable VAR
env:VARRead the environment variable VAR
An uppercase name such as GITHUB_TOKENRead that environment variable
keyring:nameLook up name in the keyring
storage:<id>Look up provider <id> in the token store
EmptyLook up the provider's own token in the token store

Pipedash rejects values that look like real tokens, such as the prefixes ghp_, github_pat_, glpat- and ATBB, with Plain-text tokens are not allowed in config. A sync can still store such a value as the token, so the file should hold references and no secrets.

Environment variables

VariableDefaultEffect
PIPEDASH_CONFIG_PATHDiscoveredPath of config.toml
PIPEDASH_DATA_DIRPlatform data dir + pipedashData directory when storage.data_dir is empty. Also a server mode signal.
PIPEDASH_SERVER_MODEUnsetAny value selects server mode
PIPEDASH_API_MODEUnsetAny value selects server mode
PIPEDASH_VAULT_PASSWORDNoneEncrypts tokens and doubles as the API bearer token. See Token storage.
PIPEDASH_BIND_ADDR127.0.0.1:8080Web server address. An invalid value stops the server at startup.
PIPEDASH_CORS_ALLOW_ALLfalsetrue or 1 allows any origin, method and header
PIPEDASH_EMBEDDED_FRONTENDtrueServes the frontend from the web server. Any value except true or 1 turns it off.
PIPEDASH_HTTP_POOL_SIZE10Idle connections kept per host in the provider HTTP client. An invalid value gives 10.
PIPEDASH_METRICS_ENABLEDUnsetMaps to general.metrics_enabled
PIPEDASH_DEFAULT_REFRESH_INTERVALUnsetMaps to general.default_refresh_interval
PIPEDASH_STORAGE_BACKENDUnsetMaps to storage.backend
PIPEDASH_POSTGRES_URLUnsetMaps to storage.postgres.connection_string
PIPEDASH_TOKEN_<provider_id>UnsetPer-provider token variable
KUBECONFIG~/.kube/configKubeconfig path for the Tekton provider
KUBERNETES_SERVICE_HOSTUnsetAny value selects server mode
DOCKER_CONTAINERUnsetAny value selects server mode

The current version does not read the 4 variables that map to config keys: PIPEDASH_METRICS_ENABLED, PIPEDASH_DEFAULT_REFRESH_INTERVAL, PIPEDASH_STORAGE_BACKEND and PIPEDASH_POSTGRES_URL. PIPEDASH_TOKEN_<provider_id> has no effect either. The TOML keys hold these settings, and ${VAR} interpolation or a token reference takes a value from the environment. A token reference such as ${GITHUB_TOKEN} can name any variable.

PIPEDASH_DB_PATH and PIPEDASH_METRICS_DB_PATH are not supported. storage.data_dir moves the database.

Precedence

Each setting has its own winner.

SettingWinner
Config pathPIPEDASH_CONFIG_PATH, then platform path, then data directory
Data directorystorage.data_dir, then PIPEDASH_DATA_DIR, then the platform directory
Bind address and CORSEnvironment only. The web server ignores the TOML keys.
Metrics servicegeneral.metrics_enabled from the file
Vault passwordstorage.vault_password, then PIPEDASH_VAULT_PASSWORD

Cache

The 3 caches Pipedash keeps, how Settings shows and clears them, and what a factory reset deletes.

Storage backends

SQLite and PostgreSQL storage, their files and the data directory, and how to test, validate and switch backends.