|
| 1 | +--- |
| 2 | +linkTitle: gitlab-mr-api |
| 3 | +title: gitlab-mr-api |
| 4 | +prev: /docs/deployment/addons/ |
| 5 | +next: /docs/user-manual/ |
| 6 | +--- |
| 7 | + |
| 8 | +**Teams Notifier's gitlab-mr-api component** |
| 9 | + |
| 10 | +| | | |
| 11 | +|---|---| |
| 12 | +| **homepage** | https://github.com/teams-notifier/gitlab-mr-api | |
| 13 | +| **registry** | https://github.com/teams-notifier/gitlab-mr-api/pkgs/container/gitlab-mr-api | |
| 14 | +| **image** | `ghcr.io/teams-notifier/gitlab-mr-api:latest` | |
| 15 | + |
| 16 | +## Intro |
| 17 | + |
| 18 | +This component enables real-time tracking of project merge requests. When a merge request is created, a message is posted and automatically updated as the MR status changes. The message is automatically deleted when the merge request is either closed or merged. |
| 19 | + |
| 20 | +Here's an example of a merge request message: |
| 21 | +{{< img src="merge-request-card-example.png" style="margin-left: 0rem">}} |
| 22 | + |
| 23 | +## Config |
| 24 | + |
| 25 | +Environment variables or `.env`: |
| 26 | + |
| 27 | +* `PORT`: port to listen to (def: `3980`) |
| 28 | +* `ACTIVITY_API`: `activity-api` base URL (ex: `https://activity-api:3981/`) |
| 29 | +* `DATABASE_URL`: Database DSN in the form: `postgresql://{USER}:{PASSWORD}@{HOST}/{DATABASE}` |
| 30 | +* `VALID_X_GITLAB_TOKEN`: comma separated list of Gitlab's Secret token (sent as `X-Gitlab-Token` header), uuidv4 generated seems a good choice. |
| 31 | + |
| 32 | +## Webhook config |
| 33 | + |
| 34 | +You'll need: |
| 35 | +- one or more conversation tokens |
| 36 | +- one of the `VALID_X_GITLAB_TOKEN` you generated |
| 37 | + |
| 38 | +On your GitLab repository, follow these steps to add a new webhook: |
| 39 | + |
| 40 | +1. Go to **Settings**. |
| 41 | +2. Select **Webhooks**. |
| 42 | +3. Click **Add new webhook**. |
| 43 | +4. Fill out the form with the following details: |
| 44 | + |
| 45 | + * **URL**: https://hostname-of-this-api.example.org/api/v1/gitlab-webhook |
| 46 | + * **Add custom header**: |
| 47 | + * name: `X-Conversation-Token` |
| 48 | + * value: comma separated list of conversation tokens you want the MR messages sent to |
| 49 | + * **Secret token**: one of the `VALID_X_GITLAB_TOKEN` you generated |
| 50 | + * **Trigger**, select: |
| 51 | + * Merge request events |
| 52 | + * Pipeline events |
| 53 | + * Emoji events (planned) |
| 54 | + |
| 55 | +You can then save or test. |
| 56 | +Note that for the test to work you need an existing MR in the project. |
| 57 | + |
| 58 | +In case of failure, now or afterward, you can Edit the webhook and you'll see all the previous calls, error code and messages, including sent payload and a way to resend the request. |
| 59 | + |
| 60 | + |
| 61 | +## Webhook declaration helper |
| 62 | + |
| 63 | +{{% details title="Environment variables" %}} |
| 64 | +```bash |
| 65 | +# Gitlab token with Admin or Maintainer right |
| 66 | +GITLAB_TOKEN= |
| 67 | + |
| 68 | +# your gitlab url (opt. if gitlab.com) |
| 69 | +#GITLAB_URL= |
| 70 | + |
| 71 | +# coma separated list of conversation tokens |
| 72 | +CONVERSATION_TOKEN= |
| 73 | + |
| 74 | +# Gitlab secret matching one of the VALID_X_GITLAB_TOKEN |
| 75 | +GITLAB_SECRET= |
| 76 | + |
| 77 | +# Full url of the accessible webhook https://gl-webhook.example.org/api/v1/gitlab-webhook |
| 78 | +HOOK_URL= |
| 79 | +``` |
| 80 | +{{% /details %}} |
| 81 | + |
| 82 | +{{% details title="`setup-webhook.sh`" %}} |
| 83 | + |
| 84 | +To find the project's id, go to the project's homepage, at the rightmost top, click the vertical ellipsis and click *Copy project ID*. \ |
| 85 | +Tested on Gitlab 17.6. |
| 86 | + |
| 87 | +```bash |
| 88 | +#!/bin/bash |
| 89 | + |
| 90 | +# Takes a project id as first arg |
| 91 | +# Optional conversation token override as second |
| 92 | +set -euo pipefail |
| 93 | + |
| 94 | +[ -e .env ] && . .env |
| 95 | + |
| 96 | +[ -z "${1:-}" ] && echo "please provide a project id as first arg" && exit 1 |
| 97 | + |
| 98 | +PROJECT_ID=${1} |
| 99 | +CONVERSATION_TOKEN=${2:-$CONVERSATION_TOKEN} |
| 100 | + |
| 101 | +GITLAB_URL=${GITLAB_URL:-gitlab.com} |
| 102 | + |
| 103 | +HOOK_COUNT=$(curl -s --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \ |
| 104 | + https://${GITLAB_URL}/api/v4/projects/$PROJECT_ID/hooks/ \ |
| 105 | + | jq 'map(select(.url | test("'${HOOK_URL}'")?)) | length') |
| 106 | + |
| 107 | +[ "$HOOK_COUNT" -gt 0 ] && echo "already a hook declared" && exit 1 |
| 108 | + |
| 109 | +curl \ |
| 110 | + -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \ |
| 111 | + -H 'Content-Type: application/json' \ |
| 112 | + https://${GITLAB_URL}/api/v4/projects/$PROJECT_ID/hooks \ |
| 113 | + -X POST -s -w $'\n' \ |
| 114 | + --data-binary @- << EOF | jq . |
| 115 | +{ |
| 116 | +"name": "gitlab-mr-api", |
| 117 | +"url": "$HOOK_URL", |
| 118 | +"token": "$GITLAB_SECRET", |
| 119 | +"custom_headers": [{"key":"X-Conversation-Token", "value":"$CONVERSATION_TOKEN"}], |
| 120 | +"merge_requests_events": true, |
| 121 | +"pipeline_events": true, |
| 122 | +"emoji_events": true, |
| 123 | +"push_events": false, |
| 124 | +"tag_push_events": false, |
| 125 | +"repository_update_events": false, |
| 126 | +"issues_events": false, |
| 127 | +"confidential_issues_events": false, |
| 128 | +"note_events": false, |
| 129 | +"confidential_note_events": false, |
| 130 | +"wiki_page_events": false, |
| 131 | +"deployment_events": false, |
| 132 | +"feature_flag_events": false, |
| 133 | +"job_events": false, |
| 134 | +"releases_events": false, |
| 135 | +"resource_access_token_events": false |
| 136 | +} |
| 137 | +EOF |
| 138 | +``` |
| 139 | +{{% /details %}} |
| 140 | + |
0 commit comments