# GitLab integration

Create GitLab issues from feedback, using a personal access token.

Source: https://docs.annot8.app/docs/integrations/gitlab



**Pro and above.** Setup is a token and a project id.

<Callout type="info">
  GitLab.com only. Self-managed and dedicated GitLab instances aren't supported
  — issues are created against `gitlab.com`. Use a
  [webhook](/docs/integrations/webhooks) into your own endpoint if you run
  GitLab yourself.
</Callout>

## Connect [#connect]

<Steps>
  <Step>
    ### Create a personal access token [#create-a-personal-access-token]

    **GitLab → Preferences → Access Tokens**. Grant the `api` scope, set an expiry,
    and copy the value — it starts with `glpat-` and is shown once.

    A project access token or group access token works too, and is a better fit for
    a team.
  </Step>

  <Step>
    ### Find the project id [#find-the-project-id]

    **Project → Settings → General**, where the numeric **Project ID** is shown at
    the top.

    You can also use the URL-encoded path — `namespace%2Fproject` — but the numeric
    id is less fragile, since it survives renames.
  </Step>

  <Step>
    ### Connect in Annot8 [#connect-in-annot8]

    **Integrations** in the sidebar → **GitLab** → enter the token and project id →
    **Connect**, then **Test**.
  </Step>

  <Step>
    ### Choose which projects use it [#choose-which-projects-use-it]

    A new connection is on for every project. Switch GitLab off under **Project →
    Integrations** for any project that shouldn't use it.
  </Step>
</Steps>

## What gets created [#what-gets-created]

Every new thread on an enabled project creates a GitLab issue titled
`[Feedback] <comment>`, with the author, the comment, and a link to the page in
the description.

<Callout type="warn">
  This fires on every thread. Point it at a dedicated intake project rather than
  your main board.
</Callout>

## Troubleshooting [#troubleshooting]

**401.** The token was revoked or has expired. GitLab enforces a maximum token
lifetime on many plans, so tokens die on a schedule — set a calendar reminder.

**403.** The token lacks the `api` scope, or the account can't create issues on
that project. Reporter role or above is required.

**404.** Wrong project id, or the token can't see the project. If you used a
path rather than a numeric id, make sure the `/` is encoded as `%2F`.