⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.
TypeScript honoissue-managementissue-trackerjira-alternativekanbanlinear-alternativemcpproject-managementreactself-hostedtypescript
docs: gitlab integration guide
zaralXad937f7c31cc
diff --git a/apps/docs/core/integrations/gitlab/setup.mdx b/apps/docs/core/integrations/gitlab/setup.mdxnew file mode 100644index 000000000..424c393bc--- /dev/null+++ b/apps/docs/core/integrations/gitlab/setup.mdx@@ -0,0 +1,62 @@+---+title: GitLab Setup+description: Connect Kaneo to GitLab.com or a self-managed instance (issues, merge requests, webhooks).+---++## Overview++The GitLab integration links a Kaneo project to a project on GitLab.com or your own instance. Tasks sync with issues, and webhooks keep Kaneo updated when issues, merge requests, or pushes change.++You need:++- **GitLab URL**: `https://gitlab.com`, or e.g. `https://gitlab.example.com`.+- **Access token** with the `api` scope and at least the **Developer** role on the target project.+- **Project path**: the full path including any groups, same as in the GitLab UI.++## Access token++1. In GitLab, open **Settings → Access tokens → Add new token** (personal, project, and group tokens all work).+2. Enable the **api** scope and pick a role of **Developer** or higher.+3. Copy the token and store it securely; paste it into Kaneo’s GitLab integration settings and leave **Token type** on **Personal, project or group access token**.++To use an OAuth2 token you already hold, switch **Token type** to **OAuth2 token**; Kaneo then sends it in `Authorization` instead of `PRIVATE-TOKEN`. GitLab expires OAuth2 tokens two hours after they are created, so an access token is the better fit for a long-lived link.++## Webhook in GitLab++Kaneo verifies incoming webhooks with a **secret token** stored per integration, which GitLab sends back in a header rather than signing the payload, so serve Kaneo over HTTPS.++### Where to create the webhook in GitLab++1. Log in to GitLab and **open the same project** you linked in Kaneo (`group/project`).+2. Open the project **Settings**.+3. In the **left sidebar**, open **Webhooks** (under the “Settings” section).+ - If you do not see it, you need at least the **Maintainer** role on that project.+4. Click **Add new webhook**.++**Direct URL pattern** (replace host and project path):++`https://<your-gitlab-host>/<project path>/-/hooks`++Example: `https://gitlab.com/acme/my-app/-/hooks`++### Configure the webhook++1. Connect the project in Kaneo **Project → Integrations → GitLab** and save.+2. Copy the **Webhook URL** and **Secret token** shown in Kaneo (after saving).+3. In GitLab: **Settings → Webhooks → Add new webhook**.+4. Set **URL** to the Kaneo webhook URL.+5. Set **Secret token** to the exact value from Kaneo.+6. Leave **Enable SSL verification** on, unless your Kaneo host uses a self-signed certificate.+7. Enable triggers:++ - **Push events**+ - **Issues events**+ - **Comments**+ - **Merge request events**++8. Save and use **Test → Push events** to confirm a `200` response from Kaneo.+ - If Kaneo runs on a private address, an administrator must first enable **Admin → Settings → Network → Outbound requests → Allow requests to the local network from webhooks and integrations**.++The webhook URL includes your integration id, for example:++`https://your-kaneo-host/api/gitlab-integration/webhook/<integrationId>`diff --git a/apps/docs/index.mdx b/apps/docs/index.mdxindex c4d1771c5..8993c2abf 100644--- a/apps/docs/index.mdx+++ b/apps/docs/index.mdx@@ -12,6 +12,7 @@ This docs site is built to get you from zero to a running instance fast, then he- [Installation Guide](/core/installation/index) to choose drim vs Docker Compose- [GitHub Integration Setup](/core/integrations/github/setup) for repo sync- [Gitea Integration Setup](/core/integrations/gitea/setup) for self-hosted Gitea+- [GitLab Integration Setup](/core/integrations/gitlab/setup) for GitLab.com or self-managed GitLab- [Outgoing webhooks](/core/integrations/outgoing-webhooks) for Slack, Discord, and custom HTTP notifications- [API Introduction](/api-reference/introduction) for authenticated API usage