Skip to main content

​
🦊 GitLab (team feature)

Connecting GitLab has two directions:
  • Outbound (Nota → GitLab) — Nota reads merge requests, posts comments, and files issues. Needs an access token.
  • Inbound (GitLab → Nota) — @nota mentions in comments get an in-thread reply and merge-request opens auto-run your workflows. Needs a webhook.
Set up outbound first, then inbound.

​
Outbound — let Nota act on your project

​
Step 1 — Create the GitLab access token

In GitLab:
  1. Click your profile icon (top-right) and open Preferences.
  2. In the left navigation pane, click Access, then Personal access tokens.
  3. Create a fine-grained or legacy (classic) token, whichever fits your policy.
  4. Set a Name (e.g. nota-integration) and an Expiration date — plan to rotate.
  5. Under Resource access (fine-grained) or Scopes (legacy), grant what Nota needs:
    • api — minimum for reading MRs / issues and posting comments.
    • read_repository — recommended so Nota can read repo contents.
Click Create, then copy the glpat-... token immediately — GitLab shows it only once.
If you post as a dedicated service user (e.g. nota-bot), create this token while logged in as that bot user so Nota’s comments and issues appear under the bot, not under you.

​
Where to add it in Nota

In Nota → Settings → Integrations → GitLab → Configure, paste the token into the GitLab Access Token field. Save — Nota uses it immediately, no redeploy needed.

​
Step 2 — Set the Default Project Path (optional)

The Default Project Path is the project Nota files issues to from automated workflow notifications. It’s the full URL path including the repo name. Take everything after gitlab.com/, including the repo name:
A numeric GitLab project ID (e.g. 12345678) is also accepted — GitLab’s REST API resolves both shapes identically. Do not include the host or a leading slash.
In the same GitLab → Configure panel, enter it in the Default Project Path field and Save.
This field affects outbound issue filing only. Leaving it blank uses per-event project context instead. Don’t confuse it with the Namespace Path used for inbound webhook routing below — that one is the group without the repo name.

​
Inbound — @mentions & merge-request events

Wire GitLab to post events into Nota. Follow the steps in order — you’ll create a secret, add a webhook in GitLab, then match it in Nota.

​
Step 1 — Generate a webhook secret

Generate a high-entropy secret and save it — you’ll paste the same value into GitLab (Step 4) and Nota (Step 5):
GitLab echoes this back in the X-Gitlab-Token header and Nota exact-matches it. On the hosted app it’s required — without it, events fail.

​
Step 2 — Open your project

Go to gitlab.com/dashboard/home. In the left navigation, click Projects and select the project you want to connect.

​
Step 3 — Identify your Namespace Path

Your Namespace Path is the URL segment(s) before the repo name. Save it for Step 5: Enter the URL slug — not the display name, not a full URL, no leading slash.

​
Step 4 — Add the webhook in GitLab

In your project’s left nav, select Settings → Webhooks, then Add new webhook.
If Settings isn’t visible you lack the required project role — consult your GitLab org admin (you need Maintainer or Owner).
Fill in: Under Trigger, enable the events Nota uses: Leave the rest unchecked. Click Add webhook.

​
Step 5 — Configure Nota

Go to app.trynota.ai/integrations and click GitLab Settings. Fill in: Click Update Settings.

​
Step 6 — Test it

Back on the GitLab webhook page, click Test → Comments. You should see:
That confirms the webhook is authenticated and routed to your team.
Try a real mention. Comment @nota-bot what does this change do? on a real MR or issue — Nota replies in-thread within a few seconds. Comment edits are ignored (only new comments trigger a reply), so post a fresh comment rather than editing one.

​
Troubleshooting

Use short-lived tokens when possible, and rotate the access token and webhook secret if you move repositories, change scopes, or suspect either has leaked.