Knowledge Base

Prerequisites

Before you begin, make sure you have:

• An active GitLab.com or self‑hosted GitLab instance.
• Administrator or Maintainer access to the target project.
• Our Platform account with integration permissions.

Step 1 – Create a Personal Access Token

Navigate to Settings → Access Tokens in GitLab and generate a token with the following scopes:

• api
• read_repository
• write_repository

Copy the token and store it securely – you’ll need it in the next step.

# Example via curl (replace placeholders)
curl --request POST \
  --header "PRIVATE-TOKEN: <YOUR_TOKEN>" \
  "https://gitlab.com/api/v4/projects/:id/triggers"

Step 2 – Set Up GitLab Webhooks

Go to Settings → Webhooks of your project and add a new webhook:

• URL: https://yourplatform.example.com/api/gitlab/webhook
• Secret Token: (use the token created above)
• Trigger events: Push events, Merge request events, Tag push

Enable SSL verification and click Add webhook.

# Sample payload test via curl
curl -X POST "https://gitlab.com/api/v4/projects/123/hooks" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://yourplatform.example.com/api/gitlab/webhook","push_events":true,"enable_ssl_verification":true}'

Step 3 – Configure CI/CD Pipelines

Add the following snippet to your .gitlab-ci.yml to notify our platform after successful pipelines:

stages:
  - build
  - test
  - deploy

notify_platform:
  stage: deploy
  script:
    - curl -X POST -H "Content-Type: application/json" -d '{"project":"$CI_PROJECT_PATH","status":"$CI_PIPELINE_STATUS"}' https://yourplatform.example.com/api/gitlab/pipeline
  only:
    - master
    - tags

Troubleshooting

Common issues and fixes:

Webhooks not firing

Check that the secret token matches exactly and that the endpoint returns a 200 response.

CI job failure after adding notification

Ensure the platform URL is reachable from the GitLab runner and that the curl command includes proper authentication if required.