GitHub Projects

GitHub 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 for the general installation flow.

Logilica imports modern Projects v2 boards only. Classic GitHub Projects are not supported.

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

• 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

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.

How Logilica Maps the Data

Logilica reads these values from either a label or a custom field 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 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).

Field names are matched loosely, so a field named story points is recognised by the story point rule above.

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.

• Use issue status such as todo, in progress, and done as explained above.

• Make sure you are using the iteration field to define sprints.

• Define story points and priorities as described above.

For more questions consult the GitHub Projects documentation 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).