GitHub
A bot connected to GitHub reads issues, pull requests, commits and releases, and proposes comments, labels, closing, new issues and draft releases. It does not write code: there is no tool that merges, pushes, deletes or publishes. Everything it writes is seen by others in your name, so it is Send and waits for you.
The recipe Dev Desk comes with Huskarl for this. See Recipes.
Connecting
GitHub is connected with a token you make for the bot, not with a sign-in. A fine-grained token reaches only the repositories you pick, with only the permissions you give, so it can be smaller than any sign-in would be.
- In the bot's settings, under Connections, click Connect on the GitHub row with the field empty. GitHub opens on a new fine-grained token, named Huskarl, with the permissions filled in where GitHub takes them from the address.
- Under Repository access, choose Only select repositories and pick the ones the bot may see.
- Check the permissions: Issues: read and write. Pull requests and Contents: read. Metadata: read (GitHub adds it). Give it nothing else. Without Contents, the bot cannot read commits for release notes, and without write on Issues, nothing it proposes can be carried out.
- Make the token, paste it in the field and click Connect.
The daemon tries the token on GitHub before it keeps it. If GitHub takes it,
the thread says "✓ Connected to GitHub as no.huskarl.github, with your GitHub login as the account.
If not, the settings say why, and nothing is kept.
From the terminal, the token comes on stdin, never as an argument others could see in the process list:
pbpaste | huskarld connect <bot> github
huskarld connect <bot> github < /dev/null # prints where to make a token
A new token for the same login replaces the old one, for every bot connected with that login. Disconnecting deletes the token from the Keychain when no bot uses the login any more. A fine-grained token expires (90 days, as the page suggests); after that, GitHub refuses it, the bot is told to have you connect again, and you make a new one.
Tools
| Tool | Class | What |
|---|---|---|
github_list_repos |
Read | the repositories the token reaches, the most recently pushed first |
github_list_issues |
Read | issues and pull requests in a repository (state, labels, since, max up to 100), the most recently updated first |
github_search |
Read | GitHub's issue search, in one repository or all, to find duplicates |
github_read_issue |
Read | an issue or pull request with its text and comments, oldest first |
github_read_pull |
Read | a pull request: what it says, the files it changes, and its checks |
github_commits |
Read | commits from a tag, branch or commit to another, or the latest |
github_releases |
Read | the latest releases, with the start of their notes |
github_comment |
Send | a comment on an issue or pull request: "Comment on GitHub: octo/web#7 «Crash on start»" |
github_label |
Send | labels added or removed |
github_close |
Send | closes an issue as done or not planned, with a comment first if given |
github_create_issue |
Send | a new issue |
github_draft_release |
Send | a draft release with notes. It is not published: you publish it on GitHub |
A repository is always owner/name. Anything else (octo/../user, a path, a
query) is refused before it can become a proposal, and so is a number that is
not one.
Everything read from GitHub is outside text: issues, comments, commits and pull requests are written by others, and cannot give the bot instructions. See Security.
What the bot cannot do
- Merge, push, change files, or delete anything.
- Publish a release. A draft is as far as it goes.
- Change settings, collaborators, secrets or workflows.
- Reach repositories the token does not.
huskarld check
huskarld check <bot> also lists the repositories the token reaches:
"GitHub: ok (3 repositories)".