Connect GitLab

Connect GitLab.com or your own GitLab with a token that can only read, and its webhook.

In short

Connect GitLab once for the whole organization: say where it lives, make a read-only token, try it on one project and add one webhook.

Before you start

• Who: someone who may manage the organization's connections - owners and admins have it by default.
• Plan: every plan keeps one code host; Business keeps 10 connections and Enterprise any number. Your own GitLab comes with the Enterprise plan.
• First: a GitLab account that can read the projects, and the Maintainer role on a group or project to add a webhook.

Where it lives

1. Open your organization, then Settings › "Connections", and press "Connect a code host".
2. Choose "GitLab". The wizard opens; each step is checked before the next one opens.
3. Choose "GitLab.com", or "My own GitLab" and type its "Address", such as https://gitlab.example.com.
4. For your own GitLab press "Check this step": it finds the host and checks its certificate.

Sign in

1. Press "Open the token page". GitLab opens a new token with the name and the scopes read_api and read_repository chosen.
2. Pick an expiry date in GitLab and press Create token.
3. Copy the token, paste it into "Token". A token with api or write scopes is refused.
4. Type one project into "A repository to check with", as group/project - such as acme/backend/payments.
5. Press "Check this step": it signs in and reads it.

Webhook

The webhook tells {{brand}} the moment something changes in GitLab, so nothing waits for the next read.

1. Press "Make the address and secret". Copy each with "Copy address" and "Copy secret" - the secret is shown only now.
2. In GitLab, open the group (or one project), then Settings, Webhooks, Add new webhook.
3. Paste the address as the URL and the secret as the Secret token.
4. Tick Push events and Merge request events, then Add webhook.
5. Press Test, Push events to send a first delivery.
6. Back in the wizard, press "Look for a delivery". You can also go on with "Next"; deliveries show up under "Deliveries".

Check and use

1. Press "Run the full check". Every step should say Passed; a step that failed names what to change.
2. Under "Where will you use it?" tick the modules that will use it - Boards, Designer and API Tester.
3. Optional: under "Only these teams" tick the teams that may pick it. Leave it empty for everyone who may use those modules.
4. Check the "Name" - boards, designs and projects show it - and press "Finish". The connection shows under "Connections" with its health.

If a step fails

• A failed step names its code, what it means and what to change. The code's section of /help/settings/fix-a-company-connection says more.
• Change what the step says and press "Check again". The next step opens only when this one passes.
• Closing the wizard keeps every step that passed. Press "Continue setup" on the connection's row to go on where you stopped.

Good to know

• A group webhook covers every project in the group.
• A project access token works too, with the same two scopes.

• A connection's row shows its health, its last delivery and "Where used".
• "Deliveries" lists what the webhook address received in the last 30 days and where each delivery went.
• "Disconnect" first lists every board, design and project that would stop using it.
• Nobody else pastes a token: boards, designs and API projects pick this connection.

Related

• /help/settings/fix-a-company-connection
• /help/settings/webhooks-and-site-ownership