Configuration
Forge can be configured using several methods:
- Interactive setup — guided configuration when running Forge for the first time. It creates
config.json. - Configuration file — the primary and most flexible way to configure Forge.
- 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 FORGE_GIT_CLIENT | Type of Git client. Can be cmd_git or go_git. |
ssh_config_path FORGE_SSH_PATH | Path to SSH configuration file. |
port FORGE_PORT | TCP port on which the web interface will be available. Default: 3000 |
interface FORGE_INTERFACE | Useful if your server has multiple network interfaces |
tmp_path FORGE_TMP_PATH | Path to directory where cloned repositories and generated files are stored. Default: /tmp/semaphore |
max_parallel_tasks FORGE_MAX_PARALLEL_TASKS | Max number of parallel tasks that can be run on the server. |
max_task_duration_sec FORGE_MAX_TASK_DURATION_SEC | Max duration of a task in seconds. |
max_tasks_per_templateFORGE_MAX_TASKS_PER_TEMPLATE | Maximum number of recent tasks stored in the database for each template. |
schedule.timezone FORGE_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 FORGE_PASSWORD_LOGIN_DISABLED | Deny password login. |
non_admin_can_create_project FORGE_NON_ADMIN_CAN_CREATE_PROJECT | Allow non-admin users to create projects. |
env_vars FORGE_ENV_VARS | JSON map which contains environment variables. |
forwarded_env_vars FORGE_FORWARDED_ENV_VARS | JSON array of environment variables which will be forwarded from system. |
apps FORGE_APPS | JSON map which contains apps configuration. |
use_remote_runner FORGE_USE_REMOTE_RUNNER | |
runner_registration_token FORGE_RUNNER_REGISTRATION_TOKEN | |
| Database | |
sqlite.host FORGE_DB_HOST | Path to the SQLite database file. |
bolt.host FORGE_DB_HOST | Path to the BoltDB database file. |
mysql.host FORGE_DB_HOST | MySQL database host. |
mysql.name FORGE_DB_NAME | MySQL database (schema) name. |
mysql.user FORGE_DB_USER | MySQL user name. |
mysql.pass FORGE_DB_PASS | MySQL user's password. |
postgres.host FORGE_DB_HOST | Postgres database host. |
postgres.name FORGE_DB_NAME | Postgres database (schema) name. |
postgres.user FORGE_DB_USER | Postgres user name. |
postgres.pass FORGE_DB_PASS | Postgres user's password. |
dialect FORGE_DB_DIALECT | Can be sqlite (default), postgres, mysql or bolt (deprecated). |
*.options FORGE_DB_OPTIONS | JSON map which contains database connection options. |
| Security | |
access_key_encryption FORGE_ACCESS_KEY_ENCRYPTION | Secret key used for encrypting access keys in database. Read more in Database encryption reference. |
cookie_hash FORGE_COOKIE_HASH | Secret key used to sign cookies. |
cookie_encryption FORGE_COOKIE_ENCRYPTION | Secret key used to encrypt cookies. |
web_host FORGE_WEB_ROOT | Can be useful if you want to use Forge by the subpath, for example: http://yourdomain.com/semaphore. Do not add a trailing /. |
tls.enabled FORGE_TLS_ENABLED | Enable or disable TLS (HTTPS) for secure communication with the Forge server. |
tls.cert_file FORGE_TLS_CERT_FILE | Path to TLS certificate file. |
tls.key_file FORGE_TLS_KEY_FILE | Path to TLS key file. |
tls.http_redirect_port FORGE_TLS_HTTP_REDIRECT_PORT | Port to redirect HTTP traffic to HTTPS. |
auth.totp.enabled FORGE_TOTP_ENABLED | Enable Two-factor authentication with using TOTP. |
auth.totp.allow_recovery FORGE_TOTP_ALLOW_RECOVERY | Allow users to reset TOTP using a recovery code. |
| Process | |
process.user FORGE_PROCESS_USER | User under which wrapped processes (such as Ansible, Terraform, or OpenTofu) will run. |
process.uid FORGE_PROCESS_UID | ID of user under which wrapped processes (such as Ansible, Terraform, or OpenTofu) will run. |
process.gid FORGE_PROCESS_GID | ID for group under which wrapped processes (such as Ansible, Terraform, or OpenTofu) will run. |
process.chroot FORGE_PROCESS_CHROOT | Chroot directory for wrapped processes. |
email_sender FORGE_EMAIL_SENDER | Email address of the sender. |
email_host FORGE_EMAIL_HOST | SMTP server hostname. |
email_port FORGE_EMAIL_PORT | SMTP server port. |
email_secure FORGE_EMAIL_SECURE | Enable StartTLS to upgrade an unencrypted SMTP connection to a secure, encrypted one. |
email_tls FORGE_EMAIL_TLS | Use SSL or TLS connection for communication with the SMTP server. |
email_tls_min_version FORGE_EMAIL_TLS_MIN_VERSION | Minimum TLS version to use for the connection. |
email_username FORGE_EMAIL_USERNAME | Username for SMTP server authentication. |
email_password FORGE_EMAIL_PASSWORD | Password for SMTP server authentication. |
email_alert FORGE_EMAIL_ALERT | Flag which enables email alerts. |
| Messengers | |
telegram_alert FORGE_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 FORGE_TELEGRAM_CHAT | Set to the Chat ID for the chat to send alerts to. Read more in Telegram Notifications Setup |
telegram_token FORGE_TELEGRAM_TOKEN | Set to the Authorization Token for the bot that will receive the alert payload. Read more in Telegram Notifications Setup |
slack_alert FORGE_SLACK_ALERT | Set to True to enable pushing alerts to slack. It should be used in combination with slack_url |
slack_url FORGE_SLACK_URL | The slack webhook url. Forge will used it to POST Slack formatted json alerts to the provided url. |
microsoft_teams_alert FORGE_MICROSOFT_TEAMS_ALERT | Flag which enables Microsoft Teams alerts. |
microsoft_teams_url FORGE_MICROSOFT_TEAMS_URL | Microsoft Teams webhook URL. |
rocketchat_alert FORGE_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 FORGE_ROCKETCHAT_URL | The rocketchat webhook url. Forge will used it to POST Rocket.Chat formatted json alerts to the provided url. Available since v2.9.56. |
dingtalk_alert FORGE_DINGTALK_ALERT | Enable Dingtalk alerts. |
dingtalk_url FORGE_DINGTALK_URL | Dingtalk messenger webhook URL. |
gotify_alert FORGE_GOTIFY_ALERT | Enable Gotify alerts. |
gotify_url FORGE_GOTIFY_URL | Gotify server URL. |
gotify_token FORGE_GOTIFY_TOKEN | Gotify server token. |
| LDAP | |
ldap_enable FORGE_LDAP_ENABLE | Flag which enables LDAP authentication. |
ldap_needtls FORGE_LDAP_NEEDTLS | Flag to enable or disable TLS for LDAP connections. |
ldap_binddn FORGE_LDAP_BIND_DN | The distinguished name (DN) used to bind to the LDAP server for authentication. |
ldap_bindpassword FORGE_LDAP_BIND_PASSWORD | The password used to bind to the LDAP server for authentication. |
ldap_server FORGE_LDAP_SERVER | The hostname and port of the LDAP server (e.g., ldap-server.com:1389). |
ldap_searchdn FORGE_LDAP_SEARCH_DN | The base distinguished name (DN) used for searching users in the LDAP directory (e.g., dc=example,dc=org). |
ldap_searchfilter FORGE_LDAP_SEARCH_FILTER | The filter used to search for users in the LDAP directory (e.g., (&(objectClass=inetOrgPerson)(uid=%s))). |
ldap_mappings.dn FORGE_LDAP_MAPPING_DN | LDAP attribute to use as the distinguished name (DN) mapping for user authentication. |
ldap_mappings.mail FORGE_LDAP_MAPPING_MAIL | LDAP attribute to use as the email address mapping for user authentication. |
ldap_mappings.uid FORGE_LDAP_MAPPING_UID | LDAP attribute to use as the user ID (UID) mapping for user authentication. |
ldap_mappings.cn FORGE_LDAP_MAPPING_CN | LDAP attribute to use as the common name (CN) mapping for user authentication. |
| Logging | |
log.events.format FORGE_EVENT_LOG_FORMAT | Event log format. Can be json or empty for text. |
log.events.enabled FORGE_EVENT_LOG_ENABLED | Enable or disable event logging. |
log.events.logger FORGE_EVENT_LOGGER | JSON map which contains event logger configuration. |
log.tasks.format FORGE_TASK_LOG_FORMAT | Task log format. Can be json or empty for text. |
log.tasks.enabled FORGE_TASK_LOG_ENABLED | Enable or disable task logging. |
log.tasks.logger FORGE_TASK_LOGGER | JSON map which contains task logger configuration. |
log.tasks.result_logger FORGE_TASK_RESULT_LOGGER | JSON map which contains task result logger configuration. |
Frequently asked questions
1. How to configure a public URL for Forge
If you use nginx or other web server before Forge, you should provide configuration option web_host.
For example you configured NGINX on the server which proxies queries to Forge.
Server address https://example.com and you proxies all queries https://example.com/semaphore to Forge.
Your web_host will be https://example.com/semaphore.