Skip to main content
Version: Cloud (SaaS)

Projects

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 create projects hosted on public Git hosting services such as GitHub or Bitbucket.

Create a project​

To create a Semaphore project you need:

Go to Semaphore, press + Create New and choose from the options based on where your repository is hosted.

Creating a new project

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

    Show me

    Select repository

  2. Optionally, you might change the default name of the project. Press the blue check button and wait for the project to be deployed. Press Continue

    Show me

    Deploy project

  3. You can now select a default agent to be used in the project, and specify the pipeline configuration location.

    Show me

    Select default agent and pipeline configuration path

  4. You will be given options to start from a template, based on your machine type.

    Show me

    Select starter workflow

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

Project created

View projects​

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

Searching for projects

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

Project activity

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

Searching for projects

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

Project activity

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:

Project tabs

How to 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.

How to manually add/remove members to projects​

To manually add or remove people from a project:

  1. Press Add People
  2. Select the user from the list of options
  3. Select the role
  4. Press Add Selected

Adding a member to the project

To remove a user, press the X button next to their name.

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

How to change permissions​

Open your project and go to the People tab

  1. Press the Change role next to the project member
  2. Select the new role

Changing a member's 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 Settings menu
  2. Select Roles Settings Role location
  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​

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

  1. Open the Settings menu
  2. Select Roles
  3. On the Project Roles section, press New Role
  4. Give a name and 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 project custom role

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.

Changing project owner

After project ownership has been transferred, you need to push a new commit. Re-running old builds no longer works once the ownership of a project has changed.

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

General settings

How to delete a project​

danger

Deleting a project is irreversible. All the pipelines, jobs, and artifacts associated with the project will be lost.

Go to the general settings of your project and follow these steps:

  1. At the bottom of the page, press "Proceed with caution" under Delete project

    Delete a project link

  2. Select a Reason for deleting the project

    Deletion page for project

  3. Optionally, you may leave some feedback

  4. Enter the name of the project to confirm the deletion

  5. Press Delete project

You may also delete a project using the Semaphore CLI.

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

Repository settings

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.

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

    Using project badges

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

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

On other branches the format is:

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

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

StyleExample
Semaphore (default)Semaphore Badge
ShieldsSemaphore Badge

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

https://<organization-url>.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
PlansEnterprise

Pre-flight checks are user-defined commands executed before the pipeline begins as part of the pipeline initialization job. These 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 preflight 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

    Setting up pre-flight checks for project

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

    Changing the initialization agent for the project

note

This setting overrides the organization-wide initialization agent.

How to configure status checks​

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

Status checks appear in the commit messages.

CI failed

And also on pull requests.

PR Passed

Semaphore only reports 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|gitlab}.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 your repos and Semaphore.

  1. Navigate to your Semaphore account
  2. Read the status next to your repository host Connection status green
  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 Checking the status of the deploy key

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 Checking the status of the deploy key

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

Reconnecting moved or renamed projects​

Certain actions in GitHub can change the repository URL associated with your Semaphore project, such as:

  • Moving the repository to a different location
  • Renaming the repository
  • Renaming the GitHub user account
  • Renaming the GitHub organization

Scenario 1: Repository moved or renamed​

If the repository URL changes due to a move or rename, no manual action is required in Semaphore.

Once the change is made on GitHub, simply push a commit from the updated repository. Semaphore will automatically detect the new repository URL and update the connection with the project.

Scenario 2: Switching a project to a different repository​

If you want to connect your project to a different repository (e.g., switching to a fork), you can update the repository URL manually. To change the repository associated with a project:

  1. Open your Project Settings
  2. Navigate to Repository
  3. Enter the new repository URL
  4. Click Change
image

After changing the repository URL, verify that the deploy key and webhook are still correctly configured.

See also​