Projects

Projects are codebases developed and managed through Semaphore Continuous Integration. A project links your Git repository with Semaphore, so it can run jobs to test, build, or deploy your application.

This page explains how to set up projects and what settings are available.

Create a project

Video Tutorial: Create a Project

To create a Semaphore project you need:

• A Semaphore account with an organization
• A GitHub or Bitbucket account. For more information, see the connection guides
  • How to connect to GitHub
  • How to connect to Bitbucket
• A repository with at least one commit

UI

Go to Semaphore, press +Create New 1 and then press Choose repository

1. Select the GitHub or Bitbucket tab. You may need to press the Connect account button if this is the first time

2. Select the repository from the list and press on Choose

   Show me

   

3. Optionally, add people to the project. Press Continue

   Show me

   

4. Select a started workflow. If in doubt, select Single Job and Start

   Show me

   

Semaphore creates a new pipeline file in the .semaphore folder in the repository and starts working.

CLI

After installing and connecting the Semaphore command line:

1. Clone the repository in your machine

2. Run sem init at the root of the repository

3. Push a change to get Semaphore working

   git add .semaphore
   git commit "Initalize Semaphore"
   git push origin main

   

You can override the project name and URL by using additional options

sem init --project-name <project_name> --project-url <project_url>

If you get permission or not find error message, double check the connection between Semaphore and your Git provider:

• How to connect to GitHub
• How to connect to Bitbucket

View projects

UI

You can find your projects in Semaphore by pressing on the Projects tab and searching by project name.

Semaphore shows the latest activity in the last few days when logging in.

CLI

To get the list of the projects in your organization:

1. If needed, switch the context to your organization

2. Run sem get to list your projects

   $ sem get project
   NAME                                 REPOSITORY
   semaphore-demo-flutter               git@github.com:semaphoreci-demos/semaphore-demo-flutter.git
   hello-semaphore                      git@github.com:semaphoreci-demos/hello-semaphore.git

Workflow triggers

See workflow triggers

The following actions in the repository can trigger Semaphore to start the project's pipelines.

• Pushing commits into any branch
• Pushing Git tags
• Creating pull requests from the same repository
• Creating pull requests originating from a forked repository
• Updating any of the project's pipelines using the [visual editor](./jobs#workflow editor)
• Pressing the Run button on the Semaphore website
• Request a re-run using the Semaphore API
• Scheduling workflows using Tasks

The reason for the trigger can be determined at runtime by examining the Semaphore environment variables in the job. See the environment variable reference page for more details.

How pull requests are handled

Semaphore starts a workflow for every push to a pull request originating from a forked repository. For security reasons, secrets are disabled in jobs triggered in this way. You can create an allow list with the secrets you want to expose in the project settings.

note

Instead of pushing the HEAD commit to the pull request, Semaphore uses the MERGE commit between the source and the upstream branch. You can find the SHA of the HEAD commit of the Pull Request in the SEMAPHORE_GIT_PR_SHA environment variable.

Project tabs

Project members can view or manage the following project elements:

• Activity: shows the latest pipeline runs
• Deployments: access the project's environment (formerly deployment targets)
• Insights: shows the insights
• Artifacts: shows the project-level artifacts and retention policy
• Tasks: shows the tasks
• Flaky Tests: shows the flaky tests detected in the project
• People: shows or changes the project members
• Settings: shows the project-level settings

How manage access to projects

Semaphore periodically syncs users from GitHub. You can add and remove people from the project by inviting or removing them from the related repository.

Users with Admin or Owner roles can access every project in their organizations — even if they don't have access to the related repository.

About project permissions

Users can be granted access and permissions on a project by different means:

• Repository-level access: Semaphore automatically syncs user permissions from GitHub. See project roles to learn how repository permissions are mapped to project permissions
• Direct access: users can be directly added to and removed from the project. Their permissions are managed with project roles
• Role access: users with Admin or Owner roles can access every project in their organizations
• Group access: groups can grant their members access to projects, provided the group itself has been given access to those projects

How to manually add/remove members to projects

Available On

PlansScaleup

Scaleup plan users can manually add and remove people from a project. To manage users, ppen your project and go to the People tab

1. Press Add People

2. Select the user from the list of options

3. Select the role

4. Press Add Selected

   

See project roles for more information what actions can each role perform.

How to change permissions

Available On

PlansScaleup

Open your project and go to the People tab

1. Press the Change role next to the project member

2. Select the new role

   

How to view pre-defined roles

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

1. Open the Organization Settings menu
2. Select Roles
3. Scroll down to Project roles
4. 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 Project 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

   

How to change the project's owner

Open the project settings, under Project Owner type the username and press Change. The user must already have been invited to the organization.

note

Transferring ownership does not automatically grant project roles on the project. You must still manually grant the admin role to allow the new owner manage the project.

Settings

The Settings tab in your project allows you to customize your project settings, add project-level secrets, and manage artifacts

Project settings

In the general project settings, you can:

• Change the owner of the project
• Change the visibility of the project
• Change the project name or description
• Delete the project

Workflow triggers

See workflow triggers to learn how to customize what actions trigger a workflow.

Repository

In Repository settings page you can:

• change the URL of your Git repository if you moved it
• configure or reinstall the GitHub or Bitbucket connections
• regenerate the git webhook if Semaphore is not picking up on the remote changes

Project secrets

In Secrets page, you can create project-level secrets. These are only accessible for this project and not globally to all the organizations.

To learn how to create project secrets, see the secrets documentation page.

