Connect GitHub so SrvYard can deploy your repositories

When your code lives on GitHub, SrvYard needs permission to see your repositories, to let your servers pull private code, and to ask GitHub to tell SrvYard when you push. You give that permission once per organisation, by connecting GitHub under Source control. Every site you create afterwards can pick the connection, a repository and a branch from lists instead of typing addresses.

This article shows how to connect GitHub, which permissions a token needs and why, where the connection shows up on a site, and what to do when GitHub stops accepting it. Other Git hosts work the same way: see Connect GitLab and Bitbucket.

Before you begin#

• A GitHub account that can reach the repositories. The connection sees whatever that account sees: its own repositories, those of organisations it belongs to, and those it collaborates on.
• Permission to manage source control. Connecting, renaming, reconnecting and removing need source-control:manage, which owners, admins and managers hold. Using a connection when you create a site needs only source-control:view.
• For a token, the right permissions. SrvYard checks the token with GitHub before it saves it, and tells you if a permission is missing.
• An organisation that owns the connection. The connection belongs to the organisation you are in, so each organisation connects its own.

1. Open Source control#

Choose Settings in the sidebar, then Source control. The page says "GitHub, GitLab and Bitbucket accounts your sites deploy from."

1. Connect git host. Opens the panel for a new connection (step 2).
2. A connection row. The name, the host, the account, how it signs in (Token here), its Status, how many Sites deploy from it and when it was Connected.
3. Status. Connected means the host accepted the last check. Needs a new token (or Needs reconnecting for a one-click connection) means GitHub rejected the access: see step 5.
4. Actions. The three-dot menu of the row.

Until you connect something, the page reads "No git hosts connected" and explains that you can also use Custom Git when you create a site, with any Git server.

2. Choose how to connect#

Press Connect git host. A panel titled New source control opens: "Connect the git host your code lives on. SrvYard lists your repositories, adds deploy keys and registers push-to-deploy webhooks."

1. Continue with GitHub. The quick way. GitHub asks you to authorise SrvYard and sends you back, and the connection appears in the list. It needs the SrvYard administrator to have configured the GitHub integration; where it is not set up, the panel says so under the button.
2. or paste an access token. The manual way, with a personal access token that you create on GitHub. It works everywhere and lets you control exactly which permissions you give. Step 3 describes it.
3. Self-hosted GitLab. For GitLab on your own server: see Connect GitLab and Bitbucket.
4. Custom Git. "Paste any git URL when you create a site. Nothing to connect here." Use it for other Git servers.

3. Paste a token#

Choose or paste an access token under GitHub.

1. The token guide. It lists the Required permissions as small badges: repo, admin:repo_hook and read:org. A classic token needs those three scopes. A fine-grained token needs, on the repositories you deploy, Administration (read and write, for deploy keys), Webhooks (read and write) and Contents (read).
2. Create a token on GitHub. Opens GitHub's token page with the scopes and the description "SrvYard" already filled in. Press Generate token there and copy it. GitHub shows it only once.
3. Personal access token. Paste it. The Name field above it labels the connection, which is useful when you connect two accounts. The token is stored encrypted and is never shown again.
4. Connect. SrvYard asks GitHub who the token belongs to and what it can do. On success the connection appears in the list as Connected.

4. How sites use the connection#

When you create a site, the form offers the connection, then lists your repositories and branches. See Connect a repository and pick a branch. After that the connection does three jobs.

• Cloning. By default the server clones the repository over HTTPS with the connection's token. If you prefer that the token is not on the server, tick Generate a site deploy key for your source control provider when you create the site: SrvYard then registers a read-only deploy key for that one repository and the server uses it.
• Push to deploy. Turn on Push to deploy in the site's deployment settings and SrvYard registers a webhook on the repository, so a push to the site's branch starts a deployment. See Push to deploy with webhooks.
• GitHub deployments. Optionally SrvYard creates a deployment record in GitHub for every deploy, with in-progress, success and failure statuses, so it shows on the repository and in pull requests. This needs a token that can write deployments (the repo scope). It is best effort: a token without access is skipped and never fails a deployment.

On the site, Settings > Integrations shows what it uses.

1. How this site is connected. The Source control connection, the Repository, Push to deploy (on or off), Push webhook (Registered or Not registered) and GitHub deployments. "Change these under Deployments."
2. Update the connection. A link to the Source control page, where you reconnect or replace the token.

5. Reconnect, check or remove a connection#

Open the three-dot menu on the row.

1. Reconnect with a new token. Shown when the connection needs it. Paste a new token, and the sites that use the connection work again.
2. Check connection. Asks the host again whether it accepts the connection. Use it after you fixed something on GitHub.
3. Remove. Deletes the connection. SrvYard refuses while sites still deploy from it ("Sites still deploy from this connection. Move or delete them first."). Rename or replace token sits between them for changing the name or swapping the token without waiting for a failure.

A connection that GitHub no longer accepts is marked, and the page says: "A git host no longer accepts a connection. Reconnect it to list repositories and deploy again." The usual reasons are an expired or revoked token, a token that lost one of the scopes, or the GitHub user losing access to the repository.

Troubleshooting#

• Needs a new token. GitHub rejected the token, or it is missing a permission (repo, admin:repo_hook and read:org). Create a new token with all three and use Reconnect with a new token.
• A repository is missing from the list. The account behind the token cannot see it. For an organisation repository, make sure the token is allowed for that organisation (organisations can require approval of tokens), or for a fine-grained token that the repository is selected.
• Push to deploy shows "Not registered". The webhook could not be created, usually because the token cannot manage webhooks on that repository. Fix the token and switch Push to deploy off and on again.
• Deployments fail with an authentication error. The token on the connection is expired or revoked. Replace it from the Source control page.
• Remove is refused. Sites still use the connection. Move them to another connection under their settings, or delete them.
• I connected the wrong account. Add the right one, move the sites over, then remove the old connection.

Related#

• Connect GitLab and Bitbucket: the same for the other Git hosts.
• Connect a repository and pick a branch: use the connection on a site.
• Push to deploy with webhooks: deploy on every push.
• Create a site on your server: where you choose the connection.