GitLab integration

Available on: Team and above for connecting, plans from tags and commit statuses. Business and Enterprise for deployment approvals. On lower plans Deployment Playbook never approves or rejects GitLab deployments, so approvals stay with people in GitLab. The Integrations page notes that deployment blocking needs Business. After a downgrade, connections are kept but gated features stop being processed. See pricing.

Works with GitLab.com and self-managed GitLab over https.

• Tag push → plan. Pushing a tag that matches a mapped project's pattern creates a plan from the mapped template. You get one plan per project and tag; redeliveries are ignored.
• Commit status. The tagged commit gets a deployment-playbook status that links to the plan: pending while waiting for approval, running while in progress, success when done, failed when rejected, canceled when rolled back.
• Deployment approvals (GitLab Premium/Ultimate). A deployment to a protected environment that requires approval waits until the plan's gate phase is open. Deployment Playbook then approves it through the Deployments approval API. If the plan is rejected, the deployment is rejected. On GitLab Free, statuses still work and approval calls are skipped; the Integrations page explains why.

1. Create an access token

Use a project access token (one project) or a group access token (all projects in a group): Settings → Access tokens → Add new token.

Setting	Value
Role	Developer for plans and statuses. Maintainer (or a role allowed to approve the protected environment) for deployment approvals
Scopes	api (required to post statuses and approve deployments)
Expiry	Your policy. Update the token on the Integrations page before it expires

The token is stored encrypted (AES-256-GCM) and is never shown again.

2. Connect the workspace

Under Integrations → GitLab (Admins only), enter your GitLab URL (https://gitlab.com or your own instance) and the token, then click Connect. The token is checked against /api/v4/personal_access_tokens/self.

Self-managed instances must be reachable over https on a public address. Hosts that resolve to private, loopback, link-local or other reserved ranges are refused, so an instance that is only reachable inside your network can't be connected yet.

3. Add the webhook

In the project (or group, on Premium), go to Settings → Webhooks → Add new webhook:

• URL: the webhook URL shown on the Integrations page (https://deployment-playbook.com/api/integrations/gitlab/webhook/<id>).
• Secret token: the secret shown on the Integrations page. It is checked on every request (X-Gitlab-Token).
• Trigger: Tag push events and Deployment events.
• Keep SSL verification on.

4. Map projects

Add a mapping with the project path (group/project), the template, the tag pattern (default v*), the environment, the gate phase and the four-eyes setting.

5. Protect the environment (Premium/Ultimate)

1. Go to Settings → CI/CD → Protected environments and protect production.
2. Set Required approvals to 1.
3. Add the token's bot user (or its role) as an approver.

Then deploy from a tag:

deploy:
  stage: deploy
  rules:
    - if: $CI_COMMIT_TAG =~ /^v/
  environment:
    name: production
  script: ./deploy.sh

The job waits for approval. When the plan's gate phase opens, Deployment Playbook approves the waiting deployment for that commit and the job starts.

Security

• The webhook secret is compared in constant time.
• Deliveries are de-duplicated (X-Gitlab-Event-UUID) and rate-limited per connection.
• Outbound calls go only to the GitLab URL you configured, through the SSRF guard.
• Disconnect deletes the stored token. Also revoke the token and remove the webhook in GitLab.