Manual 0.8.0

Write approved stories to GitHub

Point an approved draft at a GitHub repository, so approving a draft creates an issue there, and shipping closes it and leaves a delivery note on it. The read connector and the write adapter share one [connectors.github] table.

Before you start

Connect a GitHub repository
A repository whose issues you want written, and a fine-grained token with Issues read and write and Metadata read on the repository; add the organisation's Issue types read if you map native types.

Configuration page

Open the configuration page. If it is not open, run revetly config and open the address it prints.
On the project's card, select Show 5 more.

You should see Approved item store on the project's card.
Choose GitHub board in Approved item store.
Select Save.
Read the checks from step 2 under the command line below. Revetly runs the doctor's checks and the rehearsal there, and the page runs neither.

Command line

In revetly.toml at the project root, name GitHub as the approved item store:
```
# revetly.toml
[backend]
pbi = "github"
```
Revetly refuses a label the repository lacks rather than creating it, so the draft, in-progress and parked labels the status map names must already exist, and a label: type label is refused when the first draft is written.
Read that the token may write, that the creatable types resolve, and that the labels the status map names exist:
```
revetly doctor
```
```
[PASS] github: credential  GITHUB_TOKEN is set (<COUNT> chars)
[PASS] github: repository  writes <OWNER>/<REPOSITORY>
[PASS] github: creatable types  creates story -> '<NATIVE_TYPE_OR_LABEL>'
[PASS] github: notes author  delivery notes will appear under GitHub account '<LOGIN>'
```
If the organisation's Issue types read is missing, the adapter sends the native type unchecked and falls back to the mapped label on a 422, and raises the 422 where no label: mapping exists for that type.

Show the calls a draft would make, without writing anything or reading the token:

revetly backends rehearse github --project <PROJECT>

  would call  POST https://api.github.com/repos/<OWNER>/<REPOSITORY>/issues
              {"title": "A rehearsal, not a story", "body": "<BODY>", "labels": ["story"]}

Replace <PROJECT> with the key of the project whose GitHub write adapter you rehearse, or leave it off to rehearse the default project.

Warning

A repository connected before the in-progress status existed lacks that label, and doctor names it under label 'in-progress' until it is created. Where [connectors.github] lists several repos, a new item lands in the repository the draft names, else its parent's, else the first listed, a name outside the list is refused before anything is sent, and doctor checks write access, types and labels in each listed repository. A draft with a parent becomes a native sub-issue, in another listed repository too. If that link fails after the issue was created, the approval is recorded under the issue's own id and the reply says the item exists but is incomplete, naming what did not land. Link it by hand on GitHub; the next ingest reads the issue as it stands, and approving the draft again is refused against the id it already landed as rather than creating a duplicate. GitHub's issue listing can trail a write by a few seconds. Shipping a story held here posts its delivery record as one comment on the issue, under the account the notes author line names, and adds a Delivered: line to the issue's ## Revetly section. A note that fails after the record landed is reported half-landed, and revetly deliveries post-note <DEL-ID> completes it without a second comment. Turning off Tracker delivery note on the project's card, or [backend] tracker_note = false, posts no note; the local delivery record is written either way. Setting a story in-progress keeps the issue open, adds the in-progress label and posts one claim comment naming who has it, edited in place on a takeover.

Read the status map the write adapter uses, the line without the default: prefix:
```
revetly doctor --offline
```
```
[PASS] github: status map  draft = open + label draft; ready = open; in-progress = open + label in-progress; done = closed + completed/(no reason); parked = open + label parked; discarded = closed + not_planned/duplicate
```
Replace the defaults with a [connectors.github.states] table where a status needs another state, reason or label — a bare state string only where it is distinguishable from the other entries, or a { state, reason, label } table, merged over the defaults, and two indistinguishable entries are refused.

Write approved stories to GitHub

Before you start

Configuration page

Command line

Next steps