Skip to main content
Version: Enterprise Edition v1.3

Managing Semaphore

This page explains how to set up notifications, manage users, and what settings are available in your Semaphore instance. On Semaphore Enterprise Edition, we use the terms server, instance, and organization interchangeably.

Overview​

In order to access any non-public resources on Semaphore you must be invited to the Semaphore instance.

If you are trying out Semaphore for the first time, we suggest the Quickstart, where we show how to get started quickly.

A Semaphore instance has:

Managing users​

Semaphore users a Role Based Access Control model to manage permissions at the server and project level.

To manage users in your server, open the server menu and select People. This tab shows users and groups in your server along with their roles and groups.

The people tab

How to create users​

To create new accounts, go to the people option in the server menu and follow these steps:

  1. Press Add people

    Add people button

  2. Type the email of the persons you wish to invite

  3. Optionally, set a username. If not provided, the username is inferred from the email

  4. When you are done adding users, press Create Accounts

    Add user screen

  5. Take note of the temporary passwords for each account

    Temporary password

  6. When the new user first logs in with the temporary password, they will be prompted to create a new one. After that, they can start using Semaphore normally.

How to remove users​

Users can only be removed from the server when they don't own any projects. You must transfer the ownership of all the user's projects before they can be removed from the server.

To remove a user, go to the people option in the server menu and follow these steps:

  1. Transfer any project ownership the user may have to another individual. The user must not own any projects
  2. Press the X button next to the username of the user you want to remove

Removing a user from the organization

Upon removal, access to all projects in the server are revoked.

note

Only an Admins, Owner, or dedicated custom roles can remove users from the server.

How to change a user role​

To change user roles, go to the people option in the server menu and follow these steps:

  1. Press the Edit button next to the user you want to change

    Edit button

  2. Select the new role

    Change role button

How to reset a user password​

To reset a user password, go to the people option in the server menu and follow these steps:

  1. Press the Edit button next to the user you want to change

    Edit button

  2. Press the Reset password button

    Reset password button

  3. Press Reset password

  4. A new temporary password will be generated

  5. When the user logs in with the temporary password they will be prompted to create a new password

How to create groups​

User groups streamline user management by allowing bulk actions. After creating a group, you can:

  • Add members to the group
  • Assign a role to the group

All members of the group automatically inherit the permissions associated with the assigned role.

As an example, let's say you want to give the Audit team access to the Audit logs in your server. To achieve that you can:

  1. Create a custom role with view permissions on the Billing page
  2. Create an "Auditors" group
  3. Assign the new custom role to the group
  4. Add everyone in the Auditor team to the group
  5. As the team changes, you can add or delete persons from the group

To create a group, open the server menu and select People.

  1. Press on Create group
  2. Type in the group name and description
  3. Type the names of the persons to add to the group
  4. Press Save changes to create the group

Add group

The new group has the member role by default. You can change it by pressing the Modify Role button and selecting a different role.

You can also define custom server roles if none of the pre-defined roles suit your needs.

How to add members groups​

To add or remove users in a group, press the Modify group button next to it.

  • Press the X button to remove the user from the group
  • Type the name of the persons you want to add to the group
  • Press Save changes to finish editing the group

Add group

How to view pre-defined roles​

Semaphore provides pre-defined roles for the server. You can see what actions each role can perform by following these steps:

  1. Open the server Settings menu
  2. Select Roles Settings Role location
  3. In the Organization Roles section, press the eye button next to the role you want to examine

The actions with enabled checkbox are allowed for that role.

Server admin allowed actions

How to create custom roles​

Create custom roles to give your users the precise permissions they need.

  1. Open the serve Settings menu
  2. Select Roles
  3. On the Organization Roles section, press New Role
  4. Give a name a description to the new role
  5. Enable the permissions allowed to the role. You can use the search box to narrow down options
  6. Press Save changes

Creating a new server role

Semaphore users a Role Based Access Control model to manage permissions at the instance level.

To manage users in your Semaphore instance, open the server menu and select People. This tab shows users and groups in your instance along with their roles and groups.

The people tab

How to view permissions for roles​

Semaphore provides pre-defined roles. These permissions cannot be changed (but new roles can be added, see. You can see what actions each role can perform by following these steps:

  1. Open the server Settings menu
  2. Select Roles Settings Role location
  3. In the Organization Roles section, press the eye button next to the role you want to examine

The actions with enabled checkbox are allowed for that role.

Server admin allowed actions

Instance settings​

To access your settings, open the server menu and click on Settings.

Server settings location

General settings​

This page shows the main settings for your instance. Here, you can change its name, and control how workflows run.

General settings

info

The URL of your server is the URL that leads to the Home page in your Semaphore instance. For example semaphore.example.com

Notifications​

You can set up Slack and other webhook-based notifications to get your team notified whenever there project finishes running.

To learn more, see the notification documentation

Initialization agent​

Some types of pipelines require initialization job to evaluate and compile the them before the workload beings.

Semaphore tries to pick the best type of agent automatically but you change it for the whole server. This is particularly useful when you are using self-hosted agents.

To change the initialization job agent for all your projects in your Semaphore instance, follow these steps:

  1. Select Initialization job from the settings menu
  2. Select the Environment type
  3. Select the Machine type
  4. Select the OS image (if available)
  5. Press Save

Customizing a the initialization job agent

info

If you experience errors during initialization, see the initialization job logs to help troubleshoot the issue.

Okta integration​

Integration with Okta allows you to automate user management within your Semaphore server, as well as to use Okta apps for Single Sign On.

For more information, see the Okta integration page

Audit logs​

To support compliance, accountability, and security, Semaphore provides logs of audited events. Audit Log events are events that affect your server, projects, users, or any other resources in Semaphore. Events contain information about when who and what was the performed activity.

You can find audit logs in your server settings under Audit Logs.

Audit logs location

The audit logs shows all the audited events in reverse chronological order. Latest events are shown first.

Audit log example

How to export audit logs​

Audit logs can be exported in two ways:

  • CSV file
  • Streaming to an S3-compatible bucket

To export the logs as CSV, press the Export as CSV button.

Exporting as CSV

To configure streaming to an S3-compatible bucket, press the Configure Streaming button and:

  1. Select between AWS and Google Cloud

  2. Type the region (AWS only)

  3. Type the bucket name

  4. Type the access token

    • AWS: provide the Access Key ID and Access Key Secret for the IAM account
    • Google Cloud: provide the HMAC Key for a service account

    The service account credentials provided must have write and read access to the bucket

  5. Press Looks Good

Configuring Audit log streaming

info

Audit logs are streamed to the bucket once per day.

Project queues​

You can use queues to control the order in which pipelines are executed in your instance. See named queues for more information.

Activity monitor​

The activity monitor show the agent utilization and the currently running pipelines.

To view the activity monitor, open your server menu and select Activity Monitor.

Activity monitor location

In the activity monitor, you can see the machine quota utilization for your instance. Here, you can have an overview on how Semaphore Cloud machines and self-hosted agents are being used.

Activity monitor quotas

In the lower part of the activity monitor you can find the currently running workflows for all the projects in your instance. Use this to know what jobs are running, and see which ones are waiting in the queue to debug usage issues.

Activity monitor workflows

See also​