How to configure external Git hosting

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


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.

The steps in this process are:

  1. Prepare the external Git repository

  2. Add the Git repository URL to the Control Panel (so the Control Panel can find the codebase)

  3. Add your project’s public key to the Git host (so that the Control Panel is permitted to access the repository)

  4. Test access

  5. Configure a webhook for the Git repository (recommended) (so that the repository can push events to the Control Panel)

Prepare the external Git repository

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

Creating a new Divio project

In order for our Control Panel to be able to check out the Git repository, it must be able to check out the master branch, with no conflicts.

  1. Create a new repository at the Git provider.

  2. Ensure the new repository has a master branch. The branch must not contain anything other than .git, LICENSE, README, or README.rst.

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

Migrating an existing Divio 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 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 project

  • Select Repository > Custom in the project creation page.

Migrating an existing Divio 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 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.

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).

Remote Git: Reset to origin

For projects with external git repositories, especially if commits are force pushed, the project’s repository on the control panel may not reflect all the commits made in its remote repository at origin.

To reset to remote, go to the repository view of the project’s control panel and select reset to origin and the repository will reflect the commit history of the remote origin.

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 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 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 using account passwords, 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 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 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.