Ghurlbot manual

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.

Command quick reference

Command Effect
/invite gb Invite gb to the current channel
gb, bye Dismiss gb from the current channel
Look up an issue (which may also be a pull request, an action or a discussion)
@joe Link to a user profile
gb, use w3c/scribe2 Specify a repository to use
gb, drop w3c/scribe2 Remove a repository from gb's list
Issue: Foo is undefined Create a new issue
action Eve: send mail
action: Eve to send mail
Create a new action
action Eve: send mail - due in 2 weeks
action Eve: send mail due 3 June
Create a new action with a due date
action @eve78: send mail Create action using a GitHub account name
close #15 Close an issue, action, pull request or discussion
reopen aria/#15 Reopen an issue, action, pull request or discussion
Note #17 This needs work Add a comment to an issue, action, pull request or discussion
gb, list open issues with label foo List issues/actions with various criteria
gb, next
gb, next list
List more issues/actions
gb, set lines to 8 How many full issues to show at a time
gb, off
gb, on
Stop gb from processing issues, actions, pull requests, discussions & names; or turn it back on
gb, names off
gb, names on
Stop gb from processing names; or turn it back on
gb, issues off
gb, issues on
Stop gb from processing issues, actions, pull requests & discussions; or turn it back on
gb, delay 20 Set the number of lines before gb looks up the same issue number
gb, ignore RRSAgent, Zakim Nicks that cannot open or close issues, actions, pull requests & discussions
gb, don't ignore Zakim Let Zakim open/close issues, actions, pull requests & discussions again
gb, Eve = eve78
gb, Eve is eve78
Define aliases for GitHub account names
gb, status Get information about the current delay and repositories, and whether gb is turned off
gb, account Get the name of the GitHub account that gb uses
gb, help Provides a link to the manual

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

IRC command to link to an issue

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> -> #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> -> 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> -> 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> -> Issue 3 [closed] Errors replacing URLs (nigelmegitt)

Look up an issue by its URL

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:
<gb> -> CLOSED Issue 15 Feature request: syntax for verbatim lines of code (by dbooth-boston)

IRC command to link to a user name

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> -> @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., ‘’). If gb does not seem to recognize a reference, try to put spaces around it.

Text that gb ignores

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```?

Specifying the GitHub repository

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

Instead of discussing, you can also use discuss, use, using, take up, taking up, this will be or this is.

The prefix ‘’ 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.

Stop using a repository

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:

Creating an issue

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.

Creating an action

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

Closing an issue

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

The issue number can include the full name of the repository or an abbreviation, see ‘IRC command to link to an issue: #’.

Reopening 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

Creating & editing actions without Gb

If you create or edit an action by hand directly on GitHub, Gb can still recognize it if you follow the following rules:

  1. An issue must have the label ‘action’ to be recognized as an action. (It may have additional labels.)

  2. It must have one or more assignees.

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


    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

Due: 2023-11-01 (Wednesday 1 November)

Adding a comment to an issue

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
<joe> Comment aria#17: Great comment!
<joe> comment 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:

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.

Setting the number of full issues to display

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.

IRC nicks that should not open or close issues

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


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

Mapping names to GitHub accounts

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.

Inviting and dismissing the bot

You can invite the bot to a channel and dismiss it:

<joe> /invite gb
<joe> gb, bye

Suspending the bot

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> -> #13
<gb> -> #14

Reducing the number of responses from the bot

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.

Inquiring about the current status

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

GitHub account

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.

Getting help

The bot also reacts to help with some information about itself and a link to this manual.

Built-in rate limit

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.

Created by Bert Bos <> on 12 January 2022. Last updated $Date: Thu Mar 9 21:42:00 2023 UTC $ by $Author: Bert Bos $