8 |
9 | Semaphore is written in pure Go and available for Windows, macOS and Linux (x64, ARM, ARM64). Semaphore is an open-source project with concise and high-quality code.
10 |
11 | Semaphore supports the following databases:
12 |
13 | * MySQL
14 | * PostgreSQL
15 | * [BoltDB](https://github.com/etcd-io/bbolt) – embedded key/value database
16 |
17 | With Semaphore you can:
18 |
19 | * [Build, deploy and rollback](./administration-guide/cicd.md)
20 | * Group playbooks to projects
21 | * Manage environments, inventories, repositories and access keys
22 | * Run playbooks from the browser. Responsive UI allows the use of Semaphore on mobile devices
23 | * Run playbooks by schedule
24 | * View detailed logs of any playbook runs, at any time
25 | * Delegate other users the running of playbooks
26 | * Get notifications about playbook runs
27 |
28 | ## Links
29 |
30 | * Source code: [https://github.com/semaphoreui/semaphore](https://github.com/semaphoreui/semaphore)
31 | * Issue tracking: [https://github.com/semaphoreui/semaphore/issues](https://github.com/semaphoreui/semaphore/issues)
32 | * Docker: [https://hub.docker.com/r/semaphoreui/semaphore](https://hub.docker.com/r/semaphoreui/semaphore)
33 | * Snap: [https://snapcraft.io/semaphore](https://snapcraft.io/semaphore)
34 | * Contact: [denis@semaphoreui.com](mailto:denis@semaphoreui.com)
35 | * Docker container configurator:
36 |
37 | [](https://semaphoreui.com/install/docker/)
38 |
39 | * Our responsive community:
40 |
41 | [](https://discord.gg/5R6k7hNGcH)
--------------------------------------------------------------------------------
/src/SUMMARY.md:
--------------------------------------------------------------------------------
1 | # Table of contents
2 |
3 | * [Welcome to Semaphore UI](./README.md)
4 |
5 | * [Admin Guide]()
6 | * [Installation](./administration-guide/installation.md)
7 | * [Package manager](./administration-guide/installation/package-manager.md)
8 | * [Docker](./administration-guide/installation/docker.md)
9 | * [Binary file](./administration-guide/installation/binary-file.md)
10 | * [Kubernetes (Helm chart)](./administration-guide/installation/k8s.md)
11 | * [Snap (deprecated)](./administration-guide/installation/snap.md)
12 | * [Manual Installation](./administration-guide/installation\_manually.md)
13 | * [Configuration](./administration-guide/configuration.md)
14 | * [Configuration file](./administration-guide/configuration/config-file.md)
15 | * [Envrioment variables](./administration-guide/configuration/env-vars.md)
16 | * [Interactive setup](./administration-guide/configuration/cli.md)
17 | * [Snap configuration](./administration-guide/configuration/snap.md)
18 | * [Upgrading](./administration-guide/upgrading.md)
19 | * [Security](./administration-guide/security.md)
20 | * [Database security](./administration-guide/security/database.md)
21 | * [Network security](./administration-guide/security/network.md)
22 | * [NGINX config](./administration-guide/security/nginx.md)
23 | * [Apache config](./administration-guide/security/apache.md)
24 | * [CLI](./administration-guide/cli.md)
25 | * [Users](./administration-guide/cli/users.md)
26 | * [Vaults](./administration-guide/cli/vaults.md)
27 | * [Runners](./administration-guide/cli/runners.md)
28 | * [LDAP](./administration-guide/ldap.md)
29 | * [OpenID](./administration-guide/openid.md)
30 | * [GitHub config](./administration-guide/openid/github.md)
31 | * [Google config](./administration-guide/openid/google.md)
32 | * [GitLab config](./administration-guide/openid/gitlab.md)
33 | * [Authelia config](./administration-guide/openid/authelia.md)
34 | * [Authentik config](./administration-guide/openid/authentik.md)
35 | * [Keycloak config](./administration-guide/openid/keycloak.md)
36 | * [Okta config](./administration-guide/openid/okta.md)
37 | * [Azure config](./administration-guide/openid/azure.md)
38 | * [API](./administration-guide/api.md)
39 | * [Pipelines](./administration-guide/cicd.md)
40 | * [Runners](./administration-guide/runners.md)
41 | * [Logs](./administration-guide/logs.md)
42 | * [Notifications](./administration-guide/notifications.md)
43 |
44 | * [User Guide]()
45 | * [Projects](./user-guide/projects.md)
46 | * [History](./user-guide/projects/history.md)
47 | * [Activity](./user-guide/projects/activity.md)
48 | * [Settings](./user-guide/projects/settings.md)
49 | * [Runners (Pro)](./user-guide/projects/runners.md)
50 | * [Task Templates](./user-guide/task-templates/README.md)
51 | * [Ansible](./user-guide/task-templates/apps/ansible.md)
52 | * [Terraform/OpenTofu](./user-guide/task-templates/apps/terraform.md)
53 | * [Workspaces](./user-guide/task-templates/apps/terraform/workspaces.md)
54 | * [HTTP Backend (Pro)](./user-guide/task-templates/apps/terraform/states.md)
55 | * [Shell/Bash scripts](./user-guide/task-templates/apps/bash.md)
56 | * [PowerShell](./user-guide/task-templates/apps/powershell.md)
57 | * [Python](./user-guide/task-templates/apps/python.md)
58 | * [Tasks](./user-guide/tasks.md)
59 | * [Schedules](./user-guide/schedules.md)
60 | * [Key Store](./user-guide/key-store.md)
61 | * [Inventory](./user-guide/inventory.md)
62 | * [Kerberos](./user-guide/inventory/kerberos.md)
63 | * [Variable Groups](./user-guide/environment.md)
64 | * [Repositories](./user-guide/repositories.md)
65 | * [Bitbucket Access Token](./user-guide/repositories/bitbucket_access_token.md)
66 | * [Integrations](./user-guide/integrations.md)
67 | * [Team](./user-guide/team.md)
68 |
73 |
74 | * [FAQ]()
75 | * [Troubleshooting](./faq/troubleshooting.md)
76 |
--------------------------------------------------------------------------------
/src/administration-guide/api.md:
--------------------------------------------------------------------------------
1 | # API
2 |
3 | ## API reference
4 |
5 | Semaphore UI provides two formats of API documentation, so you can choose the one that fits your workflow best:
6 |
7 | * [Swagger/OpenAPI](https://semaphoreui.com/api-docs) — ideal if you prefer an interactive, browser-based experience.
8 | * [Postman](https://api.semaphoreui.com) — perfect if you want to leverage the full power of the Postman app for testing and exploring the API.
9 |
10 | Both options include complete documentation of available endpoints, parameters, and example responses.
11 |
12 | ## Getting Started with the API
13 |
14 | To start using the Semaphore API, you need to generate an API token.
15 | This token must be included in the request header as:
16 |
17 | ```http
18 | Authorization: Bearer YOUR_API_TOKEN
19 | ```
20 |
21 | ### Creating an API Token
22 |
23 | There are two ways to create an API token:
24 | - Through the web interface (since 2.14)
25 | - Using HTTP request
26 |
27 | #### Through the web interface (since 2.14)
28 |
29 | You can create and manage your API tokens via the Semaphore web UI:
30 |
31 | 
32 |
33 | #### Using HTTP request
34 |
35 | You can also authenticate and generate a session token using a direct HTTP request.
36 |
37 | Login to Semaphore (password should be escaped, `slashy\\pass` instead of `slashy\pass` e.g.):
38 |
39 | ```bash
40 | curl -v -c /tmp/semaphore-cookie -XPOST \
41 | -H 'Content-Type: application/json' \
42 | -H 'Accept: application/json' \
43 | -d '{"auth": "YOUR_LOGIN", "password": "YOUR_PASSWORD"}' \
44 | http://localhost:3000/api/auth/login
45 | ```
46 |
47 | Generate a new token, and get the new token:
48 |
49 | ```bash
50 | curl -v -b /tmp/semaphore-cookie -XPOST \
51 | -H 'Content-Type: application/json' \
52 | -H 'Accept: application/json' \
53 | http://localhost:3000/api/user/tokens
54 | ```
55 |
56 | The command should return something similar to:
57 |
58 | ```json
59 | {
60 | "id": "YOUR_ACCESS_TOKEN",
61 | "created": "2025-05-21T02:35:12Z",
62 | "expired": false,
63 | "user_id": 3
64 | }
65 | ```
66 | ---
67 |
68 | ## Using token to make API requests
69 |
70 | Once you have your API token, include it in the **Authorization** header to authenticate your requests.
71 |
72 | ### Launch a task
73 |
74 | Use this token for launching a task or anything else:
75 |
76 | ```bash
77 | curl -v -XPOST \
78 | -H 'Content-Type: application/json' \
79 | -H 'Accept: application/json' \
80 | -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
81 | -d '{"template_id": 1}' \
82 | http://localhost:3000/api/project/1/tasks
83 | ```
84 |
85 | ---
86 |
87 | ## Expiring an API token
88 |
89 | If you no longer need the token, you should expire it to keep your account secure.
90 |
91 | To manually revoke (expire) an API token, send a DELETE request to the token endpoint:
92 |
93 | ```bash
94 | curl -v -XDELETE \
95 | -H 'Content-Type: application/json' \
96 | -H 'Accept: application/json' \
97 | -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
98 | http://localhost:3000/api/user/tokens/YOUR_ACCESS_TOKEN
99 | ```
100 |
--------------------------------------------------------------------------------
/src/administration-guide/cicd.md:
--------------------------------------------------------------------------------
1 | # Pipelines
2 |
3 | Semaphore supports simple pipelines with using `build` and `deploy` tasks.
4 |
5 | Semaphore passes `semaphore_vars` variable to each Ansible playbook which it runs.
6 |
7 | You can use it in your Ansible tasks to get what type of task was run, which version should be build or deployed, who ran the task, etc.
8 |
9 | ---
10 |
11 | Example of `semaphore_vars` for `build` tasks:
12 |
13 | ```yaml
14 | semaphore_vars:
15 | task_details:
16 | type: build
17 | username: user123
18 | message: New version of some feature
19 | target_version: 1.5.33
20 | ```
21 |
22 | Example of `semaphore_vars` for `deploy` tasks:
23 |
24 | ```yaml
25 | semaphore_vars:
26 | task_details:
27 | type: deploy
28 | username: user123
29 | message: Deploy new feature to servers
30 | incoming_version: 1.5.33
31 | ```
32 |
33 | ### Build
34 |
35 | This type of task is used to create [artifacts](https://en.wikipedia.org/wiki/Artifact\_\(software\_development\)). Each build task has autogenerated version. You should use variable `semaphore_vars.task_details.target_version` in your Ansible playbook to get what version of the artifact should be created. After the artifact is created, it can be used for deployment.
36 |
37 | ---
38 |
39 | Example of `build` Ansible role:
40 |
41 | 1. Get app source code from GitHub
42 | 2. Compile source code
43 | 3. Pack created binary to a tarball with name `app-{{semaphore_vars.task_details.target_version}}.tar.gz`
44 | 4. Send `app-{{semaphore_vars.task_details.target_version}}.tar.gz` to an S3 bucket
45 |
46 |
47 |
48 | ### Deploy
49 |
50 | This type of task is used to deploy artifacts to destination servers. Each deployment task is associated with the build task. You should use variable `semaphore_vars.task_details.incoming_version` in your Ansible playbook to get what version of the artifact should be deployed.
51 |
52 | ---
53 |
54 | Example of `deploy` Ansible role:
55 |
56 | 1. Download `app-{{semaphore_vars.task_details.incoming_version}}.tar.gz` from an S3 bucket to destination servers
57 | 2. Unpack `app-{{semaphore_vars.task_details.incoming_version}}.tar.gz` to destination directory
58 | 3. Create or update configuration files
59 | 4. Restart app service
60 |
61 |
--------------------------------------------------------------------------------
/src/administration-guide/cli.md:
--------------------------------------------------------------------------------
1 | # CLI
2 |
3 |
4 | * [Runners](./cli/runners.md)
5 | * [Users](./cli/users.md)
6 | * [Vaults](./cli/vaults.md)
7 |
8 |
9 | ## Common config options
10 |
11 | | Option | Description |
12 | |----------------------|-------------------------------------------|
13 | |`--config config.json`| Path to the configuration file. |
14 | |`--no-config` | Do not use any configuration file. Only environment variable will be used. |
15 | |`--log-level ERROR` | `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`, `PANIC` |
16 |
17 | ## Version
18 |
19 | Print current version.
20 |
21 | ```bash
22 | semaphore version
23 | ```
24 |
25 |
26 | ## Help
27 |
28 | Print list of supported commands.
29 |
30 | ```bash
31 | semaphore help
32 | ```
33 |
34 | ## Database migration
35 |
36 | Update database schema to latest version.
37 |
38 | ```
39 | semaphore migrate
40 | ```
41 |
42 | ## Interactive setup
43 |
44 | Use this option for first time configuration.
45 |
46 | ```
47 | semaphore setup
48 | ```
49 |
50 | ## Server mode
51 |
52 | Start the server.
53 |
54 | ```
55 | semaphore server
56 | ```
57 |
58 | ## Runner mode
59 |
60 | Start the runner.
61 |
62 | ```
63 | semaphore runner
64 | ```
65 |
--------------------------------------------------------------------------------
/src/administration-guide/cli/runners.md:
--------------------------------------------------------------------------------
1 |
5 |
6 | # Runners
7 |
8 |
9 | We have separate section for Runners.
10 |
--------------------------------------------------------------------------------
/src/administration-guide/cli/users.md:
--------------------------------------------------------------------------------
1 |
5 |
6 | # Users
7 |
8 | Using CLI you can add, remove or change user.
9 |
10 | ```
11 | semaphore user --help
12 | ```
13 |
14 | ## How to add admin user
15 |
16 | ```
17 | semaphore user add \
18 | --admin \
19 | --login newAdmin \
20 | --email new-admin@example.com \
21 | --name "New Admin" \
22 | --password "New$Password"
23 | ```
24 |
25 | ## How to change user password
26 |
27 | ```
28 | semaphore user change-by-login \
29 | --login myAdmin \
30 | --password "New$Password"
31 | ```
32 |
--------------------------------------------------------------------------------
/src/administration-guide/cli/vaults.md:
--------------------------------------------------------------------------------
1 |
5 |
6 | ### Vaults
7 |
8 | You can reencrypt your secrets in database with using following command:
9 |
10 | ```
11 | semaphore vault rekey --old-key `bolt.host`
`SEMAPHORE_DB_HOST`
| Path to the BoltDB database file. | 18 | |
`mysql.host`
`SEMAPHORE_DB_HOST`
| MySQL database host. | 19 | |
`mysql.name`
`SEMAPHORE_DB_NAME`
| MySQL database (schema) name. | 20 | |
`mysql.user`
`SEMAPHORE_DB_USER`
| MySQL user name. | 21 | |
`mysql.pass`
`SEMAPHORE_DB_PASS`
| MySQL user's password. | 22 | |
`postgres.host`
`SEMAPHORE_DB_HOST`
| Postgres database host. | 23 | |
`postgres.name`
`SEMAPHORE_DB_NAME`
| Postgres database (schema) name. | 24 | |
`postgres.user`
`SEMAPHORE_DB_USER`
| Postgres user name. | 25 | |
`postgres.pass`
`SEMAPHORE_DB_PASS`
| Postgres user's password. | 26 | |
`dialect`
`SEMAPHORE_DB_DIALECT`
| Can be `mysql`, `postgres `or `bolt` | 27 | |
`git_client`
`SEMAPHORE_GIT_CLIENT`
| | 28 | |
`ssh_config_path`
`SEMAPHORE_SSH_PATH`
| | 29 | |
`port`
`SEMAPHORE_PORT`
| TCP port on which the web interface will be available. Default: 3000 | 30 | |
`interface`
`SEMAPHORE_INTERFACE`
| Useful if your server has multiple network interfaces | 31 | |
`tmp_path`
`SEMAPHORE_TMP_PATH`
| Path to directory where cloned repositories and generated files are stored. Default: /tmp/semaphore | 32 | |
`access_key_encryption`
`SEMAPHORE_ACCESS_KEY_ENCRYPTION`
| Secret key used for encrypting access keys in database. Read more in [Database encryption reference](./security.md#database-encryption). | 33 | |
`web_host`
`SEMAPHORE_WEB_ROOT`
| Can be useful if you want to use Semaphore by the subpath, for example: [http://yourdomain.com/semaphore](http://yourdomain.com/semaphore). Do not add a trailing `/`. | 34 | |
`tls.enabled`
`SEMAPHORE_TLS_ENABLED`
| | 35 | |
`tls.cert_file`
`SEMAPHORE_TLS_CERT_FILE`
| | 36 | |
`tls.key_file`
`SEMAPHORE_TLS_KEY_FILE`
| | 37 | |
`email_sender`
`SEMAPHORE_EMAIL_SENDER`
| | 38 | |
`email_host`
`SEMAPHORE_EMAIL_HOST`
| | 39 | |
`email_port`
`SEMAPHORE_EMAIL_PORT`
| | 40 | |
`email_secure`
`SEMAPHORE_EMAIL_SECURE`
| | 41 | |
`email_tls`
`SEMAPHORE_EMAIL_TLS`
| | 42 | |
`email_username`
`SEMAPHORE_EMAIL_USERNAME`
| | 43 | |
`email_password`
`SEMAPHORE_EMAIL_PASSWORD`
| | 44 | |
`email_alert`
`SEMAPHORE_EMAIL_ALERT`
| | 45 | |
`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`. | 46 | |
`telegram_chat`
`SEMAPHORE_TELEGRAM_CHAT`
| Set to the Chat ID for the chat to send alerts to. Read more in [Telegram Notifications Setup](./notifications.md#chat-id) | 47 | |
`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](./notifications.md#bot-setup) | 48 | |
`slack_alert`
`SEMAPHORE_SLACK_ALERT`
| Set to True to enable pushing alerts to slack. It should be used in combination with `slack_url` | 49 | |
`slack_url`
`SEMAPHORE_SLACK_URL`
| The slack webhook url. Semaphore will used it to POST Slack formatted json alerts to the provided url. | 50 | |
`microsoft_teams_alert`
`SEMAPHORE_MICROSOFT_TEAMS_ALERT`
| Set to True to enable pushing alerts to teams. It should be used in combination with `microsoft_teams_url`. | 51 | |
`microsoft_teams_url`
`SEMAPHORE_MICROSOFT_TEAMS_URL`
| The teams webhook url. Semaphore will used it to POST alerts. | 52 | |
`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. | 53 | |
`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. | 54 | |
`ldap_enable`
`SEMAPHORE_LDAP_ENABLE`
| | 55 | |
`ldap_needtls`
`SEMAPHORE_LDAP_NEEDTLS`
| | 56 | |
`ldap_binddn`
`SEMAPHORE_LDAP_BIND_DN`
| | 57 | |
`ldap_bindpassword`
`SEMAPHORE_LDAP_BIND_PASSWORD`
| | 58 | |
`ldap_server`
`SEMAPHORE_LDAP_SERVER`
| | 59 | |
`ldap_searchdn`
`SEMAPHORE_LDAP_SEARCH_DN`
| | 60 | |
`ldap_searchfilter`
`SEMAPHORE_LDAP_SEARCH_FILTER`
| | 61 | |
`max_parallel_tasks`
`SEMAPHORE_MAX_PARALLEL_TASKS`
| Max allowed parallel tasks for whole Semaphore instance. | 62 | |
`max_task_duration_sec`
`SEMAPHORE_MAX_TASK_DURATION_SEC`
| Max allowed parallel tasks for whole Semaphore instance. | 63 | |
`max_tasks_per_template`
`SEMAPHORE_MAX_TASKS_PER_TEMPLATE`
| Max allowed parallel tasks for whole Semaphore instance. | 64 | |
`oidc_providers`  | OpenID provider settings. You can provide multiple OpenID providers. More about OpenID configuration read in [OpenID](./openid.md).
| 65 | |
`password_login_disable`
`SEMAPHORE_PASSWORD_LOGIN_DISABLED`
| Disable login with using password. Only LDAP and OpenID. | 66 | |
`non_admin_can_create_project`
`SEMAPHORE_NON_ADMIN_CAN_CREATE_PROJECT`
| | 67 | |
`env_vars`
`SEMAPHORE_ENV_VARS`
| | 68 | |
`forwarded_env_vars`
`SEMAPHORE_FORWARDED_ENV_VARS`
| | 69 | |
`apps`
`SEMAPHORE_APPS`
| | 70 | |
`use_remote_runner`
`SEMAPHORE_USE_REMOTE_RUNNER`
| | 71 | |
`use_remote_runner`
`SEMAPHORE_USE_REMOTE_RUNNER`
| | 72 | |
`runner_registration_token`
`SEMAPHORE_RUNNER_REGISTRATION_TOKEN`
| | 73 | |
`auth.totp.enabled`
`SEMAPHORE_TOTP_ENABLED`
| | 74 | |
`auth.totp.allow_recovery`
`SEMAPHORE_TOTP_ALLOW_RECOVERY`
| | 75 | 76 | ## Frequently asked questions 77 | 78 | ### 1. How to configure a public URL for Semaphore UI 79 | 80 | If you use nginx or other web server before Semaphore, you should provide configuration option `web_host`. 81 | 82 | For example you configured NGINX on the server which proxies queries to Semaphore. 83 | 84 | Server address `https://example.com` and you proxies all queries `https://example.com/semaphore` to Semaphore. 85 | 86 | Your `web_host` will be `https://example.com/semaphore`. 87 | 88 | 89 | -------------------------------------------------------------------------------- /src/administration-guide/configuration/cli.md: -------------------------------------------------------------------------------- 1 | 2 | # Interactive setup 3 | 4 | Use this option for first time configuration (not working for Semaphore installed via Snap). 5 | 6 | ```bash 7 | semaphore setup 8 | ``` -------------------------------------------------------------------------------- /src/administration-guide/configuration/config-file.md: -------------------------------------------------------------------------------- 1 | 2 | # Configuration file 3 | 4 | ## Creating configuration file 5 | 6 | Semaphore uses a `config.json` file for its core configuration. You can generate this file interactively using built-in tools or through a web-based configurator. 7 | 8 | ### Generate via CLI 9 | 10 | Use the following commands to generate the configuration file interactively: 11 | 12 | * For the Semaphore server: 13 | ``` 14 | semaphore setup 15 | ``` 16 | * For the Semaphore runner: 17 | ``` 18 | semaphore runner setup 19 | ``` 20 | 21 |
22 | For more details about runner configuration, see the Runners section.
23 |
24 |
25 |
26 | ### Generate via Web
27 |
28 | Alternatively, you can use the web-based interactive configurator:
29 | * [Server configurator](https://semaphoreui.com/install/binary/2_13/config)
30 | * [Runner configurator](https://semaphoreui.com/install/binary/2_13/runner)
31 |
32 | ## Configuration file example
33 |
34 | Semaphore uses a `config.json` configuration file with following content:
35 |
36 | ```javascript
37 | {
38 | "mysql_test": {
39 | "host": "127.0.0.1:3306",
40 | "user": "root",
41 | "pass": "***",
42 | "name": "semaphore"
43 | },
44 |
45 | "dialect": "mysql",
46 |
47 | "git_client": "go_git",
48 |
49 | "auth": {
50 | "totp": {
51 | "enabled": false,
52 | "allow_recovery": true
53 | }
54 | },
55 |
56 | "use_remote_runner": true,
57 | "runner_registration_token": "73fs***",
58 |
59 | "tmp_path": "/tmp/semaphore",
60 | "cookie_hash": "96Nt***",
61 | "cookie_encryption": "x0bs***",
62 | "access_key_encryption": "j1ia***",
63 |
64 | "max_tasks_per_template": 3,
65 |
66 | "log": {
67 | "events": {
68 | "enabled": true,
69 | "path": "./events.log"
70 | }
71 | },
72 |
73 | "process": {
74 | "chroot": "/opt/semaphore/sandbox"
75 | }
76 | }
77 | ```
78 |
79 | ## Configuration file usage
80 |
81 | * For Semaphore server:
82 |
83 | ```bash
84 | semaphore server --config ./config.json
85 | ```
86 |
87 | * For Semaphore runner:
88 |
89 | ```bash
90 | semaphore runner start --config ./config.json
91 | ```
92 |
--------------------------------------------------------------------------------
/src/administration-guide/configuration/env-vars.md:
--------------------------------------------------------------------------------
1 | # Environment variables
2 |
3 | With using environment variables you can override any available configuration option.
4 |
5 | You can use interactive evnvironment variables generator (for Docker):
6 | * for [server](https://semaphoreui.com/install/docker/2_12/)
7 | * for [runner](https://semaphoreui.com/install/docker/2_12/runner).
8 |
--------------------------------------------------------------------------------
/src/administration-guide/configuration/snap.md:
--------------------------------------------------------------------------------
1 | # Snap configuration
2 |
3 | Snap configurations should be used for when Semaphore was installed via Snap.
4 |
5 | To see a list of available options, use the following command:
6 |
7 | ```bash
8 | sudo snap get semaphore
9 | ```
10 |
11 | You can change each of these configurations. For example if you want to change Semaphore port, use following command:
12 |
13 | ```bash
14 | sudo snap set semaphore port=4444
15 | ```
16 |
17 | Don't forget to restart Semaphore after changing a configuration:
18 |
19 | ```bash
20 | sudo snap restart semaphore
21 | ```
22 |
--------------------------------------------------------------------------------
/src/administration-guide/installation.md:
--------------------------------------------------------------------------------
1 | # Installation
2 |
3 | You can install Semaphore in multiple ways, depending on your operating system, environment, and preferences:
4 |
5 | * **Package manager**6 | Install Semaphore using a native package for your distribution (e.g., apt for Debian/Ubuntu or dnf for RHEL-based systems). This is the easiest way to get started on Linux servers and integrates well with system services.
7 | [Learn more »](./installation/package-manager) 8 | 9 | * **Docker**
10 | Run Semaphore as a container using Docker or Docker Compose. Ideal for fast setup, sandboxed environments, and CI/CD pipelines. Recommended for users who prefer infrastructure as code.
11 | [Learn more »](./installation/docker) 12 | 13 | * **Binary file**
14 | Download a precompiled binary from the releases page. Great for manual installation or embedding in custom workflows. Works across Linux, macOS, and Windows (via WSL).
15 | [Learn more »](./installation/binary-file) 16 | 17 | * **Kubernetes (Helm chart)**
18 | Deploy Semaphore into a Kubernetes cluster using Helm. Best suited for production-grade, scalable infrastructure. Supports easy configuration and upgrades via Helm values.
19 | [Learn more »](./installation/k8s) 20 | 21 | * **Snap (deprecated)**
22 | Previously available as a Snap package. This method is deprecated and no longer maintained. Users are advised to switch to one of the supported methods above.
23 | [Learn more »](./installation/snap) 24 | 25 | See also: 26 | * [Run as service](./installation/binary-file.md#run-as-a-service) 27 | * [Manual installation](./installation_manually.md) 28 | 29 | ---- 30 | 31 | 32 | ### Installing Additional Python Packages 33 | 34 | Some Ansible modules and roles require additional python packages to run. To install additional python packages, create a `requirements.txt` file and mount it in the `/etc/semaphore` directory on the container. For example, you could add the following lines to your `docker-compose.yml` file: 35 | 36 | ```yaml 37 | volumes: 38 | - /path/to/requirements.txt:/etc/semaphore/requirements.txt 39 | ``` 40 | 41 | The packages specified in the requirements file will be installed when the container starts up. 42 | 43 | For more information about Python requirements files, see the [Pip Requirements File Format reference](https://pip.pypa.io/en/stable/reference/requirements-file-format/) 44 | -------------------------------------------------------------------------------- /src/administration-guide/installation/binary-file.md: -------------------------------------------------------------------------------- 1 | 5 | 6 | # Binary file 7 | 8 |
9 | Look into the manual installation on how to set-up your Python/Ansible/Systemd environment!
10 |
11 |
12 |
13 | Download the `*.tar.gz` for your platform from [Releases page](https://github.com/semaphoreui/semaphore/releases). Unpack it and setup Semaphore using the following commands:
14 |
15 | {{#tabs }}
16 | {{#tab name="Linux (x64)" }}
17 | ```
18 | download/v2.13.14/semaphore_2.13.14_linux_amd64.tar.gz
19 |
20 | tar xf semaphore_2.13.14_linux_amd64.tar.gz
21 |
22 | ./semaphore setup
23 | ```
24 | {{#endtab }}
25 |
26 | {{#tab name="Linux (ARM64)" }}
27 | ```
28 | wget https://github.com/semaphoreui/semaphore/releases/\
29 |
30 | download/v2.13.14/semaphore_2.13.14_linux_arm64.tar.gz
31 |
32 | tar xf semaphore_2.13.14_linux_arm64.tar.gz
33 |
34 | ./semaphore setup
35 | ```
36 | {{#endtab }}
37 |
38 | {{#tab name="Windows (x64)" }}
39 | ```
40 | Invoke-WebRequest `
41 | -Uri ("https://github.com/semaphoreui/semaphore/releases/" +
42 | "download/v2.13.14/semaphore_2.13.14_windows_amd64.zip") `
43 |
44 | -OutFile semaphore.zip
45 |
46 | Expand-Archive -Path semaphore.zip -DestinationPath ./
47 |
48 | ./semaphore setup
49 | ```
50 | {{#endtab }}
51 | {{#endtabs }}
52 |
53 | Now you can run Semaphore:
54 |
55 | ```
56 | ./semaphore server --config=./config.json
57 | ```
58 |
59 | Semaphore will be available via the following URL [https://localhost:3000](https://localhost:3000).
60 |
61 | ----
62 |
63 | ### Run as a service
64 |
65 | For more detailed information — look into the [extended Systemd service documentation](../installation_manually.md#extended-systemd-service).
66 |
67 | If you installed Semaphore via a package manager, or by downloading a binary file, you should create the Semaphore service manually.
68 |
69 | Create the systemd service file:
70 |
71 |
72 | Replace
74 |
75 | ```bash
76 | sudo cat > /etc/systemd/system/semaphore.service </path/to/semaphore and /path/to/config.json to your semaphore and config file path.
73 |
9 | Look into the manual installation on how to set-up your Python/Ansible/Systemd environment!
10 |
11 |
12 |
13 | Download package file from [Releases page](https://github.com/semaphoreui/semaphore/releases).
14 |
15 | `*.deb` for Debian and Ubuntu, `*.rpm` for CentOS and RedHat.
16 |
17 | Here are several installation commands, depending on the package manager:
18 |
19 |
20 | {{#tabs }}
21 |
22 | {{#tab name="Debian / Ubuntu (x64)"}}
23 | ```bash
24 | wget https://github.com/semaphoreui/semaphore/releases/\
25 | download/v2.13.14/semaphore_2.13.14_linux_amd64.deb
26 |
27 | sudo dpkg -i semaphore_2.13.14_linux_amd64.deb
28 | ```
29 | {{#endtab }}
30 |
31 | {{#tab name="Debian / Ubuntu (ARM64)" }}
32 | ```bash
33 | wget https://github.com/semaphoreui/semaphore/releases/\
34 | download/v2.13.14/semaphore_2.13.14_linux_arm64.deb
35 |
36 | sudo dpkg -i semaphore_2.13.14_linux_arm64.deb
37 | ```
38 | {{#endtab }}
39 |
40 | {{#tab name="CentOS (x64)" }}
41 | ```bash
42 | wget https://github.com/semaphoreui/semaphore/releases/\
43 | download/v2.13.14/semaphore_2.13.14_linux_amd64.rpm
44 |
45 | sudo yum install semaphore_2.13.14_linux_amd64.rpm
46 | ```
47 | {{#endtab }}
48 |
49 | {{#tab name="CentOS (ARM64)" }}
50 | ```bash
51 | wget https://github.com/semaphoreui/semaphore/releases/\
52 | download/v2.13.14/semaphore_2.13.14_linux_arm64.rpm
53 |
54 | sudo yum install semaphore_2.13.14_linux_arm64.rpm
55 | ```
56 | {{#endtab }}
57 |
58 | {{#endtabs }}
59 |
60 | Setup Semaphore by using the following command:
61 |
62 | ```
63 | semaphore setup
64 | ```
65 |
66 | Now you can run Semaphore:
67 |
68 | ```
69 | semaphore server --config=./config.json
70 | ```
71 |
72 | Semaphore will be available via this URL [https://localhost:3000](https://localhost:3000).
73 |
74 | ----
75 |
--------------------------------------------------------------------------------
/src/administration-guide/installation/snap.md:
--------------------------------------------------------------------------------
1 |
5 |
6 | # Snap (deprecated)
7 |
8 | To install Semaphore via snap, run following command in terminal:
9 |
10 | ```bash
11 | sudo snap install semaphore
12 | ```
13 |
14 | Semaphore will be available by URL [https://localhost:3000](https://localhost:3000).
15 |
16 | But to log in, you should create an admin user. Use the following commands:
17 |
18 | ```bash
19 | sudo snap stop semaphore
20 |
21 | sudo semaphore user add --admin \
22 | --login john \
23 | --name=John \
24 | --email=john1996@gmail.com \
25 | --password=12345
26 |
27 | sudo snap start semaphore
28 | ```
29 |
30 | You can check the status of the Semaphore service using the following command:
31 |
32 | ```bash
33 | sudo snap services semaphore
34 | ```
35 |
36 | It should print the following table:
37 |
38 | ```
39 | Service Startup Current Notes
40 | semaphore.semaphored enabled active -
41 | ```
42 |
43 | After installation, you can set up Semaphore via [Snap Configuration](https://snapcraft.io/docs/configuration-in-snaps). Use the following command to see your Semaphore configuration:
44 |
45 | ```bash
46 | sudo snap get semaphore
47 | ```
48 |
49 | List of available options you can find in [Configuration options reference](../configuration.md#configuration-options).
50 |
51 | ----
52 |
--------------------------------------------------------------------------------
/src/administration-guide/installation_manually.md:
--------------------------------------------------------------------------------
1 | # Manually installing Semaphore
2 |
3 | ----
4 |
5 | **Content:**
6 |
7 | * [Service User](./installation_manually.md#service-user)
8 | * [Python3](./installation_manually.md#python3)
9 | * [Ansible Collections & Roles](./installation_manually.md#ansible-collections--roles)
10 | * [Reverse Proxy](./installation_manually.md#reverse-proxy)
11 | * [Systemd Service](./installation_manually.md#extended-systemd-service)
12 | * [Troubleshooting](./installation_manually.md#troubleshooting)
13 |
14 | ----
15 |
16 | This documentation goes into the details on how to set-up Semaphore when using these installation methods:
17 |
18 | * [Package manager](./installation.md#package-manager)
19 | * [Binary file](./installation.md#binary-file)
20 |
21 | The Semaphore software-package is just a part of the whole system needed to successfully run Ansible with it.
22 |
23 | The Python3- and Ansible-Execution-Environment are also very important!
24 |
25 | NOTE: There are [existing Ansible-Galaxy Roles](https://galaxy.ansible.com/search?deprecated=false&keywords=ansible%20semaphore&order_by=-relevance&page=1) that handle this setup-logic for you or can be used as a base-template for your own Ansible Role!
26 |
27 | ----
28 |
29 | ## Service User
30 |
31 | Semaphore does not need to be run as user `root` - so you shouldn't.
32 |
33 | **Benefits** of using a service user:
34 | * Has its own user-config
35 | * Has its own environment
36 | * Processes easily identifiable
37 | * Gained system security
38 |
39 | You can create a system user either manually by using `adduser` or using the [ansible.builtin.user](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/user_module.html) module.
40 |
41 | In this documentation we will assume:
42 | * the service user creates is named `semaphore`
43 | * it has the shell `/bin/bash` set
44 | * its home directory is `/home/semaphore`
45 |
46 | ### Troubleshooting
47 |
48 | If the Ansible execution of Semaphore is failing - you will need to troubleshoot it in the context of the service user.
49 |
50 | You have multiple options to do so:
51 |
52 | * Change your whole shell session to be in the user's context:
53 |
54 | ```bash
55 | sudo su --login semaphore
56 | ```
57 |
58 | * Run a single command in the user's context:
59 |
60 | ```bash
61 | sudo --login -u semaphore
51 | The expression
53 |
54 | ### Troubleshooting
55 |
56 | Use `ldapwhoami` tool to check if your **BindDN** works:
57 |
58 | ```bash
59 | ldapwhoami\
60 | -H ldap://ldap.com:389\
61 | -D "CN=your_ldap_binddn_value_in_config"\
62 | -x\
63 | -W
64 | ```
65 |
66 | It will ask interactively for the password, and should return code **0** and echo out the **DN** as specified.
67 |
68 | "username_claim": "|" generates a random username for each user who logs in through the provider.
52 |
69 | Please read Troubleshooting section if you have issues with LDAP.
70 |
71 |
72 |
73 | ## Example: Using OpenLDAP Server
74 |
75 | Run the following command to start your own LDAP server with an admin account and an additional user:
76 |
77 | ```
78 | docker run -d --name openldap \
79 | -p 1389:1389 \
80 | -p 1636:1636 \
81 | -e LDAP_ADMIN_USERNAME=admin \
82 | -e LDAP_ADMIN_PASSWORD=pwd \
83 | -e LDAP_USERS=user1 \
84 | -e LDAP_PASSWORDS=pwd \
85 | -e LDAP_ROOT=dc=example,dc=org \
86 | -e LDAP_ADMIN_DN=cn=admin,dc=example,dc=org \
87 | bitnami/openldap:latest
88 | ```
89 |
90 | Your LDAP configuration for Semaphore UI should be as follows:
91 |
92 | ```json
93 | {
94 | "ldap_binddn": "cn=admin,dc=example,dc=org",
95 | "ldap_bindpassword": "pwd",
96 | "ldap_server": "ldap-server.com:1389",
97 | "ldap_searchdn": "dc=example,dc=org",
98 | "ldap_searchfilter": "(&(objectClass=inetOrgPerson)(uid=%s))",
99 | "ldap_mappings": {
100 | "mail": "{{ .cn }}@ldap.your-domain.com",
101 | "uid": "|",
102 | "cn": "cn"
103 | },
104 | "ldap_enable": true,
105 | "ldap_needtls": false
106 | }
107 | ```
108 |
109 | To run Semaphore in Docker, use the following LDAP configuration:
110 |
111 |
112 | ```
113 | docker run -d -p 3000:3000 --name semaphore \
114 | -e SEMAPHORE_DB_DIALECT=bolt \
115 | -e SEMAPHORE_ADMIN=admin \
116 | -e SEMAPHORE_ADMIN_PASSWORD=changeme \
117 | -e SEMAPHORE_ADMIN_NAME=Admin \
118 | -e SEMAPHORE_ADMIN_EMAIL=admin@localhost \
119 | -e SEMAPHORE_LDAP_ENABLE=yes \
120 | -e SEMAPHORE_LDAP_SERVER=ldap-server.com:1389 \
121 | -e SEMAPHORE_LDAP_BIND_DN=cn=admin,dc=example,dc=org \
122 | -e SEMAPHORE_LDAP_BIND_PASSWORD=pwd \
123 | -e SEMAPHORE_LDAP_SEARCH_DN=dc=example,dc=org \
124 | -e 'SEMAPHORE_LDAP_SEARCH_FILTER=(&(objectClass=inetOrgPerson)(uid=%s))' \
125 | -e 'SEMAPHORE_LDAP_MAPPING_MAIL={{ .cn }}@ldap.your-domain.com' \
126 | -e 'SEMAPHORE_LDAP_MAPPING_UID=|' \
127 | -e 'SEMAPHORE_LDAP_MAPPING_CN=cn' \
128 | semaphoreui/semaphore:latest
129 | ```
130 |
131 |
--------------------------------------------------------------------------------
/src/administration-guide/logs.md:
--------------------------------------------------------------------------------
1 | # Logs
2 |
3 | Semaphore writes server logs to **stdout** and stores **Task** and **Activity** logs in a **database**, centralizing key log information and eliminating the need to back up log files separately. The only data stored on the file system is caching data.
4 |
5 | ---
6 |
7 | ## Server log
8 |
9 | Semaphore does not log to files. Instead, all application logs are written to **stdout**.
10 | If Semaphore is running as a systemd service, you can view the logs with the following command:
11 |
12 | ```bash
13 | journalctl -u semaphore.service -f
14 | ```
15 |
16 | This provides a live (streaming) view of the logs.
17 |
18 | ---
19 |
20 | ## Activity log
21 |
22 | The Activity Log captures all user actions performed in Semaphore, including:
23 |
24 | - Adding or removing resources (e.g., Templates, Inventories, Repositories).
25 | - Adding or removing team members.
26 | - Starting or stopping tasks.
27 |
28 | ### Pro version 2.10 and later
29 |
30 | **Semaphore Pro** 2.10+ supports writing the Activity Log and Task log to a file. To enable this, add the following configuration to your `config.json`:
31 |
32 | ```json
33 | {
34 | "log": {
35 | "events": {
36 | "enabled": true,
37 | "logger": {
38 | "filename": "./events.log"
39 | // other logger options
40 | }
41 | },
42 | "tasks": {
43 | "enabled": true,
44 | "logger": {
45 | "filename": "./tasks.log"
46 | // other logger options
47 | }
48 | }
49 | }
50 | }
51 | ```
52 |
53 |
54 | Or you can do this using following environment variables:
55 |
56 | ```bash
57 | export SEMAPHORE_EVENT_LOG_ENABLED=True
58 | export SEMAPHORE_EVENT_LOG_PATH=./events.log
59 |
60 | export SEMAPHORE_TASK_LOG_ENABLED=True
61 | export SEMAPHORE_TASK_LOG_PATH=./tasks.log
62 | ```
63 |
64 | #### Events logging options
65 |
66 | | Parameter | Environment Variables | Description |
67 | | --------------------- | --------------------- | --------------------- |
68 | | `enabled` | `SEMAPHORE_EVENT_LOG_ENABLED` | Enable event logging to file. |
69 | | `format` | `SEMAPHORE_EVENT_LOG_FORMAT` | Log record format. Can be `raw` or `json`. |
70 | | `logger` | `SEMAPHORE_EVENT_LOG_LOGGER` | Logger opitons. |
71 |
72 | #### Tasks logging options
73 |
74 | | Parameter | Environment Variables | Description |
75 | | --------------------- | --------------------- | --------------------- |
76 | | `enabled` | `SEMAPHORE_TASK_LOG_ENABLED` | Enable task logging to file. |
77 | | `format` | `SEMAPHORE_TASK_LOG_FORMAT` | Log record format. Can be `raw` or `json`. |
78 | | `logger` | `SEMAPHORE_TASK_LOG_LOGGER` | Logger opitons. |
79 |
80 | #### Logger options
81 |
82 | | Parameter | Type | Description |
83 | | --------------------- | ------- | --------------------- |
84 | | `filename` | String | Path and name of the file to write logs to. Backup log files will be retained in the same directory. It uses
70 | The expression
72 |
73 | ## Sign in screen
74 |
75 | For each of the configured providers, an additional login button is added to the login page:
76 |
77 | 
78 |
--------------------------------------------------------------------------------
/src/administration-guide/openid/authelia.md:
--------------------------------------------------------------------------------
1 |
5 |
6 | # Authelia config
7 |
8 | Authelia `config.yaml`:
9 | ```yaml
10 | identity_providers:
11 | oidc:
12 | claims_policies:
13 | semaphore_claims_policy:
14 | id_token:
15 | - groups
16 | - email
17 | - email_verified
18 | - alt_emails
19 | - preferred_username
20 | - name
21 | clients:
22 | - client_id: semaphore
23 | client_name: Semaphore
24 | client_secret: 'your_secret'
25 | claims_policy: semaphore_claims_policy
26 | public: false
27 | authorization_policy: two_factor
28 | redirect_uris:
29 | - https://your-semaphore-domain.com/api/auth/oidc/authelia/redirect
30 | scopes:
31 | - openid
32 | - profile
33 | - email
34 | userinfo_signed_response_alg: none
35 | ```
36 |
37 | Semaphore `config.json`:
38 | ```json
39 | "oidc_providers": {
40 | "authelia": {
41 | "display_name": "Authelia",
42 | "provider_url": "https://your-authelia-domain.com",
43 | "client_id": "semaphore",
44 | "client_secret": "your_secret",
45 | "redirect_url": "https://your-semaphore-domain.com/api/auth/oidc/authelia/redirect"
46 | }
47 | },
48 | ```
49 |
--------------------------------------------------------------------------------
/src/administration-guide/openid/authentik.md:
--------------------------------------------------------------------------------
1 |
5 |
6 | # Authentik config
7 |
8 | `config.json`:
9 |
10 | ```yaml
11 | {
12 | "oidc_providers": {
13 | "authentik": {
14 | "display_name": "Sign in with Authentik",
15 | "provider_url": "https://authentik.example.com/application/o/"username_claim": "|" generates a random username for each user who logs in through the provider.
71 |
133 | Use the HTTPS protocol for communication between the server and the runner, especially if they are not on the same private network.
134 |
135 |
--------------------------------------------------------------------------------
/src/administration-guide/security.md:
--------------------------------------------------------------------------------
1 | # 🔐 Security
2 |
3 | ## Introduction
4 |
5 | Security is a top priority in Semaphore UI. Whether you're automating critical infrastructure tasks or managing team access to sensitive systems, Semaphore UI is designed to provide robust, secure operations out of the box. This section outlines how Semaphore handles security and what you should consider when deploying it in production.
6 |
7 | ## Authentication & authorization
8 |
9 | Semaphore supports secure authentication and flexible authorization mechanisms:
10 |
11 | - **Login methods:**
12 | - **Username/password**Default method using credentials stored in the Semaphore database. Passwords are hashed using a strong algorithm (bcrypt). 13 | 14 | - **LDAP**
Allows integration with enterprise directory services. Supports user/group filtering and secure connections via LDAPS. 15 | 16 | - **OpenID Connect (OIDC)**
Enables single sign-on with identity providers like Google, Azure AD, or Keycloak. Supports custom claims and group mappings. 17 | 18 | - **Two-Factor authentication (2FA)**
TOTP-based 2FA is available and recommended for all users. 19 | 20 | - **Role-based access control**
You can assign different roles to users such as Admin, Maintainer, or Viewer, limiting access based on responsibility. 21 | 22 | - **Session management**
Sessions are protected with secure HTTP cookies. Session expiration and logout mechanisms ensure minimal exposure. 23 | 24 | 25 | ## Secrets & credentials 26 | 27 | Managing secrets securely is a core feature: 28 | 29 | - **Encrypted key store**
Credentials and secret variables are encrypted at rest using AES encryption. 30 | 31 | - **Environment isolation**
Secrets are only passed to jobs at runtime and are not exposed to the container environment directly. 32 | 33 | - **SSH keys and tokens**
Users are responsible for uploading valid SSH keys and tokens. These are encrypted and only used when running tasks. 34 | 35 | 36 | ## Running untrusted code / playbooks 37 | 38 | Semaphore runs user-defined playbooks and commands, which can be risky: 39 | 40 | - **Container isolation**
Tasks are executed in isolated Docker containers. These containers have no access to the host system. 41 | 42 | - **Least privilege**
Containers run with minimal permissions and can be restricted further using Docker flags. 43 | 44 | - **Chroot execution**
Semaphore can execute tasks inside a chroot jail to further isolate the execution environment from the host system. 45 | 46 | - **Task process user**
Tasks can be executed under a dedicated non-root system user (e.g., `semaphore`) to reduce the impact of potential exploits. This is optional and can be configured based on system policies. 47 | 48 | 49 | ## Secure Deployment 50 | 51 | To ensure Semaphore is securely deployed: 52 | 53 | - **Use HTTPS**
54 | Semaphore supports HTTPS both via its **built-in TLS support** and through a **reverse proxy like Nginx**. It is strongly recommended to enable HTTPS in production. 55 | 56 | To enable built-in HTTPS support add following block to **config.json**: 57 | ```json 58 | { 59 | ... 60 | "tls": { 61 | "enabled": true, 62 | "cert_file": "/path/to/cert/example.com.cert", 63 | "key_file": "/path/to/key/example.com.key" 64 | } 65 | ... 66 | } 67 | ``` 68 | 69 | - **Run behind a firewall**
Limit access to the Semaphore UI and database to only trusted IPs. 70 | 71 | - **Database security**
Use strong passwords and restrict database access to Semaphore only. 72 | 73 | ## Updates & patch management 74 | 75 | Security updates are published regularly: 76 | 77 | - **Stay updated**
Always use the latest stable release. 78 | 79 | - **Changelog**
Review changes on GitHub before updating. 80 | 81 | - **Automatic updates**
If using Docker, consider automation pipelines for regular updates. 82 | 83 | 90 | 91 | 98 | 99 | 105 | 106 | 113 | 114 | ## Reporting Vulnerabilities 115 | 116 | Found a vulnerability? Help us keep Semaphore secure: 117 | 118 | - **Responsible disclosure**
Please email us at `security@semaphoreui.com`. 119 | 120 | - **No public exploits**
Do not share vulnerabilities publicly until patched. 121 | 122 | - **Acknowledgments**
Security researchers may be acknowledged in release notes if desired. 123 | 124 | -------------------------------------------------------------------------------- /src/administration-guide/security/apache.md: -------------------------------------------------------------------------------- 1 | 6 | 7 | 8 | # Apache config 9 | 10 | Make sure you have enabled following Apache modules: 11 | 12 | ```bash 13 | sudo a2enmod proxy 14 | sudo a2enmod proxy_http 15 | sudo a2enmod proxy_wstunnel 16 | ``` 17 | 18 | Add following virtual host to your Apache configuration: 19 | 20 | ``` 21 |
71 | Coming soon
72 |
73 |
74 | ### Binary
75 |
76 | Download a `*.tar.gz` for your platform from [Releases page](https://github.com/semaphoreui/semaphore/releases). Unpack the binary to the directory where your old Semaphore binary is located.
77 |
78 | {{#tabs }}
79 | {{#tab name="Linux (x64)" }}
80 | ```
81 | wget https://github.com/semaphoreui/semaphore/releases/\
82 |
83 | download/v2.13.14/semaphore_2.13.14_linux_amd64.tar.gz
84 |
85 | tar xf semaphore_2.13.14_linux_amd64.tar.gz
86 | ```
87 | {{#endtab }}
88 |
89 | {{#tab name="Linux (ARM64)" }}
90 | ```
91 | wget https://github.com/semaphoreui/semaphore/releases/\
92 |
93 | download/v2.13.14/semaphore_2.13.14_linux_arm64.tar.gz
94 |
95 | tar xf semaphore_2.13.14_linux_arm64.tar.gz
96 | ```
97 | {{#endtab }}
98 |
99 | {{#tab name="Windows (x64)" }}
100 | ```
101 | Invoke-WebRequest `
102 | -Uri ("https://github.com/semaphoreui/semaphore/releases/" +
103 | "download/v2.13.14/semaphore_2.13.14_windows_amd64.zip") `
104 | -OutFile semaphore.zip
105 |
106 | Expand-Archive -Path semaphore.zip -DestinationPath ./
107 | ```
108 | {{#endtab }}
109 | {{#endtabs }}
110 |
111 |
--------------------------------------------------------------------------------
/src/faq/troubleshooting.md:
--------------------------------------------------------------------------------
1 | # Troubleshooting
2 |
3 | ## 1. Renner prints error 404
4 |
5 | ### How to fix
6 |
7 | [Getting 401 error code from Runner](https://github.com/semaphoreui/semaphore/discussions/1873?converting=1)
8 |
9 | ---
10 |
11 | ## 2. Gathering Facts issue for localhost
12 |
13 | The issue can occur on Semaphore UI installed via [Snap](https://snapcraft.io/semaphore) or [Docker](https://hub.docker.com/r/semaphoreui/semaphore).
14 |
15 | ```
16 | 4:10:16 PM
17 | TASK [Gathering Facts] *********************************************************
18 | 4:10:17 PM
19 | fatal: [localhost]: FAILED! => changed=false
20 | ```
21 |
22 | ### Why this happens
23 |
24 | For more information about localhost use in Ansible, read this article [Implicit 'localhost'](https://docs.ansible.com/ansible/latest/inventory/implicit_localhost.html).
25 |
26 | Ansible tries to gather facts locally, but Ansible is located in a limited isolated container which doesn't allow this.
27 |
28 | ### How to fix this
29 |
30 | There are two ways:
31 |
32 | 1. Disable facts gathering:
33 |
34 | ```yaml
35 | - hosts: localhost
36 | gather_facts: False
37 | roles:
38 | - ...
39 | ```
40 |
41 | 2. Explicitly set the connection type to **ssh**:
42 | ```
43 | [localhost]
44 | 127.0.0.1 ansible_connection=ssh ansible_ssh_user=your_localhost_user
45 | ```
46 | ---
47 | ## 4. panic: pq: SSL is not enabled on the server
48 |
49 | This means that your Postgres doesn't work by SSL.
50 |
51 | ### How to fix this
52 |
53 | Add option `sslmode=disable` to the configuration file:
54 |
55 | ```json
56 | "postgres": {
57 | "host": "localhost",
58 | "user": "pastgres",
59 | "pass": "pwd",
60 | "name": "semaphore",
61 | "options": {
62 | "sslmode": "disable"
63 | }
64 | },
65 | ```
66 |
67 |
68 | ---
69 |
70 |
71 | ## 5. fatal: bad numeric config value '0' for 'GIT_TERMINAL_PROMPT': invalid unit
72 |
73 | This means that you are trying to access a repository over HTTPS that requires authentication.
74 |
75 | ### How to fix this
76 |
77 | * Go to **Key Store** screen.
78 | * Create a new key `Login with password` type.
79 | * Specify your login for GitHub/BitBucket/etc.
80 | * Specify the password. You can't use your account password for GitHub/BitBucket, you should use a Personal Access Token (PAT) instead of it. Read more [here](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token).
81 | * After creating the key, go to the **Repositories** screen, find your repository and specify the key.
82 |
83 |
84 | ---
85 |
86 |
87 |
88 | ## 6. unable to read LDAP response packet: unexpected EOF
89 |
90 | Most likely, you are trying to connect to the LDAP server using an insecure method, although it expects a secure connection (via TLS).
91 |
92 | ### How to fix this
93 |
94 | Enable TLS in your `config.json` file:
95 |
96 | ```json
97 | ...
98 | "ldap_needtls": true
99 | ...
100 | ```
101 |
102 | ---
103 |
104 | ## 7. LDAP Result Code 49 "Invalid Credentials"
105 |
106 | You have the wrong password or `binddn`.
107 |
108 | ### How to fix this
109 |
110 | Use `ldapwhoami` tool and check if your binddn works:
111 |
112 | ```bash
113 | ldapwhoami\
114 | -H ldap://ldap.com:389\
115 | -D "CN=/your/ldap_binddn/value/in/config/file"\
116 | -x\
117 | -W
118 | ```
119 |
120 | It will ask interactively for the password and should return code **0** and echo out the **DN** as specified.
121 |
122 | You also can read the following articles:
123 | * [ldapsearch: Invalid credentials (49)](https://serverfault.com/q/771549/443463)
124 | * [https://github.com/semaphoreui/semaphore/issues/906](https://github.com/semaphoreui/semaphore/issues/906)
125 |
126 | ---
127 |
128 | ## 8. LDAP Result Code 32 "No Such Object"
129 |
130 | Coming soon.
131 |
--------------------------------------------------------------------------------
/src/user-guide/admin/README.md:
--------------------------------------------------------------------------------
1 | # Admin
2 |
--------------------------------------------------------------------------------
/src/user-guide/admin/runners.md:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/semaphoreui/semaphore-docs/ed8d380491d8e5a8ef71a845e3214e8522f358e1/src/user-guide/admin/runners.md
--------------------------------------------------------------------------------
/src/user-guide/admin/subscription.md:
--------------------------------------------------------------------------------
1 | # Subscription 🅿
2 |
--------------------------------------------------------------------------------
/src/user-guide/admin/tasks.md:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/semaphoreui/semaphore-docs/ed8d380491d8e5a8ef71a845e3214e8522f358e1/src/user-guide/admin/tasks.md
--------------------------------------------------------------------------------
/src/user-guide/admin/users.md:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/semaphoreui/semaphore-docs/ed8d380491d8e5a8ef71a845e3214e8522f358e1/src/user-guide/admin/users.md
--------------------------------------------------------------------------------
/src/user-guide/environment.md:
--------------------------------------------------------------------------------
1 | # Variable Groups
2 |
3 | The Variable Groups section of Semaphore is a place to store additional variables for an inventory and must be stored in JSON format.
4 |
5 | All task templates require an variable group to be defined even if it is empty.
6 |
7 | ## Create an variable group
8 | 1. Click on the Variable Group tab.
9 | 2. Click on the New Variable Group button.
10 | 3. Name the Variable Group and type or paste in valid JSON variables. If you just need an empty Variable Group type in ```{}```.
11 |
12 | ## Updating an variable group
13 | 1. Click on the Variable Groups tab.
14 | 2. Click the pencil icon.
15 | 3. Make changes and click save.
16 |
17 | ## Deleting the variable group
18 | Before you remove an variable proup, you must remove all resources tied to it.
19 | If you are not sure which resources are being used in an variable group, follow steps 1 and 2 below. It will show you which resources are being used, with links to those resources.
20 |
21 | 1. Click on the Variable Group.
22 | 2. Click the trash can icon next to the Variable Group.
23 | 3. Click Yes if you are sure you want to remove the variable group.
24 |
25 | ## Using Variable Groups - Terraform
26 | When you want utilize a stored variable group variable or secret in your terraform template you must prefix the name with `TF_VAR_` for the terraform script to use it.
27 |
28 | **Example**
29 | Passing Hetzner Cloud API key to OpenTofu/Terraform playbook.
30 |
31 | 1. Click on Variable Group
32 | 2. Click `New Group`
33 | 3. Click on `Secrets` tab
34 | 4. Add `TF_VAR_hcloud_token` and add you `secret` in the hidden field
35 | 5. Click Save
36 |
37 | We will call our secret `TF_VAR_hcloud_token` as `var.hcloud_token` in
38 | hetzner.tf
39 | ```
40 | terraform {
41 | required_providers {
42 | hcloud = {
43 | source = "hetznercloud/hcloud"
44 | version = "~> 1.45"
45 | }
46 | }
47 | }
48 |
49 | # Declare the variable
50 | variable "hcloud_token" {
51 | type = string
52 | description = "Hetzner Cloud API token"
53 | sensitive = true # This prevents the token from being displayed in logs
54 | }
55 |
56 | provider "hcloud" {
57 | token = var.hcloud_token
58 | }
59 |
60 | # Create a new server running debian
61 | resource "hcloud_server" "webserver" {
62 | name = "webserver"
63 | image = "ubuntu-24.04"
64 | server_type = "cpx11"
65 | location = "ash"
66 | ssh_keys = [ "mysshkey" ]
67 | public_net {
68 | ipv4_enabled = true
69 | ipv6_enabled = true
70 | }
71 | }
72 | ```
73 |
--------------------------------------------------------------------------------
/src/user-guide/integrations.md:
--------------------------------------------------------------------------------
1 | # Integrations
2 |
3 | Integrations allow establishing interaction between Semaphore and external services, such as GitHub and GitLab.
4 |
5 | 
6 |
7 | Using integration, you can trigger a specific template by calling a special endpoint (alias), for which you can configure one of the following authentication methods:
8 | * GitHub Webhooks
9 | * Token
10 | * HMAC
11 | * No authentication
12 |
13 | The alias represents a URL in the following format: `/api/integrations/
29 | This type of secret can be used as Personal Access Token (PAT) or secret string. Simply leave the Login field empty.
30 |
31 |
32 | ### 3. None
33 | This is used as a filler for Repos that do not require authentication, like an Open-Source Repository on GitLab.
34 |
--------------------------------------------------------------------------------
/src/user-guide/key-store/gitlab.md:
--------------------------------------------------------------------------------
1 |
6 |
7 | # GitLab
8 |
9 | ## GitLab repository access token
10 |
11 |
--------------------------------------------------------------------------------
/src/user-guide/netbox-dynamic-inventory.md:
--------------------------------------------------------------------------------
1 | # Netbox Dynamic Inventory Integration with Semaphore
2 |
3 | 
4 | 
5 | 
6 |
7 | ## 🛠 Key Features
8 |
9 | This repository demonstrates the use of the `netbox.netbox.nb_inventory` plugin to create a dynamic inventory in Semaphore. It enables automatic synchronization of data from Netbox, simplifying the management of your infrastructure and the execution of Ansible playbooks.
10 |
11 | ## 🔧 Setup
12 |
13 | ### Requirements
14 |
15 | - Access to Semaphore
16 | - Access to Netbox with configured API
17 |
18 | ### 🔑 Netbox Setup
19 |
20 | Ensure your Netbox is configured and accessible for API interaction. Obtain an API token which will be used to authenticate requests.
21 |
22 | ### 📡 Configuration in Semaphore
23 |
24 | 1. In Semaphore, go to the inventory section.
25 | 2. Create a new inventory.
26 | 3. Enter the following settings for the plugin configuration:
27 |
28 | ```yaml
29 | plugin: netbox.netbox.nb_inventory
30 | api_endpoint: http://your_netbox_url_here
31 | token: YOUR_NETBOX_API_TOKEN
32 | validate_certs: False
33 | config_context: False
34 | ```
35 |
36 | Replace `http://your_netbox_url_here` and `YOUR_NETBOX_API_TOKEN` with the actual data from your Netbox.
37 |
38 | ## 🚀 Usage
39 |
40 | Once configured, you can run Ansible playbooks in Semaphore using the dynamic inventory which automatically updates host data from your Netbox.
41 |
42 | ## 📚 Further Documentation
43 |
44 | Learn more about the `netbox.netbox.nb_inventory` plugin and its capabilities in the [official Ansible documentation](https://docs.ansible.com/ansible/latest/collections/netbox/netbox/nb_inventory_inventory.html).
45 |
--------------------------------------------------------------------------------
/src/user-guide/projects.md:
--------------------------------------------------------------------------------
1 | # Projects
2 |
3 | A project is a place to separate management activity.
4 |
5 | All Semaphore activities occur within the context of a project.
6 |
7 | Projects are independent from one another, so you can use them to organize unrelated systems within a single Semaphore installation.
8 |
9 | This can be useful for managing different teams, infrastructures, environments or applications.
10 |
11 | 
12 |
13 |
--------------------------------------------------------------------------------
/src/user-guide/projects/activity.md:
--------------------------------------------------------------------------------
1 |
5 |
6 | # Activity
7 |
--------------------------------------------------------------------------------
/src/user-guide/projects/history.md:
--------------------------------------------------------------------------------
1 |
5 |
6 | # History
7 |
--------------------------------------------------------------------------------
/src/user-guide/projects/runners.md:
--------------------------------------------------------------------------------
1 |
5 |
6 | # Runners (Pro)
7 |
8 |
--------------------------------------------------------------------------------
/src/user-guide/projects/settings.md:
--------------------------------------------------------------------------------
1 |
5 |
6 | # Settings
7 |
--------------------------------------------------------------------------------
/src/user-guide/repositories.md:
--------------------------------------------------------------------------------
1 | # Repositories
2 |
3 | A Repository is a place to store and manage Ansible content like playbooks and roles.
4 |
5 | 
6 |
7 | Semaphore understands Repositories that are:
8 | * a local file system (`/path/to/the/repo`)
9 | * a local Git repository (`file://`)
10 | * a remote Git Repository that is accessed over HTTPS (`https://`), SSH(`ssh://`)
11 | * `git://` protocol supported, but it is not recommended for security reasons.
12 |
13 | All Task Templates require a Repository in order to run.
14 |
15 | ## Authentication
16 | If you are using a remote Repository that requires authentication, you will need to configure a key in the **Key Store** section of Semaphore.
17 |
18 | For remote Repositories that use SSH, you will need to use your SSH key in the **Key Store**.
19 |
20 | For Remote Repositories that do not have authentication, you can create a Key with the type of `None`.
21 |
22 | ## Creating a New Repository
23 | 1. Make sure you have configured the key for the Repository you are about to add in the key store section.
24 |
25 | 2. Go to the Repositories section of Semaphore, click the **New Repository** button in the upper right hand corner.
26 |
27 | 3. Configure the Repository:
28 | * Name Repository
29 | * Add the URL. The URL must start with the following:
30 | * `/path/to/the/repo` for a local folder on the file system
31 | * `https://` for a remote Git Repository accessed over HTTPS
32 | * `ssh://` for a remote Git Repository accessed over SSH
33 | * `file://` for a local Git Repository
34 | * `git://` for a remote Git Repository accessed over Git protocol
35 | * Set the branch of the Repository, if you are not sure what it should be, it is probably master or main
36 | * Select the **Access Key** you configured prior to setting up this Repository.
37 |
38 | 4. Click Save once everything is configured.
39 |
40 | ## Editing an Existing Repository
41 | 1. Go to the Repositories section of Semaphore.
42 |
43 | 2. Click on the pencil icon next to the Repository you wish to change, then you will be presented with the Repository configuration.
44 |
45 | ## Deleting a Repository
46 | Make sure the Repository that is about to be delete is not in use by any Task Templates.
47 | A Repository cannot be deleted if it is used in any Task Templates:
48 | 1. Go to the Repositories section of Semaphore.
49 |
50 | 2. Click on the trash can icon on of the Repository you wish to delete.
51 |
52 | 3. Click Yes on the confirmation pop-up if you are sure you want this Repository to be deleted.
53 |
54 | ## Requirements
55 | Upon project initialization Semaphore searches for and installs Ansible roles and collections from requirements.yml in the following locations and order.
56 |
57 | ### Roles
58 |
59 | *  24 | 25 | 4. Go to the **Repositories** section and click the **New Repository** button. 26 | 27 | 5. Enter HTTPS URL of the repository (`https://bitbucket.org/path/to/repo`), enter correct branch and select previously created **Access Key**.
 -------------------------------------------------------------------------------- /src/user-guide/schedules.md: -------------------------------------------------------------------------------- 1 | # Schedules 2 | 3 | The schedule function in Semaphore allows to automate the execution of templates (e.g. playbook runs) at predefined intervals. This feature allows to implement routine automation tasks, such as regular backups, compliance checks, system updates, and more. 4 | 5 | Make sure to restart the Semaphore service after making changes for them to take effect. 6 | 7 | ## Setup and configuration 8 | 9 | ## Timezone configuration 10 | 11 | By default, the schedule feature operates in the UTC timezone. However, this can be customized to match your local timezone or specific requirements. 12 | 13 | You can change the timezone by updating the configuration file or setting an environment variable: 14 | 15 | 1. **Using the configuration file**: 16 | Add or update the `timezone` field in your Semaphore configuration file: 17 | ```json 18 | { 19 | "schedule": { 20 | "timezone": "America/New_York" 21 | } 22 | } 23 | ``` 24 | 25 | 2. **Using an environment variable**: 26 | Set the `SEMAPHORE_SCHEDULE_TIMEZONE` environment variable: 27 | ```bash 28 | export SEMAPHORE_SCHEDULE_TIMEZONE="America/New_York" 29 | ``` 30 | 31 | For a list of valid timezone values, refer to the [IANA Time Zone Database](https://www.iana.org/time-zones). 32 | 33 | ### Accessing the schedule feature 34 | 35 | 1. Log in to your Ansible Semaphore web interface 36 | 2. Navigate to the "Schedule" tab in the main navigation menu 37 | 3. Click the "New Schedule" button in the top right corner to create a new schedule 38 | 39 |  40 | 41 | ### Creating a new schedule 42 | 43 | When creating a new schedule, you'll need to configure the following options: 44 | 45 | | Field | Description | 46 | |-------|-------------| 47 | | Name | A descriptive name for the scheduled task | 48 | | Template | The specific Task Template to execute | 49 | | Timing | Either in cron format for more fexibility or using the built-in options for common intervals | 50 | 51 |   52 | 53 | ### Cron format syntax 54 | 55 | The schedule uses standard cron syntax with five fields: 56 | 57 | ``` 58 | ┌─────── minute (0-59) 59 | │ ┌────── hour (0-23) 60 | │ │ ┌───── day of month (1-31) 61 | │ │ │ ┌───── month (1-12) 62 | │ │ │ │ ┌───── day of week (0-6) (Sunday=0) 63 | │ │ │ │ │ 64 | │ │ │ │ │ 65 | * * * * * 66 | ``` 67 | 68 | Examples: 69 | - `*/15 * * * *` - Run every 15 minutes 70 | - `0 2 * * *` - Run at 2:00 AM every day 71 | - `0 0 * * 0` - Run at midnight on Sundays 72 | - `0 9 1 * *` - Run at 9:00 AM on the first day of every month 73 | 74 | Very helpful cron expression generator: [https://crontab.guru/](https://crontab.guru/) 75 | 76 | ## Use cases 77 | 78 | ### System maintenance 79 | 80 | ```yaml 81 | # Example playbook for system updates 82 | --- 83 | - hosts: all 84 | become: yes 85 | tasks: 86 | - name: Update apt cache 87 | apt: 88 | update_cache: yes 89 | 90 | - name: Upgrade all packages 91 | apt: 92 | upgrade: yes 93 | 94 | - name: Remove dependencies that are no longer required 95 | apt: 96 | autoremove: yes 97 | ``` 98 | 99 | Schedule this playbook to run weekly during off-hours to ensure systems stay up-to-date. 100 | 101 | ### Backup operations 102 | 103 | Create schedules for database backups with different frequencies: 104 | - Daily backups that retain for one week 105 | - Weekly backups that retain for one month 106 | - Monthly backups that retain for one year 107 | 108 | ### Compliance checks 109 | 110 | Schedule regular compliance scans to ensure systems meet security requirements: 111 | 112 | ```yaml 113 | # Example compliance check playbook 114 | --- 115 | - hosts: all 116 | tasks: 117 | - name: Run compliance checks 118 | script: /path/to/compliance_script.sh 119 | 120 | - name: Collect compliance reports 121 | fetch: 122 | src: /var/log/compliance-report.log 123 | dest: reports/{{ inventory_hostname }}/ 124 | flat: yes 125 | ``` 126 | 127 | ### Environment provisioning and cleanup 128 | 129 | For development or testing environments. Schedule cloud environment creation in the morning and teardown in the evening to optimize costs. 130 | 131 | ## Best practices 132 | 133 | * Use descriptive names for schedules that indicate both function and timing (e.g. "Weekly-Backup-Sunday-2AM") 134 | * Avoid scheduling too many resource-intensive tasks concurrently 135 | * Consider the effect of long-running scheduled tasks on other schedules 136 | * Test schedules with short intervals before setting up production schedules with longer intervals 137 | * Document the purpose and expected outcomes of scheduled tasks 138 | -------------------------------------------------------------------------------- /src/user-guide/task-templates/README.md: -------------------------------------------------------------------------------- 1 | # Task Templates 2 | 3 | Templates define how to run Semaphore tasks. Currently the following task types are supported: 4 | 5 | * Playbook repository 6 | * Playbook filename 7 | * Inventory 8 | * Environment 9 | * Vault password file 10 | * Extra CLI arguments 11 | * and much more 12 | 13 |  14 | 15 | The task template can be one of the following types: 16 | 17 | * [Task](#task) 18 | * [Build](#build) 19 | * [Deploy](#deploy) 20 | 21 | ### Task 22 | 23 | Just runs specified playbooks with specified parameters. 24 | 25 | ### Build 26 | 27 | This type of template should be used to create [artifacts](https://en.wikipedia.org/wiki/Artifact\_\(software\_development\)). The start version of the artifact can be specified in a template parameter. Each run increments the artifact version. 28 | 29 | .png>) 30 | 31 | Semaphore doesn't support artifacts out-of-box, it only provides task versioning. You should implement the artifact creation yourself. Read the article [CI/CD](../../administration-guide/cicd.md) to know how to do this. 32 | 33 | ### Deploy 34 | 35 | This type of template should be used to deploy artifacts to the destination servers. Each `deploy` template is associated with a `build` template. 36 | 37 |  38 | 39 | This allows you to deploy a specific version of the artifact to the servers. 40 | 41 | ### Schedule 42 | 43 | You can set up task scheduling by specifying a cron schedule in the template settings. Cron expression format you can find in [documentation](https://pkg.go.dev/github.com/robfig/cron/v3#hdr-CRON\_Expression\_Format). 44 | 45 |  46 | 47 | #### Run a task when a new commit is added to the repository 48 | 49 | You can use cron to periodically check for new commits in the repository and trigger a task upon their arrival. 50 | 51 | For example you have source code of the app in the git repository. You can add it to **Repositories** and trigger the Build task for new commits. 52 | 53 |  54 | -------------------------------------------------------------------------------- /src/user-guide/task-templates/apps/ansible.md: -------------------------------------------------------------------------------- 1 | 5 | 6 | # Ansible 7 | 8 | Using Semaphore UI you can run Ansible playbooks. To do this, you need to create an **Ansible Playbook** Template. 9 | 10 | 1. Go go **Task Templates** section, click on **New Template** and then **Ansible Playbook**. 11 | 12 |  13 | 14 | 2. Set up the template. 15 | 16 | The template allows you to specify the following parameters: 17 | 18 | * Repository 19 | * Path to playbook file 20 | * Inventory 21 | * Variable Groups 22 | * Vaults 23 | * and much more 24 | 25 |  26 | 27 | An ansible-playbook template can be one of the following types: 28 | 29 | * [Task](#task) 30 | * [Build](#build) 31 | * [Deploy](#deploy) 32 | 33 | ### Task 34 | 35 | Just runs specified playbooks with specified parameters. 36 | 37 | ### Build 38 | 39 | This type of template should be used to create [artifacts](https://en.wikipedia.org/wiki/Artifact\_\(software\_development\)). The start version of the artifact can be specified in a template parameter. Each run increments the artifact version. 40 | 41 | .png>) 42 | 43 | Semaphore doesn't support artifacts out-of-box, it only provides task versioning. You should implement the artifact creation yourself. Read the article [CI/CD](../../administration-guide/cicd.md) to know how to do this. 44 | 45 | ### Deploy 46 | 47 | This type of template should be used to deploy artifacts to the destination servers. Each `deploy` template is associated with a `build` template. 48 | 49 |  50 | 51 | This allows you to deploy a specific version of the artifact to the servers. 52 | 53 | ### Schedule 54 | 55 | You can set up task scheduling by specifying a cron schedule in the template settings. Cron expression format you can find in [documentation](https://pkg.go.dev/github.com/robfig/cron/v3#hdr-CRON\_Expression\_Format). 56 | 57 |  58 | 59 | #### Run a task when a new commit is added to the repository 60 | 61 | You can use cron to periodically check for new commits in the repository and trigger a task upon their arrival. 62 | 63 | For example you have source code of the app in the git repository. You can add it to **Repositories** and trigger the Build task for new commits. 64 | 65 |  66 | -------------------------------------------------------------------------------- /src/user-guide/task-templates/apps/bash.md: -------------------------------------------------------------------------------- 1 | 5 | 6 | # Shell/Bash scripts 7 | 8 | Using Semaphore UI you can run Bash scripts. To do this, you need to create a **Bash Script Template**. 9 | 10 | 1. Go go Task Templates section and click the **New Template** button. 11 | 12 |  13 | 14 | 2. Set up the template and click the **Create** button. 15 | 16 |  17 | 18 | 3. You can now run your Bash script. -------------------------------------------------------------------------------- /src/user-guide/task-templates/apps/powershell.md: -------------------------------------------------------------------------------- 1 | 5 | 6 | # PowerShell 7 | -------------------------------------------------------------------------------- /src/user-guide/task-templates/apps/python.md: -------------------------------------------------------------------------------- 1 | 5 | 6 | # Python 7 | -------------------------------------------------------------------------------- /src/user-guide/task-templates/apps/terraform.md: -------------------------------------------------------------------------------- 1 | 5 | 6 | # Terraform/OpenTofu 7 | 8 | Using Semaphore UI you can run Terraform code. To do this, you need to create a **Terraform Code Template**. 9 | 10 | 1. Go go Task Templates section and click the **New Template** button. 11 | 12 |  13 | 14 | 2. Set up the template and click the **Create** button. 15 | 16 |  17 | 18 | 3. You can now run your Terraform code. -------------------------------------------------------------------------------- /src/user-guide/task-templates/apps/terraform/states.md: -------------------------------------------------------------------------------- 1 | 6 | 7 | # HTTP Backend (Pro) 8 | 9 | The Semaphore UI HTTP backend for Terraform securely stores and manages Terraform state files directly within Semaphore. Available in the Pro plan, it offers several key advantages. 10 | 11 | ## Features 12 | 13 | - **Secure State Storage**: State files are stored securely within Semaphore. 14 | - **State Locking**: Prevents concurrent modifications to the same state file. 15 | - **Version History**: Track changes to your infrastructure state over time. 16 | - **UI Integration**: Manage state files directly through the Semaphore interface. 17 | 18 | ## Configuration 19 | 20 | To use the Semaphore UI HTTP backend, add the following configuration to your Terraform configuration: 21 | 22 | ```hcl 23 | terraform { 24 | backend "http" { 25 | address = "https://
6 | To avoid losing access to a project, it’s recommended to have at least two team members with the Owner role.
7 |
8 |
9 | ---
10 |
11 | ## Team roles
12 |
13 | Every team member has exactly one of these four roles:
14 |
15 | - **Owner**
16 | - **Manager**
17 | - **Task Runner**
18 | - **Guest**
19 |
20 | Below are detailed descriptions of each role and its permissions.
21 |
22 | ### Owner
23 |
24 | - **Full permissions**25 | Owners can do anything within the project, including managing roles, adding/removing members, and configuring any project settings. 26 | 27 | - **Multiple owners**
28 | A project can have multiple Owners, ensuring there is more than one person with full privileges. 29 | 30 | - **Restrictions on self-removal**
31 | An Owner cannot remove themselves if they are the only Owner of the project. This prevents the project from being left without an Owner. 32 | 33 | - **Managing other wwners**
34 | Owners can manage (including remove or change roles of) all team members, including other Owners. 35 | 36 | ### Manager 37 | 38 | - **Broad project control:** Managers have almost the same permissions as Owners, allowing them to handle most day-to-day tasks and manage the project environment. 39 | 40 | - Managers **cannot**: 41 | - Remove the project. 42 | - Remove or change the roles of Owners. 43 | 44 | - **Typical use case:** Assign the Manager role to senior team members who need extensive access but don’t require the authority to delete the project or manage Owners. 45 | 46 | ### Task Runner 47 | 48 | - **Run tasks:** Task Runners can execute any task template that exists within the project. 49 | 50 | - **Read-only for other resources:** While they can run tasks, they only have read‐only access to other resources such as inventory, variables, repositories, etc. 51 | 52 | - **Typical use case:** Developers or QA engineers who need to trigger and monitor tasks but do not need the ability to modify project settings or manage team membership. 53 | 54 | ### Guest 55 | 56 | - **Read-only access:** Guests have read-only access to all project resources (e.g., viewing logs, inventories, dashboards). 57 | 58 | - **No write permissions:** They cannot modify settings, run tasks, or change roles. 59 | 60 | - **Typical use case:** Stakeholders or other collaborators who only need to view project status and details without making changes. 61 | 62 | --- 63 | 64 | ## Managing team members 65 | 66 | - **Inviting new members:** **Owners** and **Managers** can invite new users to join the team and assign them an initial role. 67 | 68 | - **Changing roles:** Owners can always change the roles of any team member. Managers can change the roles of **Task Runners** and **Guests**, but **not** other Managers or Owners. 69 | 70 | - **Removing members:** Owners and Managers can remove team members with lower roles. 71 | - An Owner can remove anyone (including other Owners), but cannot remove themselves if they are the sole Owner. 72 | - A Manager can remove **Task Runners** and **Guests**, but **not** other Managers or Owners. 73 | 74 | --- 75 | 76 | ## Best practices 77 | 78 | 1. **Maintain redundancy:** Assign the **Owner** role to at least two people to ensure continuous access and prevent a single point of failure. 79 | 2. **Follow principle of least privilege:** 80 | - Give team members the minimum role necessary for their tasks. 81 | - Use **Task Runner** or **Guest** roles for those who only need limited permissions. 82 | 3. **Review membership regularly:** 83 | - As team structures change, re‐evaluate roles. 84 | - Revoke access or downgrade roles for users who no longer need high‐level privileges. 85 | 4. **Use managers for day-to-day administration:** 86 | - Reserve the Owner role for a smaller group with ultimate authority. 87 | - Delegate routine project management tasks to Managers to reduce the risk of accidental major changes or project deletions. 88 | 89 | --- 90 | 91 | ## Frequently asked questions 92 | 93 | ### 1. Can an Owner remove another Owner? 94 | Yes, an Owner can remove or change the role of any other Owner, unless they are the only remaining Owner in the project. 95 | 96 | ### 2. Who can delete the project? 97 | Only **Owners** can delete a project. 98 | 99 | ### 3. Can Managers add or remove other Managers? 100 | No. Managers can only add or remove users with **Task Runner** or **Guest** roles. To manage Owners or other Managers, you must be an Owner. 101 | 102 | ### 4. What happens if I remove all Owners by accident? 103 | Semaphore UI prevents the removal of an Owner if it would leave the project with no Owners at all. There must be at least one Owner at all times. 104 | 105 | ### 5. Can Guests run tasks? 106 | No. Guests only have read‐only access and cannot trigger or manage tasks. 107 | -------------------------------------------------------------------------------- /theme/content.css: -------------------------------------------------------------------------------- 1 | .content img { 2 | border-radius: 6px; 3 | } 4 | 5 | .light .content img { 6 | box-shadow: 0 0 3px var(--searchbar-shadow-color); 7 | } 8 | 9 | hr { 10 | border: 0; 11 | border-bottom: 1px solid rgba(150,150,150,0.1); 12 | } 13 | 14 | .warning { 15 | color: var(--warning-border); 16 | } -------------------------------------------------------------------------------- /theme/favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/semaphoreui/semaphore-docs/ed8d380491d8e5a8ef71a845e3214e8522f358e1/theme/favicon.png -------------------------------------------------------------------------------- /theme/head.hbs: -------------------------------------------------------------------------------- 1 | 2 | 9 | 10 | -------------------------------------------------------------------------------- /theme/header.css: -------------------------------------------------------------------------------- 1 | .menu-icon { 2 | width: 30px; 3 | transform: translateY(6px); 4 | margin-right: 5px; 5 | opacity: 0.7; 6 | } 7 | 8 | .light .menu-icon { 9 | opacity: 1; 10 | } 11 | 12 | 13 | .chapter > .chapter-item > .toggle { 14 | display: none; 15 | } 16 | 17 | svg { 18 | border-radius: 6px; 19 | } 20 | 21 | #disqus_thread { 22 | padding-top: 100px; 23 | } 24 | 25 | #disqus_thread > iframe { 26 | color-scheme: normal; 27 | } 28 | 29 | .menu-title { 30 | background-position: center; 31 | background-repeat: no-repeat; 32 | background-size: 150px; 33 | /* color: transparent; */ 34 | } 35 | 36 | .light .menu-title, 37 | .rust .menu-title { 38 | background-image: url(/.gitbook/assets/semaphore-docs-light.png); 39 | } 40 | 41 | .coal .menu-title, 42 | .navy .menu-title, 43 | .ayu .menu-title { 44 | background-image: url(/.gitbook/assets/semaphore-docs-dark.png); 45 | } -------------------------------------------------------------------------------- /theme/search.css: -------------------------------------------------------------------------------- 1 | ul#searchresults { 2 | padding-right: 10px; 3 | } 4 | 5 | ul#searchresults li { 6 | margin: 10px 0px; 7 | padding: 2px; 8 | border-radius: 2px; 9 | border-bottom: 1px dashed var(--searchresults-header-fg); 10 | padding-bottom: 10px; 11 | } 12 | 13 | ul#searchresults li:last-child { 14 | border-bottom: 0; 15 | padding-bottom: 0; 16 | } 17 | 18 | .searchresults-outer#searchresults-outer { 19 | border-radius: 6px; 20 | margin-top: 6px; 21 | border: 1px solid var(--searchbar-border-color); 22 | background-color: var(--searchbar-bg); 23 | /* box-shadow: 0 0 3px var(--searchbar-shadow-color); */ 24 | } 25 | 26 | ul#searchresults span.teaser { 27 | color: var(--searchbar-fg); 28 | margin-left: 0; 29 | } -------------------------------------------------------------------------------- /theme/tabs.css: -------------------------------------------------------------------------------- 1 | .mdbook-tabs { 2 | display: flex; 3 | } 4 | 5 | .mdbook-tab { 6 | background-color: var(--table-alternate-bg); 7 | padding: 0.5rem 1rem; 8 | cursor: pointer; 9 | border: none; 10 | font-size: 1.6rem; 11 | line-height: 1.45em; 12 | } 13 | 14 | .mdbook-tab.active { 15 | background-color: var(--table-header-bg); 16 | font-weight: bold; 17 | } 18 | 19 | .mdbook-tab-content { 20 | padding: 1rem 0rem; 21 | } 22 | 23 | .mdbook-tab-content table { 24 | margin: unset; 25 | } 26 | -------------------------------------------------------------------------------- /theme/tabs.js: -------------------------------------------------------------------------------- 1 | /** 2 | * Change active tab of tabs. 3 | * 4 | * @param {Element} container 5 | * @param {string} name 6 | */ 7 | const changeTab = (container, name) => { 8 | for (const child of container.children) { 9 | if (!(child instanceof HTMLElement)) { 10 | continue; 11 | } 12 | 13 | if (child.classList.contains('mdbook-tabs')) { 14 | for (const tab of child.children) { 15 | if (!(tab instanceof HTMLElement)) { 16 | continue; 17 | } 18 | 19 | if (tab.dataset.tabname === name) { 20 | tab.classList.add('active'); 21 | } else { 22 | tab.classList.remove('active'); 23 | } 24 | } 25 | } else if (child.classList.contains('mdbook-tab-content')) { 26 | if (child.dataset.tabname === name) { 27 | child.classList.remove('hidden'); 28 | } else { 29 | child.classList.add('hidden'); 30 | } 31 | } 32 | } 33 | }; 34 | 35 | document.addEventListener('DOMContentLoaded', () => { 36 | const tabs = document.querySelectorAll('.mdbook-tab'); 37 | for (const tab of tabs) { 38 | tab.addEventListener('click', () => { 39 | if (!(tab instanceof HTMLElement)) { 40 | return; 41 | } 42 | 43 | if (!tab.parentElement || !tab.parentElement.parentElement) { 44 | return; 45 | } 46 | 47 | const container = tab.parentElement.parentElement; 48 | const name = tab.dataset.tabname; 49 | const global = container.dataset.tabglobal; 50 | 51 | changeTab(container, name); 52 | 53 | if (global) { 54 | localStorage.setItem(`mdbook-tabs-${global}`, name); 55 | 56 | const globalContainers = document.querySelectorAll( 57 | `.mdbook-tabs-container[data-tabglobal="${global}"]` 58 | ); 59 | for (const globalContainer of globalContainers) { 60 | changeTab(globalContainer, name); 61 | } 62 | } 63 | }); 64 | } 65 | 66 | const containers = document.querySelectorAll('.mdbook-tabs-container[data-tabglobal]'); 67 | for (const container of containers) { 68 | const global = container.dataset.tabglobal; 69 | 70 | const name = localStorage.getItem(`mdbook-tabs-${global}`); 71 | if (name && document.querySelector(`.mdbook-tab[data-tabname=${name}]`)) { 72 | changeTab(container, name); 73 | } 74 | } 75 | }); 76 | --------------------------------------------------------------------------------