This is a short tour that will show you around the very basics, how to make your PR respond to a simple command.
0. Install RepoKitteh¶
First of all, the RepoKitteh Application must be configured for your organization. To configure the application, head on to GitHub's RepoKitteh's GitHub application page.
As currently RepoKitteh is still not generally available, please do not install the application without contacting us first.
1. Create the root module¶
The root module is what tells RepoKitteh how to respond to events. The root module resides in a file called
repokitteh.star at the root of the repository.
Create a commit with a file called
repokitteh.star at the root of you repository containing the following code:
1 2 3 4 5
def meow(sender): github.issue_create_comment('Meow, %s!' % sender) handlers.command(name='meow', func=meow)
Let's take a look at this snipper line by line:
- Line 1: Defines a function that receives a single parameter
sender. This function will be registered to be fired in line 5. RepoKitteh inspects this function before running it, recognizing the parameter
senderby its name. That causes it to pass the event sender (the user who caused this event to be generated) in this argument to the function.
- Line 2: Call
github.issue_create_commentto create an issue comment on the issue in the evaluation context (this means the issue this event want created for).
- Line 5: Call
handlers.commandto register the
meowfunction to be fired when a command is detected.
You can either commit straight to master in order for the change to take immediate effect in the repository, or create a PR with this commit to test it before merging to master.
a. Testing in a PR before merging¶
If you choose (or have to) create a PR before merging, you can test your change in that specific PR. To do so, you have to create the PR and then bless it. Blessing tells RepoKitteh that the changes in the PR should take effect in that specific PR. Blessing can be done only by users which has the
modifier role1. The reason blessing is needed, and limitted to specific users, is to prevent unauthorized users from running arbitrary scripts on behalf of RepoKitteh.
Blessing is done by applying the label
rk:blessed on the PR. RepoKitteh detects this label being applied and will create a comment on the PR to indicate that the PR is blessed. To unbless the PR, just remove the label.
Users that do not have write permissions to issue labels can either comment on a PR with
/rk:blessed or include the
/rk:blessed command in the PR body when it is created. This will instruct RepoKitteh to apply the
rk:blessed label on the PR.
See Demo PR.
2. Your changes are now in effect.¶
Once your change is merged to master they will take effect across the entire repository - RepoKitteh will handle each event from that point on according to the new
Roles are currently configured manualy on installation. In the future this will be done using GitHub teams. ↩