> For the complete documentation index, see [llms.txt](https://docs.logilica.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.logilica.com/integration/connecting-tools/gitlab-issues.md).

# GitLab Issues

This guide covers how Logilica imports issues, epics, iterations, and history from GitLab, and how issue states, labels, and types are categorised. It applies to the issue-tracking side of GitLab; merge requests and commits are handled by the GitLab code connector. GitLab cloud (gitlab.com) and self-hosted instances are both supported.

## Authentication

GitLab Issues uses the **same Personal Access Token (PAT)** as the GitLab code connector — there is no separate authentication step. The token is sent as a private token on every request and grants read-only access. The shared GitLab token needs the `read_api`, `read_user`, and `read_repository` scopes. See [Connecting Tools](/integration/connecting-tools.md) for the installation flow.

## What's Imported

For each GitLab project you connect, Logilica imports:

* **Issues** — title, description, state, severity (used as priority), labels, due date, created/updated/closed dates, and time tracking (estimate and total time spent)
* **Epics** — imported for projects that belong to a GitLab **group** (personal projects have no epics)
* **Iterations** — name, state, goal/description, and start date, mapped to Logilica sprints
* **Issue history** — created, assigned, closed (resolved), reopened, sprint-change, and in-progress events
* **Story point estimates** — taken from the issue **weight**
* **Custom workflow labels** that represent in-progress states (see State Mapping below)
* **Labels** — both group-level and project-level labels
* **Linked merge requests** — see [Linking Pull Requests and Tickets](/integration/linking-pull-requests-and-tickets.md)
* **Assignees, authors (reporters), and resolvers** — user identity, name, and username (the author and reporter are the same person for GitLab issues)

{% hint style="info" %}
If your issue descriptions contain sensitive content, you can exclude them after installation with the **Ignore Ticket Description** toggle under **Import Configuration** on the connector page.
{% endhint %}

## Issue State Mapping

GitLab issues have only two native states, `opened` and `closed`, which map as follows:

| GitLab State | Logilica Category |
| ------------ | ----------------- |
| `opened`     | **To Do**         |
| `closed`     | **Done**          |

GitLab has no native **In Progress** state, so Logilica reads it from your **project board columns**. An open issue sitting in a board column other than your To Do or Done columns is categorised as **In Progress**, and its status takes that column's name.

{% hint style="info" %}
An open issue in a column named anything other than your To Do or Done columns — for example `Doing`, `In Review`, or `QA` — is categorised as **In Progress**, and its status name is set to that column's name. Matching is case-insensitive.
{% endhint %}

In practice this means:

* An `opened` issue with no in-progress workflow label stays in **To Do**.
* An `opened` issue in an in-progress board column is categorised as **In Progress**.
* A `closed` issue is always **Done**, regardless of labels.

## Field & Type Configuration

GitLab issue fields are read automatically — there are no custom field names you need to set:

| GitLab Field  | Used For                                                  |
| ------------- | --------------------------------------------------------- |
| **state**     | Base status category (`opened` / `closed`)                |
| **weight**    | Story point estimate                                      |
| **severity**  | Issue priority                                            |
| **labels**    | Labels, and in-progress categorisation from board columns |
| **iteration** | Sprint membership                                         |
| **due date**  | Due date                                                  |
| **epic**      | Parent epic linkage                                       |

### Story points

Story points come from the issue **weight**. If a team does not set weights, story point estimates will be zero.

### Issue type and hierarchy

Logilica imports two kinds of planning item from GitLab: **Issues** (treated as standard issues) and **Epics** (treated as epics). Issues are linked to their parent epic automatically. There is no deeper custom-type hierarchy — GitLab's newer custom work item types are not yet imported as distinct types.

{% hint style="info" %}
Epics live at the **group** level in GitLab. A project that is not part of a group (a personal project) has no epics, so epic import is skipped for those projects.
{% endhint %}

## Good to Know

* **Kept in sync automatically.** After the initial import, Logilica refreshes this connection on a regular schedule — you don't need to re-trigger imports.
* **First import covers the last 6 months.** Only issues, epics, and iterations updated within the last 6 months are imported on the first scan. Older items that haven't been touched won't appear. Importing data older than 6 months requires a configuration change by Logilica — contact support.
* **In Progress depends on board labels.** Without project boards whose lists use distinct workflow labels, GitLab issues only ever appear as **To Do** (open) or **Done** (closed). To see an In Progress stage, set up board columns for your in-progress states.
* **Subtasks are not imported.** GitLab issue tasks/sub-items are not yet brought in as subtasks.
* **Iterations may be unavailable.** If the connecting token cannot read iterations (for example on a plan that doesn't include them), iteration import is skipped and issues will simply have no sprint membership.