Configuration

Semaphore can be configured using several methods:

• Interactive setup — guided configuration when running Semaphore for the first time. It creates config.json.
• Configuration file — the primary and most flexible way to configure Semaphore.
• Environment variables — useful for containerized or cloud-native deployments.
• Snap configuration (deprecated) — legacy method used when installing via Snap packages.

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 or go_git.
ssh_config_path SEMAPHORE_SSH_PATH	Path to SSH configuration file.
port SEMAPHORE_PORT	TCP port on which the web interface will be available. Default: 3000
interface SEMAPHORE_INTERFACE	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
max_parallel_tasks SEMAPHORE_MAX_PARALLEL_TASKS	Max number of parallel tasks that can be run on the server.
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.
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.
forwarded_env_vars SEMAPHORE_FORWARDED_ENV_VARS	JSON array of environment variables which will be forwarded from system.
apps SEMAPHORE_APPS	JSON map which contains apps configuration.
use_remote_runner SEMAPHORE_USE_REMOTE_RUNNER
runner_registration_token SEMAPHORE_RUNNER_REGISTRATION_TOKEN
Database
sqlite.host SEMAPHORE_DB_HOST	Path to the SQLite database file.
bolt.host SEMAPHORE_DB_HOST	Path to the BoltDB 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, mysql or bolt (deprecated).
*.options SEMAPHORE_DB_OPTIONS	JSON map which contains database connection options.
Security
access_key_encryption SEMAPHORE_ACCESS_KEY_ENCRYPTION	Secret key used for encrypting access keys in database. Read more in Database encryption reference.
cookie_hash SEMAPHORE_COOKIE_HASH	Secret key used to sign cookies.
cookie_encryption SEMAPHORE_COOKIE_ENCRYPTION	Secret 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_port SEMAPHORE_TLS_HTTP_REDIRECT_PORT	Port to redirect HTTP traffic to HTTPS.
auth.totp.enabled SEMAPHORE_TOTP_ENABLED	Enable Two-factor authentication with using TOTP.
auth.totp.allow_recovery SEMAPHORE_TOTP_ALLOW_RECOVERY	Allow users to reset TOTP using a recovery code.
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.
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.

Frequently asked questions

1. How to configure a public URL for Semaphore UI

If you use nginx or other web server before Semaphore, you should provide configuration option web_host.

For example you configured NGINX on the server which proxies queries to Semaphore.

Server address https://example.com and you proxies all queries https://example.com/semaphore to Semaphore.

Your web_host will be https://example.com/semaphore.