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

Jimothy signs in with a personal access token. A fine-grained token is recommended.

1. Open https://github.com/settings/personal-access-tokens/new (the Create a token link in Jimothy’s sign-in dialog).
2. Name it (e.g. Jimothy), set an expiry, and choose the Resource owner (your account or the organization that owns the repositories).
3. Under Repository access, choose Only select repositories and pick the repositories your triggers will watch.
4. Under Repository permissions, set Issues to Read and write. (Read-only is enough if you don’t use write-back.) Metadata: Read-only is added automatically.
5. Generate the token and copy it (github_pat_…).

Then in Jimothy: Accounts → 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.

This token doesn't open pull requests

The trigger’s token is only used to read and write issues. Pipelines that push branches and open PRs (for example with gh pr create) use the git and gh credentials available to the step. See Linear issue to pull request.

Trigger fields

Open Triggers → Add trigger → GitHub Issues. New GitHub triggers start with the label jimothy.

Field	Stored as	Notes
Name	name
Runs pipeline	pipelineId
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.
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

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

1. Enable Settings → Webhook server and expose it with a tunnel. See Webhooks.
2. Save the trigger, set a Webhook secret (any random string), and copy the URL from Instant webhook (swap in your tunnel’s host).
3. 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, reopened, assigned and edited actions, skips pull requests, and ignores other actions (HTTP 202).

Webhook matching differs from polling

For webhook events, Labels match if the issue has any of the listed labels (polling requires all), and Assignee isn’t checked. The issue’s open/closed state isn’t checked either. Keep the label list to a single hand-off label to get the same behaviour both ways.

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.