Project roles: https://docs.semaphoreci.com/security/default-roles/

Badges

The Badge settings page shows you shields embed codes for your README or any webpage, allowing team members and users about the build status of your project.

To get a badge embed code:

1. Type the branch name you want to show the status for. This is typically "main" or "master"

2. Select a badge style. This is only a style choice

3. Choose the file format where you will embed the badge

4. Copy the code into your README or webpage

   

Badge URLs follow the following format for the "master" branch:

https://<ORGANIZATION-NAME>.semaphoreci.com/badges/<PROJECT-NAME>.svg

On other branches the format is:

https://<ORGANIZATION-NAME>.semaphoreci.com/badges/<PROJECT-NAME>/branches/<BRANCH-NAME>.svg

The visual style of the badge can also be customized. There are two styles:

Style	Example
Semaphore (default)
Shields

The Semaphore style is the default. To use shields style, add ?style=shields to the URL. For example:

https://<ORGANIZATION-NAME>.semaphoreci.com/badges/<PROJECT-NAME>.svg?style=shields

Artifacts

The Artifacts settings page lets you configure the artifact retention policy.

To learn more, see the artifacts retention page

Pre-flight checks

Available On

PlansScaleup

Pre-flight checks are user-defined commands executed before the pipeline begins as part of the pipeline initialization job. They checks allow you to define the type of agent running the initialization job and to manually run commands before a pipeline starts.

note

If you want to run commands for all pipelines in your organization, see organization pre-flight checks.

How to set up checks

To create, edit, or delete project pre-flight checks, follow these steps:

1. Open the project on Semaphore

2. Go to the Settings tab

3. Select Pre-flight checks

4. Type the pre-flight commands

5. Optionally, type the name of secrets to be injected during the initialization job

6. Press Save changes

   

See the organization pre-flight page to learn about the available environment variables and see examples of pre-flight checks.

How to change init agent

You can change the agent in which the initialization and pre-flight commands run.

To change the initialization for the project, follow these steps:

1. Go to the Pre-flight settings page

2. Check the box Override default agent configuration

3. Select an Environment type

4. Select a Machine type

5. Select an OS image

6. Press Save changes

   

note

This setting overrides the organization-wide initialization agent.

How to configure status checks

Semaphore sends status checks to your GitHub or BitBucket repositories. Status checks show the latest Semaphore activity right in your repository.

Status checks appear in the commit messages.

And also on pull requests.

Semaphore only report status checks on the initial pipeline (.semaphore/semaphore.yml). But you can configure status checks on any other pipelines in the workflows or even on blocks.

Edit status checks

Status checks can only be configured using the Semaphore Command Line.

To add status checks on other non-initial pipelines, follow these steps:

1. Edit your project resource using sem edit on a terminal

   sem edit project <project-name>

2. The project configuration is opened in the default text editor. For example:

   apiVersion: v1alpha
   kind: Project
   metadata:
     name: example
   
   spec:
     repository:
       url: "git@{github|bitbucket}.com:renderedtext/example.git"
       run: true
       run_on:
         - branches
         - tags
       pipeline_file: ".semaphore/semaphore.yml"
   
       status:
         pipeline_files:
           - path: ".semaphore/semaphore.yml"
             level: "pipeline"

3. Add more items under the status.pipeline_files. The following example sends status checks for the semaphore.yml and staging-deploy.yml pipelines

   status:
     pipeline_files:
       - path: ".semaphore/semaphore.yml"
         level: "pipeline"
       - path: ".semaphore/staging-deploy.yml"
         level: "pipeline"

4. You can even send block-level status checks by using level: "block". For example:

   status:
     pipeline_files:
       - path: ".semaphore/semaphore.yml"
         level: "pipeline"
       - path: ".semaphore/staging-deploy.yml"
         level: "block"

Troubleshooting guide

If your repositories aren't showing in Semaphore or changes are not triggering new workflows, check the connection between GitHub and Semaphore.

1. Navigate to your Semaphore account
2. Read the status next to GitHub
3. If the status is disconnected, click on Grant public access or Grant private access

You can check and change the permissions of your OAuth App connection in the Semaphore OAuth page.

Verify deploy key health

Semaphore generates a deploy key when a project is created. This means there is a deploy key per repository connected to Semaphore.

When a deploy key is broken or invalid, Semaphore shows the following error message:

git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

To verify the status of a deploy key:

1. Open your project settings
2. If there isn't a green check next to Deploy Key, the key is invalid

To deploy a new key, click on Regenerate

info

A deploy key can be invalidated if:

• it was manually removed from the repository
• access via OAuth or GitHub App was revoked
• the repository's original owner no longer has access to it (only for projects added via OAuth

Verify webhook health

Semaphore uses a webhook to detect changes in your repository. When the webhook is broken, Semaphore can't trigger new workflows.

To verify the status of a webhook:

1. Open your project settings
2. If there isn't a green check next to Deploy Key, the key is invalid

To fix the broken webhook, click on Regenerate. This should generate a new webhook and repair the connection between Semaphore and GitHub.

Reconnecting moved or renamed projects

There are several actions that can break the connection between GitHub and Semaphore. For example:

• moving the repository to a different location
• renaming the repository
• renaming the GitHub user account
• renaming the GitHub organization

When this happens, you must update the URL of the repository in Semaphore. To do this:

1. Open your project settings
2. Type the new repository URL
3. Press Change

After changing the URL, double-check the status of the deploy key and the webhook.

See also

• Organization pre-flight checks
• How to manage organizations
• How to configure test reports