paseo/public-docs/hub/triggers/github.md

title, description, nav, order, category

title	description	nav	order	category
GitHub triggers	Start Hub workflows from specific GitHub issues, pull requests, comments, and labels.	GitHub	67	Hub

GitHub triggers

Use semantic GitHub events to start a workflow from one GitHub action. Add the workflow below to a repository whose .paseo/hub.yml defines the dev environment and codex agent, then activate the bundle.

Triage new issues

.paseo/workflows/triage-issue.yml:

name: triage-issue
on: github.issue_created
max_runtime: 2h
filters:
  repo: example/project
  from_users: [maintainer]
steps:
  - id: triage
    environment: dev
    max_runtime: 30m
    idle_timeout: 5m
    agent: codex
    github:
      connection: example-github
      repositories: [example/project]
      permissions:
        issues: write
    prompt:
      - text: |
          Triage the new issue. Add the appropriate labels and leave a short comment
          explaining the result with gh. Use this event context:
          ${{ paseo.context }}
          Call hub.finish_execution when done.

github.issue_created fires only when someone opens an issue. from_users is required and matches the GitHub login that caused the event.

Review new pull requests

.paseo/workflows/review-pull-request.yml:

name: review-pull-request
on: github.pull_request_created
max_runtime: 2h
filters:
  repo: example/project
  from_users: [maintainer]
steps:
  - id: review
    environment: dev
    max_runtime: 90m
    idle_timeout: 10m
    agent: codex
    github:
      connection: example-github
      repositories: [example/project]
      permissions:
        contents: read
        pull_requests: write
    prompt:
      - text: |
          Review the new pull request and submit your findings with gh. Use this event context:
          ${{ paseo.context }}
          Call hub.finish_execution when done.

github.pull_request_created fires only when someone opens a pull request.

To wait until a draft is finished, change on in the example above to github.pull_request_ready_for_review. It fires only when a draft is marked ready, with the user making that transition checked against from_users. Opening a pull request, later pushes, and converting it back to draft do not fire this event.

Pull request webhook context includes github.pull_request.draft and github.pull_request.head_sha as delivered by GitHub. github.pull_request is null for other events, including conversation comments on a pull request. Fetch the live pull request with gh pr view before reviewing and again before posting. Finish without posting if it is now draft or its head differs from the reviewed SHA. Converting back to draft does not cancel a Hub run already in progress; the workflow owns these live checks.

Respond to new comments

.paseo/workflows/respond-to-issue-comment.yml:

name: respond-to-issue-comment
on: github.issue_comment_created
max_runtime: 2h
filters:
  repo: example/project
  contains: "@paseo"
  from_users: [maintainer]
steps:
  - id: respond
    environment: dev
    max_runtime: 30m
    idle_timeout: 5m
    agent: codex
    github:
      connection: example-github
      repositories: [example/project]
      permissions:
        issues: write
    prompt:
      - text: |
          Respond to the new issue comment with gh. Address this request:
          ${{ paseo.prompt }}
          Use this event context:
          ${{ paseo.context }}
          Call hub.finish_execution when done.

.paseo/workflows/respond-to-pull-request-comment.yml:

name: respond-to-pull-request-comment
on: github.pull_request_comment_created
max_runtime: 2h
filters:
  repo: example/project
  contains: "@paseo"
  from_users: [maintainer]
steps:
  - id: respond
    environment: dev
    max_runtime: 30m
    idle_timeout: 5m
    agent: codex
    github:
      connection: example-github
      repositories: [example/project]
      permissions:
        pull_requests: write
    prompt:
      - text: |
          Respond to the new pull-request conversation comment with gh. Address this request:
          ${{ paseo.prompt }}
          Use this event context:
          ${{ paseo.context }}
          Call hub.finish_execution when done.

Use github.issue_comment_created for an issue discussion and github.pull_request_comment_created for a pull-request conversation. A comment on a changed line is a diff comment, covered by the legacy github.pull_request_review_comment event.

For github.issue_comment_created, github.pull_request_comment_created, github.issue_comment, and github.pull_request_review_comment, Hub reacts with 👀 when it accepts the delivery, 🚀 when the agent starts, 👍 on completion, and 👎 on failure.

Start work when an issue becomes ready

.paseo/workflows/implement-ready-issue.yml:

name: implement-ready-issue
on: github.issue_label_added
max_runtime: 2h
filters:
  repo: example/project
  label: ready-for-agent
  from_users: [maintainer]
steps:
  - id: implement
    environment: dev
    max_runtime: 90m
    idle_timeout: 10m
    agent: codex
    github:
      connection: example-github
      repositories: [example/project]
      permissions:
        contents: write
        issues: write
        pull_requests: write
    prompt:
      - text: |
          Implement the issue that was marked ready for an agent. Create a branch,
          push it, and open a pull request with gh. Use this event context:
          ${{ paseo.context }}
          Call hub.finish_execution when done.

label matches the label that this event added. The match is case-insensitive, so ready-for-agent also matches Ready-For-Agent.

Choose the event

on	Fires when
github.issue_created	An issue is opened.
github.pull_request_created	A pull request is opened.
github.pull_request_ready_for_review	A draft pull request is marked ready for review.
github.issue_comment_created	A comment is created on an issue.
github.pull_request_comment_created	A conversation comment is created on a pull request.
github.issue_label_added	A label is added to an issue.
github.pull_request_label_added	A label is added to a pull request.

Choose github.issue_comment_created for a comment on an issue and github.pull_request_comment_created for a conversation comment on a pull request. GitHub delivers both as issue comments; Hub separates them for you. A comment on a changed line is a diff comment, covered by the legacy github.pull_request_review_comment event.

Filter GitHub events

Every externally sourced workflow needs a non-empty from_users allowlist. GitHub filters compose with AND: the repository, connection, sender, content, changed label, and required current labels must all match.

contains and pattern inspect the title plus body for issue and pull-request events. For comment events, they inspect the comment body. contains is a substring match; pattern matches the start.

Use label with github.issue_label_added or github.pull_request_label_added when the added label itself matters. Use labels when the item must currently have every listed label. Both compare labels case-insensitively. For example, labels: [bug, backend] requires both labels; it does not mean either one.

The configuration reference lists every GitHub event and filter.

Legacy event compatibility

Existing workflows keep their behavior with github.issues, github.issue_comment, github.pull_request_review, github.pull_request_review_comment, and github.push. Prefer the semantic events above for new workflows. A semantic workflow and a legacy workflow can both match the same delivery, so they start separate runs.

A GitHub trigger grants no token. Authority is the github block on the step that needs it. GitHub has no hub.reply capability; the agent acts through gh within the declared connection, repositories, and permissions.