Connect GitHub
GitHub users need to provide access to Semaphore so it can read their repositories.
TODO: Use organization menu -> settings -> github app
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:
-
Open the server menu and select Settings
-
Select Git Integration
-
Press Connect
-
Sign into your GitHub account
-
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
-
Press Install
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
TODO: oauth was not working on the alpha I used. Check again
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:
- Open the Semaphore project you want to transfer
- Go to Project Settings and select Repository
- Press the button Switch 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.
- Navigate to your Semaphore account
- Read the status next to GitHub
- 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:
- Open your project settings
- If there isn't a green check next to Deploy Key, the key is invalid
To deploy a new key, click on Regenerate
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:
- Open your project settings
- 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:
- Open your project settings
- Type the new repository URL
- Press Change
After changing the URL, double-check the status of the deploy key and the webhook.