GitHub Issues
A GitHub trigger polls one repository’s open issues through the REST API and starts one run per new matching issue. It can also receive GitHub webhooks, and it can comment on issues and close them or add labels when runs start, succeed or fail.
For a walkthrough, see GitHub issues to pull requests.
Create a token
Section titled “Create a token”Jimothy signs in with a personal access token. A fine-grained token is recommended.
- Open
https://github.com/settings/personal-access-tokens/new(the Create a token link in Jimothy’s sign-in dialog). - Name it (e.g.
Jimothy), set an expiry, and choose the Resource owner (your account or the organization that owns the repositories). - Under Repository access, choose Only select repositories and pick the repositories your triggers will watch.
- Under Repository permissions, set Issues to Read and write. (Read-only is enough if you don’t use write-back or a processed label.) Metadata: Read-only is added automatically.
- Generate the token and copy it (
github_pat_…).
Then in Jimothy: Settings → Accounts & integrations, Sign in under GitHub, paste it into Token, and click Sign in. Jimothy calls GET https://api.github.com/user to verify it.
Organizations can require approval for fine-grained tokens; if Preview matching issues returns 404 or 403 for an org repository, check the token’s approval status in the organization’s settings. A classic token with the repo scope also works, but grants far more access.
Trigger fields
Section titled “Trigger fields”Open the project’s Triggers tab (or All triggers in the ⌘K palette), click Add trigger and choose GitHub Issues. New GitHub triggers start with the label jimothy.
| Field | Stored as | Notes |
|---|---|---|
| Name | name |
|
| Runs pipeline | pipelineId |
|
| When it finds an issue | delivery |
Start a run (default), or Add to a board to put the issue on a board and run it when its turn comes. |
| Board | boardId |
With Add to a board: the board the issue goes to. |
| GitHub account | connectionId |
Required. |
| Owner | github.owner |
User or organization, e.g. acme. Required. |
| Repository | github.repo |
Repository name, e.g. web-app. Required. |
| Labels (all of) | github.labels |
Comma separated. The issue must have every label listed. |
| Assignee | github.assignee |
Optional GitHub login. GitHub also accepts none (unassigned) and * (assigned to anyone). |
| Poll every (seconds) | pollIntervalSeconds |
Default 120, minimum 15. |
| Run again when a processed issue is updated | retriggerOnUpdate |
Uses updated_at. Hidden when Processed label is set. |
| Processed label | claimLabel |
Optional. Added to each issue Jimothy starts a run for (GitHub creates the label if it doesn’t exist); issues with it are skipped, and removing it runs the issue again. Can’t be one of the Labels (all of). See Processed label. |
| Webhook secret | webhook.secret |
GitHub webhook secret (below). |
| Write back to the issue | onStart, onSuccess, onFailure |
Comment, and close or add a label. |
Each poll calls:
GET https://api.github.com/repos/{owner}/{repo}/issues?state=open&per_page=50&sort=updated&labels=…&assignee=…Only open issues are considered, the 50 most recently updated. Pull requests (which GitHub’s issues API also returns) are skipped.
What the run sees
Section titled “What the run sees”| Template value | From GitHub |
|---|---|
{{issue.key}} |
<repo>#<number>, e.g. web-app#42 (the default branch template gives jimothy/web-app-42) |
{{issue.title}} |
title |
{{issue.description}} |
body (Markdown) |
{{issue.url}} |
html_url |
{{issue.labels}} |
label names, comma separated |
{{issue.status}} |
open |
{{issue.assignee}}, {{issue.reporter}} |
assignee login, author login |
{{issue.raw.number}}, {{issue.raw.repo}} |
issue number and owner/repo |
{{issue.raw.number}} is handy for PR bodies like Closes #{{issue.raw.number}}.
Webhooks
Section titled “Webhooks”- Enable Settings → Accounts & integrations → Webhook server and expose it with a tunnel. See Webhooks.
- Save the trigger, set a Webhook secret (any random string), and copy the URL from Instant webhook (swap in your tunnel’s host).
- In the repository: Settings → Webhooks → Add webhook. Payload URL: the URL; Content type:
application/json; Secret: the same secret. Under events, choose Let me select individual events → Issues.
Jimothy verifies X-Hub-Signature-256 (HMAC-SHA256 with the sha256= prefix) and responds 401 on mismatch. It starts runs for the opened, labeled, unlabeled, reopened, assigned and edited actions, skips pull requests, and ignores other actions (HTTP 202). With a Processed label, unlabeled means removing that label re-runs the issue as soon as GitHub delivers the event.
Write-back
Section titled “Write-back”- Comment posts the start message or run summary as the token’s user.
- The transition field (hint: Close issue or add label (e.g. closed, jimothy:done)) accepts:
closed— closes the issue;open— reopens it;- anything else — adds that label (created by GitHub if it doesn’t exist).
A common setup: on success add jimothy:done (or closed if the PR closes it anyway), on failure add jimothy:failed. Existing labels aren’t removed, so an issue keeps its jimothy label; dedup prevents it from running twice. See Write-back. To let people re-run an issue from GitHub, set a processed label such as jimothy-ran and remove it from the issue.