Connect GitLab, self-hosted GitLab and Bitbucket

GitLab and Bitbucket work like GitHub in SrvYard. You connect the account once under Source control, and from then on sites can list your projects and branches, clone private code, and deploy when you push. What differs is the credential each host asks for: GitLab uses a personal access token, Bitbucket uses your username and an app password, and a GitLab that you run yourself also needs its address.

This article shows each form, the permissions the credential needs, and how to use Custom Git for any other Git server. If you have not connected a host before, Connect GitHub explains the page, the statuses and what a site does with the connection in more detail. All of it applies here too.

Before you begin#

• An account on the host that can reach the repositories you want to deploy.
• Permission to manage source control. Connecting needs source-control:manage, which owners, admins and managers hold.
• For a self-hosted GitLab, an address your server can reach. SrvYard talks to it over HTTPS from SrvYard's own servers, and your servers pull code from it, so both must be able to reach it. A GitLab that is only reachable inside a private network will not work unless that network allows the connections.
• A few minutes on the host's website to create the token or app password.

Which credential for which host#

In every case SrvYard stores the credential encrypted, never shows it again, and uses it to list your repositories, to clone, and to register the push webhook. Give each credential an expiry date you will remember: an expired credential is the most common reason a deployment suddenly fails.

1. Connect GitLab with a token#

Open Settings > Source control, press Connect git host, and choose or paste an access token under GitLab.

1. The token guide. "Create a personal access token so SrvYard can list your projects, add deploy keys and register push webhooks." The Required permissions are api and write_repository. The first lets SrvYard add deploy keys and webhooks, and the second lets your servers clone over HTTPS. The link Create a token on GitLab opens GitLab's page with the name SrvYard and both scopes already ticked.
2. Personal access token. Paste the token (it starts with glpat-). Above it the Name field labels the connection; the panel suggests the host's name. Press Connect.

SrvYard asks GitLab who the token belongs to. On success the connection is listed as Connected. If GitLab refuses, the message from GitLab appears under the field and nothing is saved.

2. Connect a self-hosted GitLab#

On the first panel, choose Self-hosted GitLab.

1. GitLab URL. The address of your installation, for example https://gitlab.example.com. For gitlab.com you leave it empty. The help text says so: "Only for a self-hosted GitLab, e.g. https://gitlab.example.com. Leave empty for gitlab.com."
2. Personal access token. Create it on your own GitLab under your profile's access tokens, with the same api and write_repository scopes. The Create a token link points at your GitLab once you have typed the address.

Use https. A certificate that is not trusted can make the check fail, so give the GitLab a proper certificate first.

3. Connect Bitbucket#

Choose or paste an access token under Bitbucket.

1. The guide. "Create an app password so SrvYard can list your repositories, add access keys and register push webhooks." The permissions are repository, repository:admin and webhook, which Bitbucket's form words as Repositories: Read and Admin, and Webhooks: Read and write. The link opens the page for creating an app password.
2. Bitbucket username. Your Bitbucket username (from Personal settings, Account settings), not your email address.
3. App password. Paste the generated password. Bitbucket shows it once.

Press Connect. SrvYard lists the repositories you are a member of, newest activity first, and the connection shows as Connected.

4. Check what you have#

Back on the Source control page, every connection is a row. A connection changes from Connected to Needs a new token when the host refuses the credential, for example during a check or while SrvYard lists repositories: that is the page telling you the credential stopped working.

1. A GitLab connection. Its name (you can rename it later), host, account, Token as the access type, its Status and how many Sites deploy from it. The three-dot menu at the end of the row offers the same actions as for GitHub: Reconnect with a new token, Rename or replace token, Check connection and Remove.
2. A Bitbucket connection. The same columns. The status tells you whether the host still accepts the credential: Connected, or Needs a new token with the host's message underneath when it was refused, as on the Bitbucket row in this example.

Create a site and the connection appears in the source control choice with its projects and branches. See Connect a repository and pick a branch.

5. Any other Git server: Custom Git#

Gitea, Forgejo, an internal Git server or a bare repository on another machine need no connection. When you create a site, choose Custom Git and paste the repository address:

• An SSH address ([email protected]:team/app.git). SrvYard creates a deploy key for that one site and shows you the public half to add to the repository as a read-only key. The server clones with it.
• An HTTPS address of a public repository. No credential is needed.

Custom Git cannot list repositories or register the push webhook for you. For push-to-deploy, use the site's deploy hook address from a script or from the repository's own webhook settings: see Push to deploy with webhooks.

Troubleshooting#

• "Not set up on this SrvYard yet." The one-click sign-in is not configured on this installation. Use the token or app password route.
• GitLab says the token is invalid. Check that it has both api and write_repository, that it has not expired, and that you pasted it without spaces. For a self-hosted GitLab check the address too.
• Bitbucket fails with a login error. You probably entered your email address or your account password. Use the username from your Bitbucket settings and an app password.
• The connection works but a private project is missing. The account behind the token is not a member of it, or the token was created for a group you are not in.
• Needs a new token. The host rejected the credential. Use Reconnect with a new token in the row menu.
• Remove is refused. Sites still deploy from the connection. Move or delete them first.

Related#

• Connect GitHub: the full walk-through of the Source control page.
• Connect a repository and pick a branch: use a connection on a site.
• Push to deploy with webhooks: deploy on every push, with or without a connection.
• Deploy from GitHub Actions and other CI: another way to trigger deployments.