# Integrations & issue tracking

> https://docs.errora.org/en/products/integrations

Integrations connect Errora to your source control. That unlocks two things: **AI auto-fix**
(read source, open merge requests) and **issue tracking** (create or link a GitLab issue from
an Errora issue).

## Connect GitLab

**Settings → Integrations → Add integration**:

| Field | Notes |
| --- | --- |
| `provider` | `gitlab` (self-hosted or gitlab.com). `github` is scaffolded for a future release. |
| `base_url` | Your instance, e.g. `https://gitlab.example.com`. Defaults to `https://gitlab.com`. |
| `access_token` | A personal/group access token. Stored **encrypted at rest**. |
| `name` | A label, so several instances stay distinguishable |

Token scopes: `api` is the simplest working scope — Errora needs to list projects, read file
contents, create branches and open merge requests and issues.

```bash
curl -X POST "$ERRORA/api/v1/organizations/$ORG_ID/integrations" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider":"gitlab","base_url":"https://gitlab.example.com","access_token":"glpat-…","name":"Company GitLab"}'
```

Managing integrations requires the **`integration:manage`** capability.

## Sync repositories

After connecting, **Sync** pulls the repositories the token can see:

```text
POST /api/v1/organizations/{org_id}/integrations/{id}/sync
GET  /api/v1/organizations/{org_id}/integrations/{id}/repositories
```

Each repository is stored with its provider id, `path_with_namespace`, web URL and default
branch.

## Link a repository to a project

On the project's settings, pick the repository whose code produces that project's errors.
This is what [AI auto-fix](/en/products/ai-autofix) reads from and opens merge requests
against.

## Issue tracking from an issue

On any Errora issue you can:

- **Create a GitLab issue** — title and description are prefilled from the exception, the
  stack trace and a link back to Errora.
- **Link an existing issue** — search the repository's issues and attach one, optionally
  posting a comment with the Errora link.

Linked issues are listed on the issue page, so the next person sees the ticket without
digging.

```text
GET  /api/v1/projects/{project_id}/issues/{issue_id}/external-issues
POST /api/v1/projects/{project_id}/issues/{issue_id}/external-issues
GET  /api/v1/projects/{project_id}/external-issues/search?q=
GET  /api/v1/projects/{project_id}/issues/{issue_id}/repositories
```

## Troubleshooting

| Symptom | Cause / fix |
| --- | --- |
| Sync returns nothing | The token can't see any projects — check its scope and the group it belongs to |
| `401` from the provider | Token expired or revoked; re-enter it (tokens are write-only in the API) |
| Your GitLab instance unreachable | Errora calls it from its own servers, not from your browser — the instance must be reachable publicly, with a valid certificate |
| MR creation fails | The token lacks write access, or the default branch is protected against direct branch creation |