# GitHub issues

> How By Dawn reads, opens and comments on GitHub issues in your repos, and how a ticket links to them.

This page explains what By Dawn does with the GitHub issues in your repos, so you know what to expect on
GitHub and on the board. By the end you'll know which issues a worker can touch, how its comments and
issues look on GitHub, and what each refusal means.

By Dawn works with issues through its GitHub App, the same App that pushes ticket branches and opens pull
requests. A **worker** (the agent working a ticket) can read, open and comment on issues, and link an
issue to its ticket. People link and unlink issues from the ticket in By Dawn. Either way, the board card
shows the linked issues, so you can see at a glance which GitHub issues a ticket is about.

## What a worker can do

A worker reaches GitHub issues only through By Dawn, never with a GitHub credential of its own. That's why
everything it writes is posted by the App, under the App's bot account, and is limited to the ticket's
own repos.

| Action | What happens |
| --- | --- |
| List issues | Reads a repo's issues live from GitHub, open by default. Pull requests are left out. |
| View an issue | Reads one issue with its body and its latest 30 comments. |
| Comment | Posts a comment on the issue as the App's bot. |
| Open an issue | Opens a new issue as the App's bot, and links it to the ticket. |
| Link an issue | Links an existing issue to the ticket, so it shows on the card. |

A worker can only touch issues in the repos the ticket is bound to. That keeps one ticket's agent from
writing to repos it was never asked to work in. When a ticket has one repo, the worker doesn't need to
name it.

Anything a worker writes ends with a short footer naming the ticket. That way someone reading the issue
on GitHub knows which ticket wrote it.

A worker running a read-only job, such as a planning run, can list and read issues but can't comment,
open or link them.

## Limits

By Dawn caps what one ticket's worker can write, so a worker stuck in a loop can't flood your repo:

- at most **5** issues opened from one ticket
- at most **30** comments from one ticket per day

Reading isn't capped by By Dawn. GitHub's own rate limits still apply.

## Linking issues from By Dawn

Open a ticket and find **GitHub issues**, under the pull requests. Choose **Link**, paste the issue's
URL (for example `https://github.com/acme/web-app/issues/42`) and press Enter. You can link an issue
from any repo in the ticket's project, not only the ticket's own repos. Unlinking removes the link from
the ticket. It doesn't change the issue on GitHub.

Each row shows the issue's number, title and whether it's open or closed. Issues the worker opened are
marked **Opened by SAW**. The card on the board shows one linked issue as its number (`#42`) and several
as a count (`3 issues`).

By Dawn keeps a copy of each linked issue's title and state. When you open the ticket, any copy older than
five minutes is refreshed from GitHub, so the card can lag behind GitHub for a few minutes.

## Importing a repo's issues

To bring a repo's existing issues in as tickets, rather than linking them one by one, import them (see [Import
from GitHub Issues](https://docs.bydawn.com/import-github-issues/)). Each imported ticket is linked to its issue the same way, so it
shows on the card like any other link. An import never takes over an issue someone already linked by hand: it
creates a new ticket for that issue.

## When By Dawn refuses

A refusal comes back in the usual error envelope (see [Responses and errors](https://docs.bydawn.com/developers/responses-and-errors/)).
The `message` says exactly what went wrong, so show it to the person rather than writing your own.

| Slug | Status | Why |
| --- | --- | --- |
| `forbidden` | 403 | The App hasn't been granted **Issues** on your GitHub organization, or the job is read-only. |
| `repo_not_bound_to_ticket` | 403 | The repo isn't one of the ticket's repos. |
| `not_found` | 404 | There's no issue with that number, the number belongs to a pull request, or the link doesn't exist. |
| `rate_limited` | 429 | The ticket reached its limit of issues opened or comments posted today. |
| `validation_error` | 422 | The URL isn't a GitHub issue URL, or a title or comment is empty or too long. |

> **Granting Issues to the App:** The App asks for **Issues: Read and write** when it's installed. If your organization installed
>   it before that permission was added, an organization owner has to accept the new permission on
>   GitHub (**Settings › GitHub Apps › SAW › Review request**). Until then, issue actions are refused
>   with `forbidden`.

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