Connect GitLab
Connect a gitlab.com group to Prodgator. Prodgator creates the webhook for you.
Prodgator connects to GitLab with OAuth. You sign in with GitLab, pick a group, and Prodgator creates the webhook that sends pipeline, job, deployment, merge request and push events.
Prodgator supports gitlab.com. Self-managed GitLab instances are not supported.
Requirements
- On GitLab: Maintainer or Owner of a top-level group.
- In Prodgator: the role.
Connect a group
- Open Admin Console > Integrations.
- On the GitLab card, click Connect GitLab (or Connect another GitLab group).
- Sign in to GitLab and approve access. Prodgator asks for the scope, which it needs to create webhooks, read job logs, read merge requests and post the Prodgator Policies commit status on them.
- Pick the group to connect. Only top-level groups where you are Maintainer or above are listed.
The group then appears on the GitLab card.
The webhook Prodgator creates
Prodgator tries a group webhook first. Group webhooks need GitLab Premium or Ultimate. If GitLab refuses, Prodgator adds a webhook to each project in the group and its subgroups where you are Maintainer (up to 100 projects). Projects added to the group later are covered by a group webhook, but not by per-project webhooks.
Each webhook:
| Setting | Value |
|---|---|
| URL | |
| Secret token | Generated by Prodgator for this connection |
| Triggers | Pipeline events, Job events, Deployment events, Merge request events, Push events |
| SSL verification | On |
You do not need to copy the token anywhere. Prodgator checks the header on every delivery against the stored token.
What each trigger is for
| Trigger | What Prodgator does with it |
|---|---|
| Pipeline events | Pipeline runs and their jobs on the Pipelines page, with the release name (the merge request title for a merge request pipeline, otherwise the commit title); wakes the merge request gate of the commit |
| Job events | Job status and times; a finished job wakes the merge request gate of the commit |
| Deployment events | Deployments, protected environment approvals and release policies |
| Merge request events | Merge request gates and SPACE metrics (merge requests opened and merged, approvals as reviews) |
| Push events | Policies kept in the repository: a push to the default branch that changes . Other pushes are acknowledged and dropped |
Tag push and release events are not used, as their GitHub counterparts are not: a tag pipeline already arrives as a pipeline event with the tag as its ref, and a push to a merge request's branch arrives as a merge request event.
Connections made before a trigger was added
Prodgator keeps its webhooks up to date. When a Prodgator release adds a trigger, the webhook of every connection is updated with the new trigger (and the same secret token) within about ten minutes. If that fails, for example because the person who connected the group is no longer a Maintainer, edit the webhook in GitLab: open the group's Settings > Webhooks (or each project's, for per-project webhooks), choose the Prodgator webhook, tick every trigger listed above and save. Do not change the secret token. You can also disconnect and reconnect the group, which creates the webhook again with every trigger.
Check the connection
Run a pipeline in a project in the group. It appears on the Pipelines page within a few seconds, with each job as a stage.
Troubleshooting
"Nothing to connect". You are not Maintainer or Owner of any top-level group. Ask a group owner for the role, or ask them to connect GitLab from Prodgator. GitLab connects through Prodgator's sign-in with GitLab, so there is nothing to install in GitLab.
"Webhook not created". Prodgator could not create a group webhook or any project webhook. Check that you can manage webhooks in the group's projects.
"Already connected". The group is already connected to this organization.
Events stopped arriving. In GitLab open the project's Settings > Webhooks and check Recent events for errors.
Disconnecting
Click the delete icon next to the group in Admin Console > Integrations. Prodgator deletes the webhooks it created, revokes its GitLab token and removes the stored secrets. If GitLab cannot be reached, Prodgator tells you what to remove by hand. Status checks you added Prodgator as stay on their projects: Prodgator reminds you to delete them, since GitLab would otherwise wait on them.
Approving GitLab deployments
To approve GitLab protected environment deployments from Prodgator, link your own GitLab account first. See Approve deployments.
Gating merge requests
With a group connected, Prodgator evaluates each merge request against the pull request policies bound to its project and target branch, and posts a Prodgator Policies commit status on the merge request's pipeline. Turn on Pipelines must succeed in the project's merge request settings to block the merge until it passes. See Pull request gates on GitLab.
On GitLab Ultimate, an admin can add Prodgator as an external status check on a project instead, from the merge request's Merge protection section. This needs the Maintainer role for the GitLab account that connected the group. GitLab then calls Prodgator at , signed with a secret Prodgator keeps for the connection, and Prodgator answers the check. See Prodgator as a status check.