Organizations

Organizations are the administrative unit for Semaphore. This page explains how to set up notifications, manage users, and what settings are available.

Overview

In order to access any non-public resources on Semaphore you must be invited to the organization your team or company has created.

If you are trying out Semaphore for the first time, we suggest the Guided Tour, where we show how to create your first organization.

Organizations have:

• zero or more projects
• a billing plan
• one or more owners
• users and groups with role-based permissions
• a dedicated URL, for example, https://my-org.semaphoreci.com

How to change organizations

Switch the active organization to change its settings or view its projects.

UI

To view or create other organizations, open the organization menu in the top right corner and select Change Organization.

CLI

You must install and connect the Semaphore command line to access your organizations

1. Run sem context to show the organizations connected to the tool. The active organization has an asterisk (*) next to it
   View connected organizations

   $ sem context
       myorg1_semaphoreci_com
       myorg2_semaphoreci_com
     * myorg3_semaphoreci_com
2. Change organization with sem context <organization-url>
   Change active organization

   $ sem context myorg1_semaphoreci_com
   switched to context "myorg1_semaphoreci_com"

Managing users

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

Free plans are limited to 5 users per organization. Paid plans have no user limit.

You can only invite people with GitHub or BitBucket accounts to your organization.

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

How to invite users

To invite a user to your organization, press the Add people button:

1. Select one of the available tabs

   • Type the user's handle, e.g. TomFern, or select the user from the list.
   • If you don't see the user in the list. Ensure they have repository access in GitHub or BitBucket for at least one project in your organization

   

2. Press Add selected

3. Optionally, set their role

How to remove users

Users can only be removed from the organization 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 organization.

To remove a user, go to the people option in the organization 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

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

note

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

How to change user roles

To change the role of a user, press the Change Role button next to the person.

See organization roles to learn what roles are available.

How to create groups

Available On

PlansScaleup

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 Finance team access to the Billing pages in your organization. To achieve that you can:

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

To create a group, open the organization 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

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 organization roles if none of the pre-defined roles suit your needs.

How to change group roles

To change the role of a group, press the Change Role button next to the group.

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

How to view pre-defined roles

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

1. Open the Organization Settings menu
2. Select Roles
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.

How to create custom roles

Available On

PlansScaleup

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

1. Open the Organization 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

Organization settings

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

General settings

Your organization main settings. Here, you can change its name, its URL, and control how workflows run.

info

The URL of your organization is the URL that leads to the Home page in your Semaphore organization.

The default value is the name of your organization in lowercase and kebab-case, e.g. <your-organization-url>.semaphoreci.com. You can change the first part of the URL in the general settings page.

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 organization. This is particularly useful when you are using self-hosted agents.

To change the initialization job agent for all your projects in your organization, 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
5. Press Save

To change the initialization agent for a single project, see project pre-flight checks.

info

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

Okta integration

Available On

PlansScaleup

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

For more information, see the Okta integration page

Contacts

Manage your contact information.

In this section, you can add contact details in case the Semaphore Support Team needs to reach you. Add your name, phone number and email in three categories:

• Finance: used any billing-related messaging related to your organization
• Main: used as the primary point of communication
• Security: used to discuss any issues related to security in your organization

Audit logs

Available On

PlansScaleup

To support compliance, accountability, and security, Semaphore provides logs of audited events. Audit Log events are events that affect your organization, 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 organization settings under Audit Logs.

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

How to export audit logs

Available On

PlansScaleup

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.

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

info

Audit logs are streamed to the bucket once per day.

Organization queues

You can use assign pipelines to organization queues to control the order in which pipelines are executed. 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 organization menu and select Activity Monitor.

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

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

Transfer ownership

Before you can transfer of an organization, the following conditions need to happen:

• The new owner is a member of the organization
• The new owner must have logged in Semaphore at least once
• Only the current owner can transfer ownership

To promote a new owner to the organization:

1. Go to the organization People tab
2. Press the Change Role button
3. Select Owner

It might take several minutes for the update to be completed.

note

Updating the ownership of an organization doesn't automatically transfer the project ownership. For more information, see How to transfer project ownership.

How to remove an owner

If you need to demote or remove an owner from the organization, any user with the Owner permission level needs to send an email to support@semaphoreci.com from the primary email address associated with their GitHub or Bitbucket account used to log into Semaphore.

How to delete an organization

danger

Deleted organizations cannot be restored. There is no undo for this operation.

Before you can delete an organization, you must remove all it projects. Only the Owner of an organization can delete it.

In order to delete an organization, follow these steps:

1. Open the Organization Settings menu
2. Press on Settings
3. Press on Delete Organization... at the bottom of the page
4. Type "delete" to confirm
5. Press the Delete Organization button

See also

• How to configure Okta integration
• How to configure notifications
• How to configure projects