Configuration

Semaphore can be configured using several methods:

Online configurator — web interface for generating configuration online.
Configuration file — the primary and most flexible way to configure Semaphore.
Environment variables — useful for containerized or cloud-native deployments.

Configuration options

Full list of available configuration options:

Config file option / Environment variable	Description
Common
`git_client` `SEMAPHORE_GIT_CLIENT`	Type of Git client. Can be `cmd_git` (default) or `go_git`.
`ssh_config_path` `SEMAPHORE_SSH_PATH`	Path to custom SSH configuration file. Default: `~/.ssh/config`.
`port` `SEMAPHORE_PORT`	TCP port on which the web interface will be available. Default: `:3000`
`interface` `SEMAPHORE_INTERFACE`	Bind address (empty = all interfaces). Useful if your server has multiple network interfaces.
`tmp_path` `SEMAPHORE_TMP_PATH`	Path to directory where cloned repositories and generated files are stored. Default: /tmp/semaphore
`dirs.secrets` `SEMAPHORE_SECRETS_PATH`	Path to directory where secrets are stored. Default: /tmp/semaphore
`dirs.repos` `SEMAPHORE_REPOS_DIR`	Path to directory where repositories are stored.
`dirs.ssh_agent_sockets` `SEMAPHORE_SSH_AGENT_SOCKETS_DIR`	Path to directory where SSH agent sockets are stored. Default: /tmp/semaphore
`home_dir_mode` `SEMAPHORE_HOME_DIR_MODE`	Controls how the HOME environment variable is set for tasks. Options: `template_dir` (default), `project_home`, `user_home`.
`max_parallel_tasks` `SEMAPHORE_MAX_PARALLEL_TASKS`	Max number of parallel tasks that can be run on the server. Default: 9999
`max_task_duration_sec` `SEMAPHORE_MAX_TASK_DURATION_SEC`	Max duration of a task in seconds.
`max_tasks_per_template` `SEMAPHORE_MAX_TASKS_PER_TEMPLATE`	Maximum number of recent tasks stored in the database for each template.
`schedule.timezone` `SEMAPHORE_SCHEDULE_TIMEZONE`	Timezone used for scheduling tasks and cron jobs. Default: UTC
`oidc_providers` `SEMAPHORE_OIDC_PROVIDERS`	OpenID provider settings. You can provide multiple OpenID providers. More about OpenID configuration read in OpenID.
`password_login_disable` `SEMAPHORE_PASSWORD_LOGIN_DISABLED`	Deny password login.
`non_admin_can_create_project` `SEMAPHORE_NON_ADMIN_CAN_CREATE_PROJECT`	Allow non-admin users to create projects.
`env_vars` `SEMAPHORE_ENV_VARS`	JSON map which contains environment variables exposed to task runs.
`forwarded_env_vars` `SEMAPHORE_FORWARDED_ENV_VARS`	JSON array of host environment variables which will be forwarded into task runs.
`apps` `SEMAPHORE_APPS`	JSON map which contains apps configuration.
`use_remote_runner` `SEMAPHORE_USE_REMOTE_RUNNER`	Enable to use remote runner.
`runner_registration_token` `SEMAPHORE_RUNNER_REGISTRATION_TOKEN`	Bootstrap token used by runners to register with the server.
Subscription
`subscription.key` `SEMAPHORE_SUBSCRIPTION_KEY`	Subscription key or token. Disables activation from the web UI when set.
`subscription.key_file` `SEMAPHORE_SUBSCRIPTION_KEY_FILE`	Path to subscription key or token file.
`subscription.server_url` `SEMAPHORE_SUBSCRIPTION_SERVER_URL`	Subscription / billing server URL. Default: https://portal.semaphoreui.com/billing
JWT
`jwt.enabled` `SEMAPHORE_JWT_ENABLED`	When enabled, Semaphore mints a short-lived JWT for each task run and exposes its public key via `/.well-known/jwks.json`.
`jwt.issuer` `SEMAPHORE_JWT_ISSUER`	Value emitted in the `iss` claim of issued JWTs.
`jwt.default_ttl` `SEMAPHORE_JWT_DEFAULT_TTL`	Default lifetime of an issued task JWT, as a Go duration (e.g. `30m`, `1h`). Default: 1h
`jwt.max_ttl` `SEMAPHORE_JWT_MAX_TTL`	Hard upper bound on per-template JWT TTL, as a Go duration. Default: 24h
Runner
`runner.registration_token_file` `SEMAPHORE_RUNNER_REGISTRATION_TOKEN_FILE`	Path to file containing the runner registration token.
`runner.token` `SEMAPHORE_RUNNER_TOKEN`	Runner authentication token. Mutually exclusive with `runner.token_file`.
`runner.token_file` `SEMAPHORE_RUNNER_TOKEN_FILE`	Path to token file for runner registration.
`runner.private_key_file` `SEMAPHORE_RUNNER_PRIVATE_KEY_FILE`	Path to private key file for runner.
`runner.one_off` `SEMAPHORE_RUNNER_ONE_OFF`	Runner processes a single job and exits. Useful for dynamic runners.
`runner.enabled` `SEMAPHORE_RUNNER_ENABLED`	Enable the runner.
`runner.webhook` `SEMAPHORE_RUNNER_WEBHOOK`	Webhook URL for runner.
`runner.name` `SEMAPHORE_RUNNER_NAME`	Runner name.
`runner.tags` `SEMAPHORE_RUNNER_TAGS`	JSON array of runner tags.
`runner.max_parallel_tasks` `SEMAPHORE_RUNNER_MAX_PARALLEL_TASKS`	Max number of parallel tasks for the runner. Default: 9999.
`runner.project_id` `SEMAPHORE_RUNNER_PROJECT_ID`	Restrict the runner to a single project.
`runner.connection.server_ca_cert_file` `SEMAPHORE_RUNNER_SERVER_CA_CERT_FILE`	PEM bundle used to verify the Semaphore server certificate, in addition to the system trust store. Set when the server uses a self-signed or internal-CA certificate.
`runner.connection.skip_tls_verify` `SEMAPHORE_RUNNER_SKIP_TLS_VERIFY`	Disable server certificate verification entirely. Insecure (vulnerable to MITM) — use only for testing.
`runner.executor.type` —	Strategy the runner uses to execute each task: `local` (default), `k8s` or `docker`.
`runner.executor.k8s.kubeconfig` `SEMAPHORE_RUNNER_K8S_KUBECONFIG`	Path to a kubeconfig file. Empty = in-cluster configuration.
`runner.executor.k8s.namespace` `SEMAPHORE_RUNNER_K8S_NAMESPACE`	Namespace where ephemeral task Pods are created. Default: semaphore
`runner.executor.k8s.image` `SEMAPHORE_RUNNER_K8S_IMAGE`	Default container image for the build container. Default: semaphoreui/job:latest
`runner.executor.k8s.helper_image` `SEMAPHORE_RUNNER_K8S_HELPER_IMAGE`	Image used for the git-clone init container. Default: semaphoreui/helper:latest
`runner.executor.k8s.service_account` `SEMAPHORE_RUNNER_K8S_SERVICE_ACCOUNT`	Service account that task Pods run under. Default: default
`runner.executor.k8s.pull_secrets` `SEMAPHORE_RUNNER_K8S_PULL_SECRETS`	Comma-separated list of imagePullSecrets attached to each Pod.
`runner.executor.k8s.poll_interval_seconds` `SEMAPHORE_RUNNER_K8S_POLL_INTERVAL_SECONDS`	How often the executor polls Pod status, in seconds. Default: 3
`runner.executor.k8s.cleanup_grace_seconds` `SEMAPHORE_RUNNER_K8S_CLEANUP_GRACE_SECONDS`	Grace period when deleting Pods, in seconds. Default: 30
`runner.executor.docker.host` `SEMAPHORE_RUNNER_DOCKER_HOST`	Docker daemon URL (`unix://`, `tcp://` or `npipe://`). Empty = standard environment (`DOCKER_HOST`) and platform default socket.
`runner.executor.docker.tls_verify` `SEMAPHORE_RUNNER_DOCKER_TLS_VERIFY`	Enable TLS certificate verification for `tcp://` connections.
`runner.executor.docker.cert_path` `SEMAPHORE_RUNNER_DOCKER_CERT_PATH`	Directory holding ca.pem, cert.pem and key.pem for mutual TLS.
`runner.executor.docker.image` `SEMAPHORE_RUNNER_DOCKER_IMAGE`	Default image for the build container. Default: semaphoreui/job:latest
`runner.executor.docker.helper_image` `SEMAPHORE_RUNNER_DOCKER_HELPER_IMAGE`	Image used for the transient git-clone container. Default: semaphoreui/helper:latest
`runner.executor.docker.network` `SEMAPHORE_RUNNER_DOCKER_NETWORK`	Docker network the build container joins. Default: bridge
`runner.executor.docker.pull_policy` `SEMAPHORE_RUNNER_DOCKER_PULL_POLICY`	Image pull policy: `always`, `if-not-present` (default) or `never`.
`runner.executor.docker.cpu_limit` `SEMAPHORE_RUNNER_DOCKER_CPU_LIMIT`	When > 0, caps the build container CPU (passed as `--cpus`).
`runner.executor.docker.memory_limit` `SEMAPHORE_RUNNER_DOCKER_MEMORY_LIMIT`	When non-empty, caps the build container memory (e.g. `2g`).
`runner.executor.docker.poll_interval_seconds` `SEMAPHORE_RUNNER_DOCKER_POLL_INTERVAL_SECONDS`	How often container status is polled, in seconds. Default: 2
`runner.executor.docker.cleanup_grace_seconds` `SEMAPHORE_RUNNER_DOCKER_CLEANUP_GRACE_SECONDS`	Timeout passed to `docker stop`, in seconds. Default: 30
`runner.executor.docker.privileged` `SEMAPHORE_RUNNER_DOCKER_PRIVILEGED`	Run the build container with `--privileged`. Dangerous; off by default.
Runners (server-side fleet)
`runners.offline_timeout_sec` `SEMAPHORE_RUNNERS_OFFLINE_TIMEOUT_SEC`	Heartbeat staleness (seconds) after which a runner is considered offline. Its "starting" tasks are reassigned. Default: 120
`runners.task_fail_timeout_sec` `SEMAPHORE_RUNNERS_TASK_FAIL_TIMEOUT_SEC`	Heartbeat staleness (seconds) after which a runner's "running" tasks are failed. Values below `offline_timeout_sec` are clamped to it. Default: 420
`runners.reconcile_interval_sec` `SEMAPHORE_RUNNERS_RECONCILE_INTERVAL_SEC`	How often (seconds) dispatched tasks are reconciled against runner liveness. Default: 30
Teams
`teams.invites_enabled` `SEMAPHORE_TEAMS_INVITES_ENABLED`	Allow users to invite members to teams.
`teams.invite_type` `SEMAPHORE_TEAMS_INVITE_TYPE`	Type of invite: `username` (default), `email`, `both`.
`teams.members_can_leave` `SEMAPHORE_TEAMS_MEMBERS_CAN_LEAVE`	Allow members to leave teams.
Database
`sqlite.host` `SEMAPHORE_DB_HOST`	Path to the SQLite database file.
`mysql.host` `SEMAPHORE_DB_HOST`	MySQL database host.
`mysql.name` `SEMAPHORE_DB_NAME`	MySQL database (schema) name.
`mysql.user` `SEMAPHORE_DB_USER`	MySQL user name.
`mysql.pass` `SEMAPHORE_DB_PASS`	MySQL user's password.
`postgres.host` `SEMAPHORE_DB_HOST`	Postgres database host.
`postgres.name` `SEMAPHORE_DB_NAME`	Postgres database (schema) name.
`postgres.user` `SEMAPHORE_DB_USER`	Postgres user name.
`postgres.pass` `SEMAPHORE_DB_PASS`	Postgres user's password.
`dialect` `SEMAPHORE_DB_DIALECT`	Can be `sqlite` (default), `postgres` or `mysql`.
`*.options` `SEMAPHORE_DB_OPTIONS`	JSON map which contains database connection options.
Security
`access_key_encryption` `SEMAPHORE_ACCESS_KEY_ENCRYPTION`	Base64-encoded key used for encrypting access keys stored in the database. Read more in Database encryption reference.
`option_encryption` `SEMAPHORE_OPTION_ENCRYPTION`	Base64-encoded key used to encrypt DB options (the JWT signing key) with the old single-key scheme (no rotation). Falls back to the access key when unset.
`cookie_hash` `SEMAPHORE_COOKIE_HASH`	Base64-encoded HMAC key used to sign cookies.
`cookie_encryption` `SEMAPHORE_COOKIE_ENCRYPTION`	Base64-encoded key used to encrypt cookies.
`web_host` `SEMAPHORE_WEB_ROOT`	Can be useful if you want to use Semaphore by the subpath, for example: http://yourdomain.com/semaphore. Do not add a trailing `/`.
`tls.enabled` `SEMAPHORE_TLS_ENABLED`	Enable or disable TLS (HTTPS) for secure communication with the Semaphore server.
`tls.cert_file` `SEMAPHORE_TLS_CERT_FILE`	Path to TLS certificate file.
`tls.key_file` `SEMAPHORE_TLS_KEY_FILE`	Path to TLS key file.
`tls.http_redirect_addr` `SEMAPHORE_TLS_HTTP_REDIRECT_ADDR`	Address (`host[:port]`) for the HTTP→HTTPS redirect listener. Mutually exclusive with `tls.http_redirect_port`.
`tls.http_redirect_port` `SEMAPHORE_TLS_HTTP_REDIRECT_PORT`	Port to redirect HTTP traffic to HTTPS. Mutually exclusive with `tls.http_redirect_addr`.
`mfa.totp.enabled` `SEMAPHORE_TOTP_ENABLED`	Enable Two-factor authentication using TOTP.
`mfa.totp.app_name` `SEMAPHORE_TOTP_ISSUER`	Issuer label (Semaphore title) shown in TOTP authenticator apps.
`mfa.totp.allow_recovery` `SEMAPHORE_TOTP_ALLOW_RECOVERY`	Allow users to reset TOTP using a recovery code.
`mfa.email.enabled` `SEMAPHORE_EMAIL_2TP_ENABLED`	Enable email-based multi-factor authentication.
`mfa.email.allow_login_as_external_user` `SEMAPHORE_EMAIL_2TP_ALLOW_LOGIN_AS_EXTERNAL_USER`	Allow login as an external (email-only) user.
`mfa.email.allow_create_external_user` `SEMAPHORE_EMAIL_2TP_ALLOW_CREATE_EXTERNAL_USER`	Allow creating external users on first login.
`mfa.email.allowed_domains` `SEMAPHORE_EMAIL_2TP_ALLOWED_DOMAINS`	JSON array of allowed email domains.
`mfa.email.disable_for_oidc` `SEMAPHORE_EMAIL_2TP_DISABLE_FOR_OIDC`	Disable email MFA for users authenticated via OIDC.
Encryption
`encryption.keys_file` `SEMAPHORE_ENCRYPTION_KEYS_FILE`	Path to a separate file holding the encryption keyrings (YAML or JSON). Watched for changes — edits are applied without restarting the server. When unset, the legacy `access_key_encryption` field is used.
`encryption.keys_poll_interval` `SEMAPHORE_ENCRYPTION_KEYS_POLL_INTERVAL`	How often `keys_file` is polled for changes (a Go duration like `15s`). `0` disables polling (a SIGHUP still forces a reload). Default: 15s
Process
`process.user` `SEMAPHORE_PROCESS_USER`	User under which wrapped processes (such as Ansible, Terraform, or OpenTofu) will run.
`process.uid` `SEMAPHORE_PROCESS_UID`	ID of user under which wrapped processes (such as Ansible, Terraform, or OpenTofu) will run.
`process.gid` `SEMAPHORE_PROCESS_GID`	ID for group under which wrapped processes (such as Ansible, Terraform, or OpenTofu) will run.
`process.chroot` `SEMAPHORE_PROCESS_CHROOT`	Chroot directory for wrapped processes.
`process.no_new_privs` `SEMAPHORE_PROCESS_NO_NEW_PRIVS`	Set the `no_new_privs` flag so wrapped processes cannot gain new privileges.
`process.app_namespaces.user` `SEMAPHORE_PROCESS_APP_NS_USER`	Isolate UIDs/GIDs (`CLONE_NEWUSER`) for app runs. Linux only.
`process.app_namespaces.mount` `SEMAPHORE_PROCESS_APP_NS_MOUNT`	Hide host mount points such as secret tmpfs (`CLONE_NEWNS`) for app runs. Linux only.
`process.app_namespaces.pid` `SEMAPHORE_PROCESS_APP_NS_PID`	Hide host processes from app runs (`CLONE_NEWPID`). Linux only.
`process.app_namespaces.ipc` `SEMAPHORE_PROCESS_APP_NS_IPC`	Isolate SysV IPC and POSIX message queues (`CLONE_NEWIPC`) for app runs. Linux only.
`process.app_namespaces.uts` `SEMAPHORE_PROCESS_APP_NS_UTS`	Isolate hostname and domain (`CLONE_NEWUTS`) for app runs. Linux only.
Email
`email_sender` `SEMAPHORE_EMAIL_SENDER`	Email address of the sender.
`email_host` `SEMAPHORE_EMAIL_HOST`	SMTP server hostname.
`email_port` `SEMAPHORE_EMAIL_PORT`	SMTP server port.
`email_secure` `SEMAPHORE_EMAIL_SECURE`	Enable StartTLS to upgrade an unencrypted SMTP connection to a secure, encrypted one.
`email_tls` `SEMAPHORE_EMAIL_TLS`	Use SSL or TLS connection for communication with the SMTP server.
`email_tls_min_version` `SEMAPHORE_EMAIL_TLS_MIN_VERSION`	Minimum TLS version to use for the connection.
`email_username` `SEMAPHORE_EMAIL_USERNAME`	Username for SMTP server authentication.
`email_password` `SEMAPHORE_EMAIL_PASSWORD`	Password for SMTP server authentication.
`email_alert` `SEMAPHORE_EMAIL_ALERT`	Flag which enables email alerts.
Messengers
`telegram_alert` `SEMAPHORE_TELEGRAM_ALERT`	Set to True to enable pushing alerts to Telegram. It should be used in combination with `telegram_chat` and `telegram_token`.
`telegram_chat` `SEMAPHORE_TELEGRAM_CHAT`	Set to the Chat ID for the chat to send alerts to. Read more in Telegram Notifications Setup
`telegram_token` `SEMAPHORE_TELEGRAM_TOKEN`	Set to the Authorization Token for the bot that will receive the alert payload. Read more in Telegram Notifications Setup
`slack_alert` `SEMAPHORE_SLACK_ALERT`	Set to True to enable pushing alerts to slack. It should be used in combination with `slack_url`
`slack_url` `SEMAPHORE_SLACK_URL`	The slack webhook url. Semaphore will used it to POST Slack formatted json alerts to the provided url.
`microsoft_teams_alert` `SEMAPHORE_MICROSOFT_TEAMS_ALERT`	Flag which enables Microsoft Teams alerts.
`microsoft_teams_url` `SEMAPHORE_MICROSOFT_TEAMS_URL`	Microsoft Teams webhook URL.
`rocketchat_alert` `SEMAPHORE_ROCKETCHAT_ALERT`	Set to True to enable pushing alerts to Rocket.Chat. It should be used in combination with `rocketchat_url`. Available since v2.9.56.
`rocketchat_url` `SEMAPHORE_ROCKETCHAT_URL`	The rocketchat webhook url. Semaphore will used it to POST Rocket.Chat formatted json alerts to the provided url. Available since v2.9.56.
`dingtalk_alert` `SEMAPHORE_DINGTALK_ALERT`	Enable Dingtalk alerts.
`dingtalk_url` `SEMAPHORE_DINGTALK_URL`	Dingtalk messenger webhook URL.
`gotify_alert` `SEMAPHORE_GOTIFY_ALERT`	Enable Gotify alerts.
`gotify_url` `SEMAPHORE_GOTIFY_URL`	Gotify server URL.
`gotify_token` `SEMAPHORE_GOTIFY_TOKEN`	Gotify server token.
LDAP
`ldap_enable` `SEMAPHORE_LDAP_ENABLE`	Flag which enables LDAP authentication.
`ldap_needtls` `SEMAPHORE_LDAP_NEEDTLS`	Flag to enable or disable TLS for LDAP connections.
`ldap_binddn` `SEMAPHORE_LDAP_BIND_DN`	The distinguished name (DN) used to bind to the LDAP server for authentication.
`ldap_bindpassword` `SEMAPHORE_LDAP_BIND_PASSWORD`	The password used to bind to the LDAP server for authentication.
`ldap_server` `SEMAPHORE_LDAP_SERVER`	The hostname and port of the LDAP server (e.g., ldap-server.com:1389).
`ldap_searchdn` `SEMAPHORE_LDAP_SEARCH_DN`	The base distinguished name (DN) used for searching users in the LDAP directory (e.g., dc=example,dc=org).
`ldap_searchfilter` `SEMAPHORE_LDAP_SEARCH_FILTER`	The filter used to search for users in the LDAP directory (e.g., (&(objectClass=inetOrgPerson)(uid=%s))).
`ldap_mappings.dn` `SEMAPHORE_LDAP_MAPPING_DN`	LDAP attribute to use as the distinguished name (DN) mapping for user authentication.
`ldap_mappings.mail` `SEMAPHORE_LDAP_MAPPING_MAIL`	LDAP attribute to use as the email address mapping for user authentication.
`ldap_mappings.uid` `SEMAPHORE_LDAP_MAPPING_UID`	LDAP attribute to use as the user ID (UID) mapping for user authentication.
`ldap_mappings.cn` `SEMAPHORE_LDAP_MAPPING_CN`	LDAP attribute to use as the common name (CN) mapping for user authentication.
Logging
`log.events.format` `SEMAPHORE_EVENT_LOG_FORMAT`	Event log format. Can be `json` or empty for text.
`log.events.enabled` `SEMAPHORE_EVENT_LOG_ENABLED`	Enable or disable event logging.
`log.events.logger` `SEMAPHORE_EVENT_LOGGER`	JSON map which contains event logger configuration.
`log.tasks.format` `SEMAPHORE_TASK_LOG_FORMAT`	Task log format. Can be `json` or empty for text.
`log.tasks.enabled` `SEMAPHORE_TASK_LOG_ENABLED`	Enable or disable task logging.
`log.tasks.logger` `SEMAPHORE_TASK_LOGGER`	JSON map which contains task logger configuration.
`log.tasks.result_logger` `SEMAPHORE_TASK_RESULT_LOGGER`	JSON map which contains task result logger configuration.
`syslog.enabled` `SEMAPHORE_SYSLOG_ENABLED`	Enable or disable writing logs to the configured syslog server.
`syslog.network` `SEMAPHORE_SYSLOG_NETWORK`	Protocol used to connect to the Syslog server: `udp` or `tcp`.
`syslog.address` `SEMAPHORE_SYSLOG_ADDRESS`	Hostname and port of the Syslog server. Example: `localhost:514`.
`syslog.tag` `SEMAPHORE_SYSLOG_TAG`	The tag used to mark Semaphore UI records on the Syslog server.
`syslog.format` `SEMAPHORE_SYSLOG_FORMAT`	Format of the Syslog messages. Can be `rfc5424` or empty for default.
Debugging
`debugging.api_delay` `SEMAPHORE_API_DELAY`	Add delay to API responses (for debugging purposes).
`debugging.pprof_dump_dir` `SEMAPHORE_PPROF_DUMP_DIR`	Directory for pprof dump files.
High Availability (HA)
`ha.enabled` `SEMAPHORE_HA_ENABLED`	Enable High Availability (HA) mode.
`ha.node_id` `SEMAPHORE_HA_NODE_ID`	Unique identifier for the HA node.
`ha.redis.addr` `SEMAPHORE_HA_REDIS_ADDR`	Address of the Redis server used for HA. Example: `localhost:6379`.
`ha.redis.db` `SEMAPHORE_HA_REDIS_DB`	Redis database number.
`ha.redis.pass` `SEMAPHORE_HA_REDIS_PASS`	Password for the Redis server.
`ha.redis.user` `SEMAPHORE_HA_REDIS_USER`	Username for the Redis server.
`ha.redis.tls` `SEMAPHORE_HA_REDIS_TLS`	Enable TLS for the Redis connection.
`ha.redis.tls_skip_verify` `SEMAPHORE_HA_REDIS_TLS_SKIP_VERIFY`	Skip TLS certificate verification for the Redis connection.