Revetly
Manual 0.8.0

Connect a GitHub repository

Point one project at a repository on GitHub, so CONTEXT reads its issues and pull requests. The repository is named in the file, and its token is named in the environment.

Before you start

Configuration page

  1. Open the configuration page. If it is not open, run revetly config and open the address it prints.

  2. On the project's card, select Add source.

  3. Choose GitHub.

  4. Enter the repository in Repository, as owner/name.

  5. Enter the token in Key for the github connector. Leave the variable-name box above it alone.

  6. Select Save.

    You should see Access token: set on the card.

  7. On the same line, read the repository the card says it reads.

    You should see GitHub repository: <OWNER>/<REPOSITORY> on the card.

  8. Select Test connection on the GitHub line. Revetly answers with what it reached, and puts any advice after it.

    You should see https://api.github.com answers and <OWNER>/<REPOSITORY> resolves on the card.

  9. Select Show issue types on the GitHub line. Revetly lists each issue type the organisation enables, ticked, beside the item type of the same name it becomes.

  10. Untick each type this project should leave off the backlog.

  11. Select Save issue types. Revetly writes the type map, adds each item type the project lacks, and says where each new one may sit, in one save.

Command line

  1. In revetly.toml at the project root, add GitHub to the sources this project reads:

    # revetly.toml
[connectors]
enabled = ["pm", "docs", "conversations", "deliveries", "github"]

    Revetly replaces this list rather than merging into it, so it restates every source already read.

  2. In revetly.toml, name the repository in one table:

    # revetly.toml
[connectors.github]
repo = "owner/name"

    Replace the value with the repository your issues are in, or write repos = ["owner/a", "owner/b"] in its place where they live in several, each issue keeping its own repository's id and a new item landing in the repository the draft names, else its parent's, else the first listed.

  3. Read back the scope this instance will read:

    revetly doctor --offline

    [PASS] github: settings repo = '<OWNER>/<REPOSITORY>'

    Revetly reads an issue the type map leaves out, and every pull request unless [connectors.github] sets pull_requests = false, but keeps both off the backlog, and after a pass doctor's github: untyped items line counts the issues with no type.

  4. Read which variable the token is read from:

    revetly check

    connector 'github': GITHUB_TOKEN is not set in the environment — …

  5. In .env beside it, put the token that line named: 

    # .env
GITHUB_TOKEN=<GITHUB_TOKEN>

    Replace <GITHUB_TOKEN> with a fine-grained personal access token with Issues read, Pull requests read and Metadata read on the repository, adding the organisation's Issue types read if you map native types.

  6. Test the connection to GitHub: 

    revetly doctor

    [PASS] github: reachable  https://api.github.com answers and <OWNER>/<REPOSITORY> resolves

  7. Print the tables that map the organisation's issue types onto this project's item types: 

    revetly connectors issue-types --dry-run

    Nothing written (--dry-run).

    Revetly offers each type the organisation enables, mapped to the item type of the same name, with the item types and parent rules the project lacks.

  8. Write those tables to revetly.toml in one save: 

    revetly connectors issue-types

    If a type should stay off the backlog, add --skip and its name once per type.

  9. In revetly.toml, map labels where the repository belongs to a personal account:

    # revetly.toml
[connectors.github.types]
"label:story" = "story"

    Replace story after label: with the repository's own label name — native issue types exist only on organisation repositories, and the right side is one of [backlog] types.

Troubleshooting

Next steps