Connecting a self-hosted GitLab repository as your source

Connecting a Git Repository on your self-hosted GitLab to your Site allows you to work on your website files locally and sync your changes to CloudCannon. CloudCannon also syncs any file changes you make in CloudCannon back to your self-hosted GitLab.

Connect to your self-hosted instance#

Before you sync a Git Repository from your self-hosted GitLab, you need to connect CloudCannon to your self-hosted GitLab instance. You only need to do this once per Organization.

The details CloudCannon needs come from an application on your GitLab server, which you can create on the Applications page of your GitLab User Settings. Set the application's Redirect URI to https://app.cloudcannon.com/self_hosted_gitlab/authorize/ and select the following minimum scopes:

• api
• read_user
• read_repository
• write_repository
• openid

Once you've created the application, GitLab will show its Application ID and Secret. You will need both to connect CloudCannon to your instance.

To connect to your self-hosted GitLab instance:

1. Navigate to the Self-Hosted GitLab page under the Files heading in your Org Settings.
2. Enter the details for your self-hosted GitLab instance:
   • Authorize URL: https://HOSTNAME/oauth/authorize
   • Token URL: https://HOSTNAME/oauth/token
   • API Endpoint: https://HOSTNAME/api/v4. This field is required and must include https://.
   • Key: The Application ID of your GitLab application.
   • Secret: The Secret of your GitLab application.
3. Click the Configure Self-hosted GitLab button.

CloudCannon will save your server details and show the Authentication, Settings, Sites, and Danger Zone tabs on the Self-Hosted GitLab page. If a field is missing or invalid, CloudCannon will show an error under that field instead.

Configure your GitLab connection#

Once you've connected your self-hosted GitLab server, you can configure CloudCannon to support your particular infrastructure. If your server uses a private certificate authority or requires custom headers, set the Custom CA Certificate or Custom Headers option before you authenticate your self-hosted GitLab. Otherwise, authentication and syncing will fail. These options are on the Settings tab of the Self-Hosted GitLab page under Org Settings, below the Server Configuration details you entered when you connected your instance:

• Minimum Access Level
• Custom Headers
• Custom CA Certificate

The Minimum Access Level setting allows you to change the minimum access CloudCannon requires on a GitLab Git Repository before it can connect. You can choose Guest, Reporter, Developer, Maintainer, or Owner. By default, CloudCannon requires Maintainer access to a Git Repository before syncing it. Self-hosted GitLab allows custom access level permissions, so a lower access level may be sufficient, depending on your setup.

The Custom Headers setting allows you to configure additional headers for CloudCannon to use when connecting to your GitLab server. Click the Add Custom Header button to add a header. CloudCannon passes custom headers in the form key:value using Git's http.extraHeader configuration option.

The Custom CA Certificate setting allows you to paste a PEM-encoded certificate or certificate chain for CloudCannon to trust during Git operations. CloudCannon passes the certificate using Git's http.sslCAInfo configuration option.

Click the Update Configuration button to save your changes to these options.

Sync with a Git Repository#

To connect a self-hosted GitLab Git Repository and start syncing files:

1. Navigate to the Syncing page under Site Settings.
2. Select the Self-hosted GitLab repository option from the provider dropdown.
3. Click the Authorize button.

CloudCannon will open the Connect to GitLab modal, where you can choose one of two authentication methods. These options are only available in the Connect to GitLab modal. The Authentication tab of the Self-Hosted GitLab page under Org Settings shows a single Authenticate button, which connects your GitLab account.

Authenticate with your GitLab account

When you authenticate with your GitLab user account, your CloudCannon Organization gets access to the same Git Repositories on your self-hosted GitLab to which you have access.

To authenticate with your user account:

1. Select the Connect your GitLab account option under Authentication method in the Connect to GitLab modal.
2. Click the Authenticate with GitLab button. CloudCannon will redirect you to your self-hosted GitLab instance.
3. Log in to your self-hosted GitLab account.
4. Authorize CloudCannon to access your GitLab account.

GitLab will redirect you back to CloudCannon, where you can choose a Git Repository to connect.

Authenticate with a group access token

Alternatively, you can create a group access token in GitLab and save that token in CloudCannon. This gives your CloudCannon Organization access to all the resources scoped to your token. For instructions on creating and configuring a token, please read GitLab's group access tokens documentation.

To authenticate with a group access token:

1. Select the Authenticate with a group access token option under Authentication method in the Connect to GitLab modal.
2. Paste your token into the Group Access Token field.
3. Enter the date your token expires in the Expiry Date field. The date must be in the future.
4. Click the Save and authenticate button.

CloudCannon will save your token and authenticate your self-hosted GitLab. CloudCannon will email the members of the Owners Permission Group in your Organization shortly before the token expires. To replace an expired or revoked token, unauthenticate your self-hosted GitLab, then authenticate again with a new token in the Connect to GitLab modal.

Select your Git Repository and branch

Once you've authenticated, you can choose the Git Repository and branch to connect to your Site. Under the Branch Setup heading, you can sync from a branch that already exists in your Git Repository, or have CloudCannon create a new branch from a source branch. If your Git Repository has no branches, CloudCannon will show a link to add one in your self-hosted GitLab.

To connect your Git Repository and branch:

1. Select your Git Repository from the Repository dropdown.
2. Choose the Use an existing branch option or the Create a new branch option under the Branch Setup heading.
3. Pick your branch from the Branch dropdown. If you are creating a new branch, pick the branch to copy from the Source branch dropdown and enter a name in the New branch name field.
4. Click the Backup and Sync button.

CloudCannon will connect your Site to your self-hosted GitLab Git Repository. CloudCannon pulls in any changes you push to your Git Repository, and automatically commits and pushes any changes you make in CloudCannon.

Disconnect your self-hosted instance#

Disconnecting your self-hosted GitLab instance removes the server and its stored credentials from your Organization. CloudCannon keeps the files for any Sites that synced with it. You will need to enter your server details again to reconnect.

You can only disconnect your server after you unauthenticate it. If the Danger Zone tab shows an Unauthenticate button, unauthenticate your self-hosted GitLab first, which stops syncing for every Site that uses it. For more information, please read our documentation on unauthenticating your Git Provider.

To disconnect your self-hosted GitLab instance:

1. Navigate to the Self-Hosted GitLab page under the Files heading in your Org Settings.
2. Select the Danger Zone tab.
3. Click the Disconnect Self Hosted GitLab button.
4. Click the Confirm button.

CloudCannon will remove your server details and show the configuration form on the Self-Hosted GitLab page.