Skip to main content
AgentJam includes ready-made triggers for GitHub and Sentry. Each trigger polls using the token from the schedule’s own connection, so a schedule only sees what its human can see. For Slack, see Build a Slack agent.

Available triggers

Only repository, organization, and project are required. Requesters fill in the config when they schedule the trigger.

Add triggers to a skill

githubTriggers() and sentryTriggers() take the skill’s connection and return the triggers, and the skill picks the ones it offers. The task handler reads the event’s data:
As with any OAuth connection, serve its callback route with agent.receiveOAuth(), so humans can connect their accounts. The GitHub triggers work with either a githubConnection() or a githubAppConnection(). The Sentry trigger takes a sentryConnection() from @agentjam/sdk/sentry (agentjam.sentry in Python). After the connection, both helpers take these options: In Python, the options are snake_case, such as poll_interval_minutes.

How each trigger works

A new schedule only fires for events that happen after it first activates. Every event has a stable id, so an event that’s seen twice, such as by both a poll and a webhook, starts only one run.
  • pull_request_opened fires for each newly opened pull request, oldest first. If includeDrafts is set, a draft pull request starts a run when it opens. Otherwise, it starts a run once it’s marked ready for review. Pull requests from forks only start runs if includeForks is set.
  • pull_request_merged fires for each pull request merged into branch, in merge order. If branch isn’t set, it watches the repository’s default branch.
  • issue_assigned fires each time an issue is assigned to assignee or labeled with label. Both are matched case-insensitively. Pull requests are left out. A schedule must set assignee, label, or both. Assigning an issue again starts another run.
  • error_reported fires once for each new unresolved issue in the Sentry project. An issue that regresses after being resolved doesn’t start another run. The sentryConnection() needs the event:read, project:read, and org:read scopes. region is us or de, and defaults to us.
When a GitHub trigger activates, it checks that the schedule’s token can read the repository, and refuses the repository if the token can’t read it. Renaming a repository doesn’t break its schedules.

Run sooner with GitHub webhooks

Pull request triggers can start runs as soon as GitHub delivers a webhook, rather than at the next poll. Point the GitHub App’s or repository’s webhook at your server, subscribe it to the “Pull request” event, and pass each delivery to receiveEvents() with githubWebhooks():
githubWebhooks() verifies each delivery’s signature and responds to an invalid one with a 401. Webhook events use the same ids and data as polls, so a pull request seen both ways starts only one run. GitHub doesn’t retry a failed delivery, so the poll catches anything a webhook missed. The issue_assigned trigger only polls.

Watermark stores

For each schedule, a trigger records how far it has gotten in a watermark store. That way, a process that takes over a schedule, or a process that restarts, carries on where the last one left off. The default in-memory store is fine for tests, but it forgets its progress on restart, so schedules start over from the moment of the restart. In production, back the store with your database. A store gets and sets a small JSON object per key. In this example, github and sentry are the skills’ connections:
The expiring index clears the watermarks of schedules that have ended. Pass the same store to every helper, since their keys don’t collide.