Ghurlbot (GitHub URL robot) is an IRC bot that looks up GitHub issues, pull requests or discussions, creates new issues and action items, or closes them. It typically has the nickname ‘gb’ on IRC, which is what we will use here.
This manual describes how to interact with a running gb on IRC. A separate manual is included in the program source and describes how to run ghurlbot.
Commands for gb, as well as names of repositories and names of people, are case-insensitive. E.g., ‘issue’ can also be written as ‘ISSUE’ or ‘iSSue’; and ‘use w3c/scribe2’ can also be written as ‘USE W3C/SCRIBE2’ or ‘Use W3c/Scribe2’.
When somebody types something that looks like a repository name
followed by # and an issue number, gb responds
with the full URL of that issue, action item, pull request or
discussion:
<joe> Let's talk about foo/bar#13. <gb> https://github.com/foo/bar/issues/13 -> #13
(The -> is understood
by scribe.perl and causes the URL to be formatted as a link when
scribe.perl generates HTML from the IRC log.)
Gb also tries to look up the issue on GitHub. If it succeeds, it not only shows a URL, but also a summary, e.g.:
<joe> Next topic: w3c/scribe2#15 <gb> https://github.com/w3c/scribe2/issues/15 -> CLOSED Issue 15 Feature request: syntax for verbatim lines of code (by dbooth-boston)
Gb fails to look up an issue if it does not have access to a GitHub account or if the issue is in a private repository, see ‘GitHub account’. Gb may also fail due to network problems. In these cases the URL is unverified and may be wrong.
If you have told gb what repositories you are discussing (see below), you can abbreviate the repository name, or even omit it:
<joe> Next topic: #15 <gb> https://github.com/w3c/scribe2/issues/15 -> Issue 15 [closed] Feature request: syntax for verbatim lines of code (dbooth-boston)
If you have told gb to look at more than one repository, the above will only look in the repository that was added last. To look up an issue in one of the other repositories, prefix the number with the name of the repository:
<joe&lgt; Let's talk about aria#13.
The prefix only needs to be long enough to be unambiguous. So if there are no other repositories known to gb that start with an ‘a’, it is enough to say
<joe> a#13
You can optionally include the repository owner in the prefix:
<joe> w3c/a#13
Only if none of the repositories that gb knows start with those letters, gb assumes that the given name represents the full name of a repository.
In that case you can omit the owner if it is the same as the repository at the top of gb's list:
<joe> Is scribe2#3 the same issue? <gb> https://github.com/w3c/scribe2/issues/3 -> Issue 3 [closed] Errors replacing URLs (nigelmegitt)
When gb sees a URL that looks like the URL of an issue, pull request or discussion on GitHub, it will try to retrieve its summary from GitHub. E.g.:
<joe> topic: https://github.com/w3c/scribe2/issues/15 <gb> https://github.com/w3c/scribe2/issues/15 -> CLOSED Issue 15 Feature request: syntax for verbatim lines of code (by dbooth-boston)
When somebody types @ plus a name, gb responds with
the full URL to that person or team. E.g.:
<joe> That comment came from @aliciag <gb> https://github.com/aliciag -> @aliciag
gb only expands a reference that is on in its own, not one that seems to be attached to something else, such as an email address (e.g., ‘contact@aliciag.com’). If gb does not seem to recognize a reference, try to put spaces around it.
Because gb is often used on channels where RRSAgent is also active, it assumes lines that look like substitution and insertion commands for RRSAgent (more precisely: scribe.perl) are indeed that, and are not meant to be interpreted by gb. E.g., it will not look up issues 14 and 15 when lines looks like this:
<joe> s/like #14/like #15/ <joe> i/Discuss/topic: #15/
Also, borrowing a convention from the MarkDown markup language often used on GitHub, gb assumes that text enclosed in equal numbers of backquotes is a code span in some programming language. Thus, gb will not see ‘@context’ as a user name in these lines:
<joe> Use the JSON-LD `@context` <eva> How do you use ```@context```?
To be able to refer to issues, actions, pull requests and discussions with the abbreviated syntax, you need to say what repository is being discussed on this channel:
<joe> gb, discussing https://github.com/xxx/yyy
Instead of discussing, you can also
use discuss, use, using, take
up, taking up, this will be
or this is.
The prefix ‘https://github.com/’ is assumed, so you can also say:
<joe> gb, discussing xxx/yyy
You can list mutliple repositories. And if you previously specified a repository with the same owner, you can also omit the owner:
<joe> gb, discussing yyy, zzz
Every time you use the command, gb will add the given repository to its list. (Or move it to the top of the list, if it was already in the list.)
You can also use the syntax of scribe.perl (version 205):
<joe> repo: xxx/yyy, zzz
Instead of repo, you can also
use repos, repository or
repositories.
Gb remembers the repositories even when it is dismissed from a channel. When it is later asked to rejoin, it continues using the same repositories.
To remove a repository from the list that gb knows:
<joe> gb, drop xxx/yyy
Instead of drop, you can also
say forget, remove, don't
use or do not use.
You can list multiple repositories. And you can also use the syntax of scribe.perl (version 205):
<joe> repo- xxx/yyy
To remove all repositories, you can use an
empty repo command:
<joe> repo:
You can create new issues by starting a line
with issue::
<joe> Issue: is the default 1 or 0?
The issue will be created in the repository that is at the top of gb's list. To create an issue in another repository, you need to move it to the top first.
You can create an action item for somebody with the following three syntaxes:
<joe> action alex: review chapter 1 <joe> action: alex to review chapter 1 <joe> action: alex: review chapter 1
You can assign an action to several people at once by separating their names with commas and/or the word ‘and’. E.g.:
<jope> action alex, kylie, coen: review chapter 1 <joe> action: alex, kylie and coen to review chapter 1
The action will be created in the repository that is at the top of gb's list.
You can only assign an action to somebody who is associated with that repository (an owner or a collaborator).
You can optionally prefix the assignee with @:
<joe> action @alex: review chapter 1
Instead of somebody's GitHub account name, you can use an IRC nick or an alias, but only if gb knows what the corresponding GitHub account is. See ‘Mapping names to GitHub accounts’.
By default, an action gets a due date in one week, but you can explicitly set a date:
<joe> action alex: review chapter 1 - due 1 June
Many different ways of describing a date are supported, including things like ‘in 2 weeks’, ‘tomorrow’ and ‘next Tuesday’.
You can close an issue, action, pull request or discussion by
starting a line
with close, followed by an issue number or a URL,
e.g.:
<joe> close aria#15 <joe> close #13 <joe> close w3c/aria#17 <joe> close https://github.com/w3c/scribe2/issues/15
The issue number can include the full name of the repository or an abbreviation, see ‘IRC command to link to an issue: #’.
You can reopen an issue, action, pull request or discussion by
starting a line
with reopen, followed by an issue number or a URL,
e.g.:
<joe> reopen #15 <joe> reopen https://github.com/w3c/scribe2/issues/15
If you create or edit an action by hand directly on GitHub, Gb can still recognize it if you follow the following rules:
An issue must have the label ‘action’ to be recognized as an action. (It may have additional labels.)
It must have one or more assignees.
If it has a due date, the due date must start with the word ‘due‘ and a colon (:) and look like either
due: YYYY-MM-DD
or
due: YYYY-MM-DD (comment)
where YYYY is the year (4 digits), MM is the month (2 digits), DD is the day (2 digits). E.g., ‘2023-08-30’. The comment between parentheses is arbitrary text. The word ‘due’ may have both upper- and lowercase letters (‘DUE’, ‘Due’, ‘DuE’, etc.). A due date must be all on one line with nothing before it except maybe some white space and nothing after it except possibly white space and/or a period. (If there are multiple lines with due dates, Gb will use the first one.)
For comparison, actions created by Gb itself have three lines in the body: A line that says that the action was created as a result of a command on IRC, an empty line, and a line with a due date. Example:
Opened by Eve via IRC channel #aria on irc.w3.org Due: 2023-11-01 (Wednesday 1 November)
You can add a comment to an existing issue, action, pull request
or discussion, with
commands note and comment, like
this:
<joe> Note #17: Also related to http://example.org <joe> Comment aria#17: Great comment! <joe> comment https://github.com/w3c/scribe2/issues/15: Agreed. <joe> aria#17 note: discussed on 2024-04-25 <joe> aria#17 comment: See also aria#18.
The colon (:) may be omitted. Gb will respond with a pointer to the newly created comment on GitHub.
You can ask for lists of issues or actions:
<joe> list open issues <joe> list closed actions <joe> list all actions
The answer will be something like:
<gb> #20, #15, #14
Instead of list, you can also
say find, look
up, get, search or search
for.
You can search for issues or actions.
If you omit the word, gb will search for issues. (An action is a
kind of issue, so searching for issues will also return actions,
but not the other way round.) You can search
for open, closed or all
issues. If you omit the word, gb will search for open
issues. Thus the command
gb, list
means list open issues.
You can add criteria to restrict the results:
from myrepo or from repository
myrepo will list issues from ‘myrepo’
instead of the repository that was added last. The name of the
repository may be abbreviated exactly
like when referencing issues.with label foo or with labels foo,
bar will limit the results to issues with all of the
given labels.by joe will only return issues that were created
by joe.for joe will return issues assigned to joe.
Instead of a name, you can also say me. And instead
of for me, you can also start with my,
e.g.: list actions for me is the same as list
my actions.You can add one, two, three or four criteria. E.g.:
<joe> gb, list actions for me from rdf-star
If the result contains more than 99 issues, gb will list only the 99 highest numbers. To see the next 99, use this:
<joe> gb, next
next list or find next, etc. also works.
If you add verbosely, full, with
descriptions or in full in an appropriate
place in the command, gb will not show the numbers of the issues,
but the full description of each issue.
In this case gb will, by default, list at most 10 issues. See ‘Setting the number of full issues to display’ below to change that number.
When asked to list issues or action with full descriptions, gb will by default display no more than 10 issues. You can change that number with something like
<joe> set lines to 12 <joe> lines 12 <joe> lines = 12
The maximum is 99. But note that, because IRC imposes a limit on the number of lines per second, listing 10 issues already takes about 23 seconds.
Certain IRC bots may print text that looks like an action or an issue, but isn't really. E.g., RRSAgent repeats all actions at the end of a meeting. To stop such bots from inadvertently opening or closing issues and actions, you can add their names to an ignore list:
<joe> gb, ignore RRSAgent
You can specify multiple names (separated by commas and/or spaces). Case doesn't matter: ‘rrsagent’ and ‘RRSAgent’ are the same.
If you made a mistake, you can say:
<joe> gb, don't ignore RRSAgent
or
<joe> gb, do not ignore RRSAgent
IRC nicks are only ignored on the current channel. If you need to ignore the same nicks on other channels, you need to repeat the command on each of the channels.
When you create an action for somebody, it is usually the easiest to use the IRC nick name of that person. But if the IRC nick is not the same as the GitHub account name of that person, GitHub will assign the action to nobody.
To help with that, you can define aliases with =
or is, e.g.:
<joe> gb, Eve = eve78 <joe> gb, dayan is dcslobo
An initial @ is optional:
<joe> gb, Eve = @eve78
The first name is the one you plan to use when creating actions, the second is the corresponding GitHub account name. In fact, you can define arbitrary aliases. They don't have to be IRC nicks.
Gb remembers the aliases even when it leaves and later rejoins.
Be careful with nick changes: gb does not try to track nick changes for aliases. So if somebody's nick changes, it is up to you to renew the alias.
You can invite the bot to a channel and dismiss it:
<joe> /invite gb <joe> gb, bye
You can tell the bot to stop processing issues, actions, pull request, discussion and names without dismissing it from the channel; and turn it back on again:
<joe> gb, off <joe> gb, on
You can ask the bot to stop expanding just persons and teams:
<joe> gb, set names to off <joe> gb, names off <joe> gb, names = off
Instead of off, you can also use no
or false. And instead of names you can
also use persons or teams.
To ask it to stop processing just issues, pull requests, discussions and actions, the command is:
<joe> gb, set issues to off <joe> gb, issues off <joe> gb, issues = off
To turn processing back on, replace off
by on, yes or true.
When you address Gb directly, it will always respond even if it is turned off otherwise:
<joe> gb, #13 and #14? <gb> https://github.com/xxx/yyy/issues/13 -> #13 <gb> https://github.com/xxx/yyy/issues/14 -> #14
To avoid flooding the IRC conversation, the bot will not react to an issue number or name if it has already looked up the same reference recently. By default, it waits until 15 lines have been typed into the IRC channel before expanding the same reference again, but that can be configured. All of the following set the delay to 20 lines:
<joe> gb, set delay to 20 <joe> gb, delay 20 <joe> gb, delay = 20
The delay only stops the bot from reacting to normal messages in the channel. When you address Gb directly, it will respond even if it gave the same URL recently.
You can ask what repository gb is currently using:
<joe> gb, status? <gb> Delay is 15 lines, issues are on, names are on and I'm using https://github.com/xxx/yyy
Gb can be started with or without (the access codes for) a GitHub account. Without an account, it will expand issue numbers to URLs, but it cannot look up issue summaries and cannot create any new issues or actions.
To find out what account gb was started with, use this command:
<joe> gb, who are you? <gb> I am using GitHub account joe-bot
Instead of who are you, you can also
say account, user or login.
If gb, despite having access to a GitHub account, still fails to look up issues or create new ones, it may be that the repository is private. In that case the owners of the repository will have to add gb's account to the list of accepted collaborators.
To be able to create an action, gb additionally needs to have ‘push’ access to the repository it is adding the action to. Without push access, it will create an issue instead. Push access is typically not granted by default. The owner of the repository will have to explicitly invite the account that gb is using and give it at least write access to the repository.
The bot also reacts to help with some information
about itself and a link to this manual.
For security reasons, Gb will write at most 100 times to a repository per period of 10 minutes. (I.e., 100 issues or actions created, closed or reopened; merely looking up an issue does not count.) After 10 minutes, the count is reset. This limit is per repository, not per IRC channel. If multiple IRC channels use the same repository, their counts are added together.
In addition, there is a limit on the total number of GitHub requests on all repositories and all channels. This includes making changes to issues, but also looking up information about an issue. This limit is imposed by GitHub and is currently 5000 operations per hour.
Gb is written in Perl. The source is on GitHub.