How to set up Git hosting for your project

All Divio Cloud projects can use the Git private server we provide. This article describes how you can instead use the Git hosting provider of your choice.

Important

Once you have set up an external Git provider on a project, you will no longer be able to revert to Divio’s own Git server. Please ensure that this is what you want to do before using this feature.

Set up external Git hosting

Prepare the external Git repository

Go to your Git hosting service. The next step depends on whether you are creating a new Divio Cloud project, or migrating an existing project:

Creating a new Divio Cloud project

  1. Create a new repository at the Git provider.
  2. Ensure the new repository has a master branch, and does not contain anything other than .git, LICENSE, README, README.md or README.rst.

If these conditions are not met, the Control Panel will not accept the repository URL.

Migrating an existing project

  1. Add the Git repository to the local version of your project as a remote: git remote add external <repository URL>.
  2. Ensure that all the branches you wish to keep are present and up to date with the Divio Cloud server: git pull <branch>
  3. Push the branches you require to the new remote: git push external <branch>

Add the Git repository URL to the Control Panel

You will need to supply the URL (SSH URLs are recommended, but you can also use HTTPS URLs) of your new repository to the Control Panel. The next step depends on whether this is a new or existing Divio project:

Creating a new Divio Cloud project

  • Select Repository > Custom in the project creation page.

Migrating an existing project

  1. Select Repository from your project’s menu in the Dashboard.
  2. Select Migrate to external repository.

Add your project’s public key to the Git host

The Divio Control Panel will provide you with a public key to add to the Git host, allowing our infrastructure to access the repository (see below for HTTPS).

Copy the key, and add it to the Git repository:

'GitHub' GitHub

  1. In the repository, go to Settings > Deploy keys > Add deploy key.
  2. Paste the key.
  3. Select Allow write access.

'GitLab' GitLab

  1. In the repository, go to Settings > Repository > Deploy keys > Create a new deploy key.
  2. Paste the key.
  3. Select Write access allowed.

'BitBucket' BitBucket

  1. Optionally, create a Bitbucket account specifically for Divio Cloud projects - otherwise the key will grant access to all your Bitbucket projects.
  2. Go to Bitbucket settings > SSH keys > Add key.
  3. Paste the key.

Test access

When you hit Continue in the Control Panel, it tests its access by performing a git pull action. If successful, the project Dashboard will show the repository URL.

Configure a webhook for the Git repository

In order for the Control Panel to receive a signal when the repository is updated, you need to set up a webhook. This step is optional but strongly recommended for convenience.

In the Repository view, select the appropriate webhook type (GitHub, GitLab and BitBucket each have their own type of webhook. Other providers will generally use a webhook that is similar to one of these).

The Control Panel will give you a URL to use for the webhook, and a secret key.

At the Git host, add a new webhook:

'GitHub' GitHub

  1. In the repository, go to Settings > Webhooks > Add webhook.
  2. Add the Webhook URL to the Payload URL field.
  3. Leave the Content type as application-x/www-form-urlencode.
  4. Add the Webhook Shared Secret to the Secret field.
  5. Set Push events as the trigger for the webhook.

'GitLab' GitLab

  1. In the repository, go to Settings > Integrations.
  2. Add the Webhook URL to the URL field.
  3. Add the Webhook Shared Secret to the Secret token field.
  4. Leave the Push events trigger set.

'BitBucket' BitBucket

  1. In the repository, go to Settings > Webhooks.
  2. Give the webhook a title.
  3. Add the Webhook URL to the URL field.
  4. For Triggers, ensure that Repository push is set.

The Webhook Shared Secret is not used.

Using the external Git remote

Your external Git remote has now been set up.

The Control Panel can save commits to it (using the key you provided) and the repository can send a signal to the Control Panel to pull in new commits when they land (using the webhook).

Options and special cases

Read-only access to the repository

In most cases, you will want to allow write access to the repository. This is the standard configuration and gives you full access to the benefits of the Divio Cloud addon system, in which the Control Panel records interface actions and addon configuration as Git commits.

It’s also possible to maintain stricter control over the repository, allowing only read access. In this case, project configuration that would normally be maintained via the Control Panel must be undertaken manually.

Write access is required to set up the external Git configuration, but may be disabled subsequently.

HTTPS authentication

By default, the Control Panel will assume that you will be using SSH authentication to the Git provider, which is preferred.

However, HTTPS can be useful in environments where SSH is not permitted, and is available if you explicitly provide an HTTPS URL.

You can give the Divio Project access to the Git repository over HTTPS by providing the Git hosting username and a personal access token.

This is disabled for those providers that would allow us to connect using your password. In accordance with our security policies, Divio Cloud will not request or store your passwords for other services.

Some Git providers enforce the use of personal access tokens for HTTPs, rather than allowing passwords to be used. However, GitHub, GitLab and BitBucket all permit HTTPS authentication without the protection of two-factor authorisation, and for this reason we do not permit HTTPS as an authentication method for these platforms.

Errors and what they mean

The remote repository requires a master branch

The Control Panel expected to find a branch (by default named master) at the remote.

If the Divio Cloud project uses the Custom tracking branches feature, then whatever branch is used for the Test environment should be present at the remote.

Check the repository for the expected branch.

Authentication error

The most likely problem is that one or more of:

are not correct. Check these values.

The master branch must exist and only include a single readme file in order to create a new project

The master branch at the remote repository contained other files.

Check that no other files are in the branch.

You have no webhook set up

Although the Control Panel has been able to connect to the repository and authenticate, a webhook has not yet been set up.

This is not necessarily an error, but it does mean that your Divio Cloud project will not automatically receive signals from the remote when new commits are made to it, and so you will need to use the manual Update button to pull new changes to your project.

Using webhooks is recommended.