diff --git a/assets/css/custom.css b/assets/css/custom.css new file mode 100644 index 0000000..88ea22c --- /dev/null +++ b/assets/css/custom.css @@ -0,0 +1,4 @@ +thead th:empty { + border: thin solid black !important; + display: none; +} diff --git a/content/docs/deployment/addons/gitlab-mr-api.md b/content/docs/deployment/addons/gitlab-mr-api.md deleted file mode 100644 index 76dbe2f..0000000 --- a/content/docs/deployment/addons/gitlab-mr-api.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -linkTitle: gitlab-mr-api -title: gitlab-mr-api -prev: /docs/deployment/addons/ -next: /docs/user-manual/ ---- - -**Teams Notifier's gitlab-mr-api component** - -homepage: https://github.com/teams-notifier/gitlab-mr-api - -Environment variables or `.env`: - -* `PORT`: port to listen to (def: `3980`) -* `ACTIVITY_API`: `activity-api` base URL (ex: `https://activity-api:3981/`) -* `DATABASE_URL`: Database DSN in the form: `postgresql://{USER}:{PASSWORD}@{HOST}/{DATABASE}` -* `VALID_X_GITLAB_TOKEN`: comma separated list of Gitlab's Secret token (sent as `X-Gitlab-Token` header), uuidv4 generated seems a good choice. - -## Usage - -You'll need: -- one or more conversation tokens -- one of the `VALID_X_GITLAB_TOKEN` you generated - -On your Gitlab repo, go to Settings then Webhooks and click "Add new webhook" and fill up the form: - -* **URL**: https://hostname-of-this-api.example.org/api/v1/gitlab-webhook -* **Add custom header**: - * name: `X-Conversation-Token` - * value: comma separated list of conversation tokens you want the MR messages sent to -* **Secret token**: one of the `VALID_X_GITLAB_TOKEN` you generated -* **Trigger**, select: - * Merge request events - * Pipeline events - * Emoji (soon) - -You can then save or test. -Note that for the test to work you need an existing MR in the project. - - -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. diff --git a/content/docs/deployment/addons/gitlab-mr-api/gitlab-project-id.png b/content/docs/deployment/addons/gitlab-mr-api/gitlab-project-id.png new file mode 100644 index 0000000..b40c26b Binary files /dev/null and b/content/docs/deployment/addons/gitlab-mr-api/gitlab-project-id.png differ diff --git a/content/docs/deployment/addons/gitlab-mr-api/index.md b/content/docs/deployment/addons/gitlab-mr-api/index.md new file mode 100644 index 0000000..0f9d541 --- /dev/null +++ b/content/docs/deployment/addons/gitlab-mr-api/index.md @@ -0,0 +1,140 @@ +--- +linkTitle: gitlab-mr-api +title: gitlab-mr-api +prev: /docs/deployment/addons/ +next: /docs/user-manual/ +--- + +**Teams Notifier's gitlab-mr-api component** + +| | | +|---|---| +| **homepage** | https://github.com/teams-notifier/gitlab-mr-api | +| **registry** | https://github.com/teams-notifier/gitlab-mr-api/pkgs/container/gitlab-mr-api | +| **image** | `ghcr.io/teams-notifier/gitlab-mr-api:latest` | + +## Intro + +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. + +Here's an example of a merge request message: +{{< img src="merge-request-card-example.png" style="margin-left: 0rem">}} + +## Config + +Environment variables or `.env`: + +* `PORT`: port to listen to (def: `3980`) +* `ACTIVITY_API`: `activity-api` base URL (ex: `https://activity-api:3981/`) +* `DATABASE_URL`: Database DSN in the form: `postgresql://{USER}:{PASSWORD}@{HOST}/{DATABASE}` +* `VALID_X_GITLAB_TOKEN`: comma separated list of Gitlab's Secret token (sent as `X-Gitlab-Token` header), uuidv4 generated seems a good choice. + +## Webhook config + +You'll need: +- one or more conversation tokens +- one of the `VALID_X_GITLAB_TOKEN` you generated + +On your GitLab repository, follow these steps to add a new webhook: + +1. Go to **Settings**. +2. Select **Webhooks**. +3. Click **Add new webhook**. +4. Fill out the form with the following details: + + * **URL**: https://hostname-of-this-api.example.org/api/v1/gitlab-webhook + * **Add custom header**: + * name: `X-Conversation-Token` + * value: comma separated list of conversation tokens you want the MR messages sent to + * **Secret token**: one of the `VALID_X_GITLAB_TOKEN` you generated + * **Trigger**, select: + * Merge request events + * Pipeline events + * Emoji events (planned) + +You can then save or test. +Note that for the test to work you need an existing MR in the project. + +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. + + +## Webhook declaration helper + +{{% details title="Environment variables" %}} +```bash +# Gitlab token with Admin or Maintainer right +GITLAB_TOKEN= + +# your gitlab url (opt. if gitlab.com) +#GITLAB_URL= + +# coma separated list of conversation tokens +CONVERSATION_TOKEN= + +# Gitlab secret matching one of the VALID_X_GITLAB_TOKEN +GITLAB_SECRET= + +# Full url of the accessible webhook https://gl-webhook.example.org/api/v1/gitlab-webhook +HOOK_URL= +``` +{{% /details %}} + +{{% details title="`setup-webhook.sh`" %}} + +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*. \ +Tested on Gitlab 17.6. + +```bash +#!/bin/bash + +# Takes a project id as first arg +# Optional conversation token override as second +set -euo pipefail + +[ -e .env ] && . .env + +[ -z "${1:-}" ] && echo "please provide a project id as first arg" && exit 1 + +PROJECT_ID=${1} +CONVERSATION_TOKEN=${2:-$CONVERSATION_TOKEN} + +GITLAB_URL=${GITLAB_URL:-gitlab.com} + +HOOK_COUNT=$(curl -s --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \ + https://${GITLAB_URL}/api/v4/projects/$PROJECT_ID/hooks/ \ + | jq 'map(select(.url | test("'${HOOK_URL}'")?)) | length') + +[ "$HOOK_COUNT" -gt 0 ] && echo "already a hook declared" && exit 1 + +curl \ + -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \ + -H 'Content-Type: application/json' \ + https://${GITLAB_URL}/api/v4/projects/$PROJECT_ID/hooks \ + -X POST -s -w $'\n' \ + --data-binary @- << EOF | jq . +{ +"name": "gitlab-mr-api", +"url": "$HOOK_URL", +"token": "$GITLAB_SECRET", +"custom_headers": [{"key":"X-Conversation-Token", "value":"$CONVERSATION_TOKEN"}], +"merge_requests_events": true, +"pipeline_events": true, +"emoji_events": true, +"push_events": false, +"tag_push_events": false, +"repository_update_events": false, +"issues_events": false, +"confidential_issues_events": false, +"note_events": false, +"confidential_note_events": false, +"wiki_page_events": false, +"deployment_events": false, +"feature_flag_events": false, +"job_events": false, +"releases_events": false, +"resource_access_token_events": false +} +EOF +``` +{{% /details %}} + diff --git a/content/docs/deployment/addons/gitlab-mr-api/merge-request-card-example.png b/content/docs/deployment/addons/gitlab-mr-api/merge-request-card-example.png new file mode 100644 index 0000000..0134e2a Binary files /dev/null and b/content/docs/deployment/addons/gitlab-mr-api/merge-request-card-example.png differ diff --git a/content/docs/deployment/core/activity-api.md b/content/docs/deployment/core/activity-api.md index b27a85d..b5849f8 100644 --- a/content/docs/deployment/core/activity-api.md +++ b/content/docs/deployment/core/activity-api.md @@ -6,7 +6,12 @@ next: /docs/deployment/addons/ *Teams Notifier's activity api component. Used to send/update/delete messages (activities) to MS Teams.* -homepage: https://github.com/teams-notifier/activity-api +| | | +|---|---| +| **homepage** | https://github.com/teams-notifier/activity-api | +| **registry** | https://github.com/teams-notifier/activity-api/pkgs/container/activity-api | +| **image** | `ghcr.io/teams-notifier/activity-api:latest` | + ## Intro diff --git a/content/docs/deployment/core/bf-directline-endpoint.md b/content/docs/deployment/core/bf-directline-endpoint.md index 859c27c..79fcf32 100644 --- a/content/docs/deployment/core/bf-directline-endpoint.md +++ b/content/docs/deployment/core/bf-directline-endpoint.md @@ -6,7 +6,12 @@ weight: 30 *Teams Notifier's bot framework directline component* -homepage: https://github.com/teams-notifier/bf-directline-endpoint +| | | +|---|---| +| **homepage** | https://github.com/teams-notifier/bf-directline-endpoint | +| **registry** | https://github.com/teams-notifier/bf-directline-endpoint/pkgs/container/bf-directline-endpoint | +| **image** | `ghcr.io/teams-notifier/bf-directline-endpoint:latest` | + ## Intro