Intake
GitHub issues

GitHub issues

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). 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). 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.