# Import from GitHub Issues

> Bring GitHub issues into By Dawn through your organization's GitHub App, from one or more repos, with milestones and sub-issues.

This page helps you bring the issues from your GitHub repos into By Dawn. At the end they're By Dawn tickets, linked to
the issues they came from, and, if you chose to keep syncing, the two stay in step until your end date.
[Import and sync](https://docs.bydawn.com/import-and-sync/) explains the steps every tracker shares, so this page covers only
what's particular to GitHub.

## Before you start

- You need to be a project admin in By Dawn.
- The By Dawn GitHub App must be installed on the GitHub organization or account that owns the repos, with access to
  them. There's no token to paste: By Dawn uses the App, the same one that pushes ticket branches and opens pull
  requests. If the App can't read issues in a repo, ask whoever installed it to accept its Issues permission.

## Connect

1. In By Dawn, open **Settings › Import & sync › New import** and pick **GitHub Issues**.

2. Choose **Use it**.

## Pick what to bring

Pick a **repository**. All of its issues come over, open and closed. Pull requests are left out.

## How GitHub maps

- **Statuses.** Open issues go to a to-do column and closed ones to a completed column. An issue closed as *not
  planned* or as a duplicate also lands in a completed column, with a `resolution:` label, so it isn't counted
  as finished work.
- **Priorities.** GitHub has no priority field, so tickets come in with no priority.
- **Milestones** become By Dawn milestones, all held in one epic named after the repository, or `milestone:` labels if you
  prefer. A milestone with the same name in several repos becomes one By Dawn milestone.
- **Sub-issues** become sub-tickets.
- **Assignees.** The first assignee becomes the ticket's assignee; the rest are kept on the ticket. GitHub shows
  emails only when people make them public, so expect to pair some people by hand.
- **Images and files** in an issue stay as links to GitHub.

Each imported ticket is also linked to its issue, so the issue shows on the card the same way as an issue linked
by hand (see [GitHub issues](https://docs.bydawn.com/github-issues/)).

> **Issues you already linked by hand:** An import doesn't take over an issue that's already linked to a By Dawn ticket by a person or a worker. It creates a
> new ticket for it. The dry run lists those issues, so you know before you import.

## When you sync both ways

By Dawn writes back the title, description, open or closed state, assignees and labels, plus new comments. It writes
as the App, so changes on GitHub show the App's bot as their author. Priority and due dates aren't written back,
because GitHub has neither.

GitHub tells By Dawn when an issue or its comments change, so edits usually reach By Dawn within seconds.

## Where to go next

- [GitHub issues](https://docs.bydawn.com/github-issues/): what a worker can do with issues, and linking by hand.
- [Import and sync](https://docs.bydawn.com/import-and-sync/): conflicts, pausing and ending a sync.

Source: https://docs.bydawn.com/import-github-issues/