Honeydipper uses environment variables for bootstrap configuration, authentication, and runtime behavior. This document provides a comprehensive reference for all supported environment variables.
These variables control how Honeydipper loads its initial configuration.
| Variable | Required | Default | Description |
|---|---|---|---|
REPO |
Yes | — | Bootstrap configuration repository URL. Can be a git URL or a local directory path. |
BRANCH |
No | master |
Branch to use in the bootstrap repository. |
BOOTSTRAP_PATH |
No | / |
Path within the repository from which to load the init file. |
BOOTSTRAP_FILE |
No | init.yaml |
Custom init file name. Overrides the default init.yaml. |
JOB_FILE |
Job mode only | — | Path to a workflow file. Required when running Honeydipper in job mode. |
Standard bootstrap from a git repo:
export REPO="git@github.com:myorg/honeydipper-config.git"
export BRANCH="production"
export BOOTSTRAP_PATH="/configs"
export BOOTSTRAP_FILE="init.yaml"
Bootstrap from a local directory:
export REPO="/path/to/local/config"
export BRANCH="main"
Job mode:
export REPO="git@github.com:myorg/honeydipper-config.git"
export JOB_FILE="workflows/nightly-cleanup.yaml"
These variables configure how Honeydipper authenticates with git repositories when cloning or pulling configuration.
| Variable | Description |
|---|---|
DIPPER_GIT_PASS |
Default password for git HTTP authentication. Used when no username-specific variable is set. |
DIPPER_GIT_PASS_{USERNAME} |
Username-specific password. The username is uppercased and hyphens are replaced with underscores. For example, for username deploy-bot, use DIPPER_GIT_PASS_DEPLOY_BOT. |
Priority order for HTTP auth:
DIPPER_GIT_PASS_{USERNAME} (username-specific)DIPPER_GIT_PASS (fallback)| Variable | Description |
|---|---|
DIPPER_SSH_KEY |
Raw SSH private key content (PEM format). Takes precedence over key file. |
DIPPER_SSH_KEYFILE |
Path to the SSH private key file. |
DIPPER_SSH_PASS |
Passphrase for the SSH private key. |
SSH_AUTH_SOCK |
SSH agent socket path. If set, the SSH agent is used for authentication. |
Priority order for SSH auth:
SSH_AUTH_SOCK (SSH agent)DIPPER_SSH_KEY (inline key)DIPPER_SSH_KEYFILE (key file)HTTP with username-specific password:
export DIPPER_GIT_PASS_DEPLOY_BOT="ghp_xxxxxxxxxxxx"
SSH with inline key:
export DIPPER_SSH_KEY="$(cat ~/.ssh/id_ed25519)"
export DIPPER_SSH_PASS="my-passphrase"
SSH with agent:
export SSH_AUTH_SOCK="$SSH_AUTH_SOCK"
These variables configure the HTTP API server’s JWT signing.
| Variable | Required | Description |
|---|---|---|
HD_JWT_SIGNING_KEY |
For JWT | Secret key used to sign JWT tokens. Must be a secure, random string. |
HD_JWT_ISSUER |
No | JWT issuer claim. Identifies the entity issuing the token. |
HD_UI_URL |
No | Base URL of the Honeydipper UI. Used for constructing redirect URLs after SAML/OAuth authentication. Can also be set in config as daemon.services.api.ui_url. |
HD_SECRET_DRIVER |
No | Name of the secret driver to use (e.g., vault). Overrides the default secret driver configuration. |
export HD_JWT_SIGNING_KEY="your-256-bit-secret-key-here"
export HD_JWT_ISSUER="honeydipper-prod"
export HD_UI_URL="https://honeydipper.example.com"
These variables control where Honeydipper finds and caches drivers.
| Variable | Default | Description |
|---|---|---|
HONEYDIPPER_DRIVERS_BUILTIN |
$GOPATH/bin or /opt/honeydipper/driver/builtin |
Path to the built-in driver directory. |
HONEYDIPPER_DRIVERS_CACHE |
/opt/honeydipper/drivers/cache |
Path where remote drivers are cached after download. |
HONEYDIPPER_REMOTE_REQUIRE_SIGNATURE |
(not set) | When set to any value, enforces Ed25519 signature verification for remote driver packages. |
Built-in drivers:
$HONEYDIPPER_DRIVERS_BUILTIN$GOPATH/bin/opt/honeydipper/driver/builtinRemote driver cache:
$HONEYDIPPER_DRIVERS_CACHE/opt/honeydipper/drivers/cacheexport HONEYDIPPER_DRIVERS_BUILTIN="/opt/honeydipper/drivers/builtin"
export HONEYDIPPER_DRIVERS_CACHE="/opt/honeydipper/drivers/cache"
export HONEYDIPPER_REMOTE_REQUIRE_SIGNATURE="true"
These variables allow overriding repository URLs at runtime without modifying the configuration.
| Variable | Format | Description |
|---|---|---|
REPO_OVERRIDE |
<remote_url>=<local_path> |
Override a single repository. |
REPO_OVERRIDE_<NAME> |
<remote_url>=<local_path> |
Named override. <NAME> can be any identifier. |
The format is: <remote_url>=<local_path>. Both sides are trimmed of whitespace.
Single override:
export REPO_OVERRIDE="git@github.com:myorg/config.git=/local/path/to/config"
Multiple overrides:
export REPO_OVERRIDE_MAIN="git@github.com:myorg/main-config.git=/local/main"
export REPO_OVERRIDE_SHARED="git@github.com:myorg/shared-config.git=/local/shared"
These variables configure GitHub App-based authentication for accessing GitHub repositories.
| Variable | Description |
|---|---|
GH_APP_ID |
GitHub App ID. |
GH_APP_INSTALLATION_ID |
Installation ID for the GitHub App. |
GH_APP_KEY |
Private key for the GitHub App (PEM format). |
When these are set, Honeydipper uses the GitHub App to generate access tokens for repository operations instead of personal access tokens.
export GH_APP_ID="123456"
export GH_APP_INSTALLATION_ID="78901234"
export GH_APP_KEY="$(cat github-app-private-key.pem)"
| Variable | Category | Required | Default |
|---|---|---|---|
REPO |
Bootstrap | Yes | — |
BRANCH |
Bootstrap | No | master |
BOOTSTRAP_PATH |
Bootstrap | No | / |
BOOTSTRAP_FILE |
Bootstrap | No | init.yaml |
JOB_FILE |
Bootstrap | Job mode | — |
DIPPER_GIT_PASS |
Git Auth | No | — |
DIPPER_GIT_PASS_{USERNAME} |
Git Auth | No | — |
DIPPER_SSH_KEY |
Git Auth (SSH) | No | — |
DIPPER_SSH_KEYFILE |
Git Auth (SSH) | No | — |
DIPPER_SSH_PASS |
Git Auth (SSH) | No | — |
SSH_AUTH_SOCK |
Git Auth (SSH) | No | — |
GH_APP_ID |
GitHub App | No | — |
GH_APP_INSTALLATION_ID |
GitHub App | No | — |
GH_APP_KEY |
GitHub App | No | — |
HD_JWT_SIGNING_KEY |
API/JWT | For JWT | — |
HD_JWT_ISSUER |
API/JWT | No | — |
HD_UI_URL |
API/JWT | No | — |
HD_SECRET_DRIVER |
API | No | — |
HONEYDIPPER_DRIVERS_BUILTIN |
Drivers | No | $GOPATH/bin |
HONEYDIPPER_DRIVERS_CACHE |
Drivers | No | /opt/honeydipper/drivers/cache |
HONEYDIPPER_REMOTE_REQUIRE_SIGNATURE |
Drivers | No | (disabled) |
REPO_OVERRIDE |
Repo Override | No | — |
REPO_OVERRIDE_* |
Repo Override | No | — |