Skip to main content
Version: Community Edition v1.3

Connect GitHub

GitHub users need to provide access to Semaphore so it can read their repositories.

Overview​

Semaphore accesses your GitHub repositories using the Semaphore GitHub App. This method provides fine-grained control and per-repository permissions to control which code Semaphore can access.

You must install the GitHub App in order to create projects on Semaphore.

How to authorize the GitHub App​

To connect Semaphore with GitHub, follow these steps:

  1. Open the server menu and select Settings

    Server menu

  2. On Git Integration press Connect

    Git integration page

  3. Sign into your GitHub account

  4. Select what type of access to authorize

    • All repositories: grant access to Semaphore to all your current and future repositories
    • Only select repositories: select from the list which repositories can be accessed by Semaphore

  5. Press Install

note

You might not be able to install the GitHub App if you are not the GitHub organization owner. In this case, following these steps sends an installation request to the organization's owner. You cannot proceed until the owner authorizes the access.

How to transfer projects from OAuth to GitHub App​

Projects connected via the OAuth App can be transferred to the GitHub App at any time. You need to have installed the GitHub App in your organization before the transfer can take place.

To transfer projects, follow these steps:

  1. Open the Semaphore project you want to transfer
  2. Go to Project Settings and select Repository
  3. Press the button Switch to GitHub App Switching from OAuth to GitHub App

If the project was transferred successfully, you should get a message that says Project connection type switched to GitHub app.

Go to Project Settings and select Repository Settings. If your project is using a personal token to connect to the repository, you will see the following screen:

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 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 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 Changing the repository URL in Semaphore

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

File semaphore.yml is not available​

You might see the following error message when trying to run workflows on Semaphore:

semaphore.yml ERROR:
Error: {"File '.semaphore/semaphore.yml' is not available", "Not Found"}

This means that Semaphore can't fetch the .semaphore/semaphore.yml file from the repository. There are two reasons why this might happen:

  1. The file doesn't exist on your repository: double check to make sure that the Semaphore YAML file actually exists
  2. Repository is disconnected from Semaphore: follow the steps previously described

See also​