Connect a repository and pick a branch

A site deploys from one repository and one branch. You choose both when you create the site, and you can change either afterwards in the site settings. Nothing is fetched at the moment you save: SrvYard stores the new address and the next deployment uses it.

This article shows where the repository settings live, the two ways to connect a repository (a provider connection or a plain Git URL), how the server authenticates to it, and what to do when a connection stops working. It also explains the two Reset actions that help when the code on the server is not what you expect.

Before you begin#

• A site with a repository. A site that was created without one has nothing to deploy. The create form warns that a site made without a repository cannot get one later, so decide before you press Create site. A site made by WordPress or phpMyAdmin installers never has a repository: SrvYard downloads those applications itself.
• A source control connection, for the provider route. Connect GitHub, GitLab or Bitbucket under Source control in the sidebar first. The GitHub and GitLab and Bitbucket articles show how.
• Permission to update the site. Members who can only view a site see the repository but not the controls to change it.

1. Open the repository settings#

Open the site, choose Settings and stay on General in the side menu.

1. Root directory. The folder of the repository that Composer and npm run in. It is fixed when the site is created and shown greyed out. For a monorepo it is the subfolder that holds the application.
2. Web directory. The folder Nginx serves, relative to the root directory. For Laravel it is /public. You can change it here; SrvYard rewrites the Nginx configuration straight away, unlike the repository, which waits for the next deployment.
3. Repository. Three choices: No repository, Git provider and Custom Git URL. Switching between them only changes the form until you save.
4. Git URL. Shown for Custom Git URL. An https:// address for a public repository, or an SSH address such as [email protected]:team/app.git.
5. Branch. The branch every deployment fetches. It defaults to the repository's default branch when you pick one from a provider, and to main when you type it.
6. Save. The page confirms with "Settings saved. Repository changes apply on the next deployment."

2. Choose a repository from a connected provider#

The Git provider tab uses a connection you made under Source control. It is the best choice for private repositories because the connection already carries the access token.

1. Git provider. The tab is disabled when your organisation has no connection yet.
2. Connection. Pick which connection to use. Each entry shows the connection's name and the provider.
3. Account or organization (optional). Narrows the repository list to one account or organisation. On Bitbucket this is the workspace. Leave it on All accounts and organizations to search everything the token can see.
4. Repository and branch. Normally a searchable list of repositories followed by a list of that repository's branches, with the default branch labelled default. In the screenshot SrvYard could not reach the provider, so it shows a notice instead.

The demo organisation uses fictional tokens, so SrvYard cannot read repositories there and shows the notice that a real organisation sees when a token has expired or lost a permission. It offers Update the connection (or Reconnect for an OAuth connection) and Type the repository manually. Typing means entering owner/repository yourself and the branch name; it saves the same way.

The repository you save is stored as owner/repository. SrvYard builds the clone address from it and authenticates with the connection's token.

3. Use any other Git host#

The Custom Git URL tab is for hosts SrvYard has no provider for, and for public repositories you do not want to connect an account for.

• An https:// address works for public repositories only, because no token is sent.
• An SSH address (git@host:path.git or ssh://git@host/path.git) makes SrvYard create a site deploy key. Open Settings > Deployments and find the Keys card: it shows the public key. Add it as a read-only deploy key in your repository, then deploy. The private key stays in SrvYard and is sent to the server only while a deployment runs.

The Keys card also tells you what a site uses. For a provider connection it says the server clones with the access token of the connection, or shows the public key SrvYard registered at the git host.

4. Check what the next deployment will fetch#

Open the Deployments tab. The Source card repeats what is saved.

1. Source. The repository, the branch, the strategy (Zero downtime or In place), how many releases are kept and when the site was last deployed.
2. Deploy now. Starts a deployment of exactly what the card shows.

What a deployment does with the repository depends on the strategy:

• Zero downtime. Every deployment makes a fresh shallow clone of the branch (--depth 1 --single-branch) into a new release folder. Changing the repository or the branch is therefore safe: the next release simply comes from the new place, and the live release is untouched until the new one succeeds.
• In place. The site folder is a Git checkout. A deployment points its origin at the saved address, fetches the branch with depth 1 and resets the working tree to it, so local edits on the server are discarded.

Both fetch Git submodules when the repository has a .gitmodules file. A submodule that cannot be fetched produces a warning in the log and does not fail the deployment.

5. Reset the Git state when the server drifts#

Someone who edits files on the server by hand can leave the checkout dirty. Two actions in the site actions menu (the three dots at the top right of the site) help.

1. Site actions. Opens the menu. It also holds Edit Nginx configuration, Restart Nginx and Rename site.
2. Reset deployment state. Fails deployments that have waited or run for more than 30 minutes without reporting back, so a new one can start. A deployment that is still working is not touched.
3. Reset Git state. Throws away uncommitted changes and untracked files. It is disabled for a site without a repository.

1. The title and text change with the strategy. On a zero-downtime site the reset cleans the live release and keeps the deployed commit; to get newer code you deploy. On an in-place site it fetches the branch and makes the folder equal to it.
2. Reset Git state confirms. Ignored files such as .env, vendor and storage are kept in both cases.

Troubleshooting#

• "GitHub rejected the access token, or it is missing a permission". The connection's token expired or lost a scope (repo, admin:repo_hook and read:org for GitHub). Press Update the connection or Reconnect, issue a new token and try again.
• The repository you want is missing from the list. The token cannot see it. Check the account or organisation filter, grant the token access to the repository, or choose Type it manually and enter owner/repository.
• "Could not list branches; type the name or retry." The provider did not answer. Press retry, or type the branch name.
• "Use the owner/name format, for example laravel/laravel." A provider repository must be written owner/name. For any other address use Custom Git URL.
• "Enter an https:// or SSH git URL." The Custom Git URL does not match one of the accepted shapes. Plain http:// and addresses with spaces are refused.
• A deployment fails with "Permission denied (publickey)". The server cannot authenticate over SSH. Add the public key from the Keys card to the repository as a deploy key, or switch to a provider connection.
• A deployment fails with "Could not clone the branch". The branch name is wrong or the server has no access to the repository. Check Branch and the connection.
• The page still shows the old repository after you saved. The deployment history only changes when you deploy. Press Deploy now and read the log.

Related#

• Create a site on your server: pick the repository when the site is made.
• Push to deploy with webhooks: deploy on every push to the branch.
• Write and test a deploy script: what runs after the code is fetched.
• Connect GitHub: create the connection that this article uses.