> 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/github-projects.md).

# GitHub Projects

[GitHub Projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects) is GitHub's flexible and configurable planning and task management system. Logilica supports GitHub Projects boards by importing them as **Planning data**.

Because GitHub Projects is highly customisable, a few naming conventions in your board let Logilica map your planning data correctly. These are described below.

## Authentication

GitHub Projects uses the **same access as the GitHub connector** — there is no separate authentication step. You connect GitHub once and select your Projects boards as planning data. The same authentication options apply:

* **OAuth** — authorise Logilica through GitHub's standard consent screen. This is the default way to connect GitHub.
* **Personal Access Token (PAT)** — supply a token with access to the project and its issues, for example on GitHub Enterprise or where OAuth is not available. The token needs the `repo`, `user:read`, and `user:email` scopes.
* **GitHub App installation** — install the Logilica GitHub App on your organisation. This is the recommended option for organisation-wide access and for **GitHub Enterprise** and **self-hosted GitHub**.

See [Connecting Tools](/integration/connecting-tools.md) for the general installation flow.

{% hint style="info" %}
Logilica imports modern **Projects v2** boards only. Classic GitHub Projects are not supported.
{% endhint %}

## What's Imported

For each GitHub Projects board you connect, Logilica imports:

* **Issues** — title, description, status, type, priority, labels, story points, and created/updated/closed dates
* **Draft issues** — title, description, status, author, and assignee (draft issues carry minimal data, so they have no labels, sprints, custom fields, or history beyond creation and assignment)
* **Issue history** — created, assigned, status-change, and closed (resolved) events from each issue's timeline
* **Sprints** — name and start/end dates, derived from a custom iteration field (see Sprints below)
* **Parent/child relationships** — sub-issues, and a parent issue when that parent is an `epic` (see Issue Types below)
* **Assignees and authors (reporters)** — user identity, name, and username (the author and reporter are the same person for GitHub Projects)
* **Linked pull requests** — see [Linking Pull Requests and Tickets](/integration/linking-pull-requests-and-tickets.md)
* **Custom fields** — other project fields you have added beyond the built-in ones are imported alongside each issue
* **Labels** — every label applied to imported 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 %}

## How Logilica Maps the Data

Logilica reads these values from either a [label](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/managing-labels) or a [custom field](https://docs.github.com/en/issues/planning-and-tracking-with-projects/understanding-fields) on the issue. Unless stated otherwise, all matching is case-insensitive.

### Issue Types

GitHub Project issue types are detected in two ways:

* A label on the issue that begins with `kind/` or `type/` — the text following the `/` is taken as the **issue type name**.
* The value of a custom field named either `kind` or `type` is taken as the **issue type name**.

**Note**: when both are present, the custom field takes precedence. Issues with no detected type default to `Issue`.

A parent issue is linked to its sub-issues only when the parent's type is `epic`. Sub-issues are still imported either way.

### Issue Status

Logilica categorises each item's GitHub **Status** into one of three categories:

* **To Do** — any item whose status is unset or matches `todo` or `to do`
* **In Progress** — any item whose status matches `in progress` or `in review`
* **Done** — any item whose status matches `done`

An item with no status set is recorded as `Not Set` and categorised as **To Do**.

### Sprints

Logilica detects sprints through the values used in a custom [iteration field](https://docs.github.com/en/issues/planning-and-tracking-with-projects/understanding-fields/about-iteration-fields) within imported issues. The custom iteration field must be named `sprint`. Each iteration's start date and duration are used to set the sprint's start and end.

### Other Fields

In addition to the above, the following fields are also supported:

* **Priority** — matches the value that appears after a label that starts with `priority/`, or a custom field on an issue named `priority`.
* **Story Points** — matches on a custom field within an issue named `story point` (the field name `story points` is also recognised).

{% hint style="info" %}
Field names are matched loosely, so a field named `story points` is recognised by the `story point` rule above.
{% endhint %}

## Best Practices

For Logilica to most accurately reflect the GitHub Projects data, we recommend following a few best practices in your GitHub Projects setup:

* Use labels or custom fields to define issue types with the convention explained [above](#issue-types).
* Use issue status such as `todo`, `in progress`, and `done` as explained [above](#issue-status).
* Make sure you are using the `iteration field` to define sprints.
* Define story points and priorities as described [above](#other-fields).

For more questions consult the GitHub Projects [documentation](https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects) or connect with your Logilica support representative.

## 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 updated within the last 6 months are imported on the first scan. Older issues that haven't been touched won't appear. Importing data older than 6 months requires a configuration change by Logilica — contact support.
* **Modern Projects v2 only.** Classic GitHub Projects are not imported.
* **Sprint end dates come from the iteration length.** GitHub iterations define a start date and a duration rather than an explicit end date, so a sprint's end is set from its start plus duration.
* **A single assignee is recorded.** GitHub issues can have multiple assignees, but Logilica records one — the most recent assignee from the issue's timeline (for draft issues, one of the listed assignees).