Skip to content

Meow, World!

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.

Attention

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 sender by 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_comment to create an issue comment on the issue in the evaluation context (this means the issue this event want created for).
  • Line 5: Call handlers.command to register the meow function 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 repokitteh.star file.

  1. Roles are currently configured manualy on installation. In the future this will be done using GitHub teams. ↩