Post an Agent Review to a Pull Request

Use this guide when an agent should publish its review to GitHub, not only write it to the Shipfox log. The step receives pull-request read operations and one review-write family.

Before you begin

You need:

• The slug of an integration connection for GitHub. This guide uses github_acme as a placeholder.
• A GitHub integration connection that can read and write pull-request reviews.
• A test branch that is ready to open as a pull request. Do not open it until the workflow has synced.

Add the workflow

Create .shipfox/workflows/post-pull-request-review.yml. Replace github_acme with your integration connection slug. This is a complete workflow:

# yaml-language-server: $schema=https://www.shipfox.io/docs/workflow.schema.json
name: Post a pull request review
runner: shipfox

triggers:
  on_pull_request:
    source: github_acme # Replace with the slug of your GitHub integration connection.
    event: pull_request.opened

jobs:
  review:
    steps:
      - prompt: |
          Inspect pull request #${{ event.number }} and its changed files.
          Submit one COMMENT review with the two highest correctness risks.
          Do not approve, request changes, merge, or edit the repository.
        integrations:
          - include: [pull_request_read, pull_request_review_write]
            allow_write: true

allow_write is an explicit choice for this step. The selection does not grant repository-content writes or unrelated GitHub operations. Exact tool and repository selection fields live in Agent integration fields.

The integration entry omits connection, so it uses the project's GitHub source integration connection and repository.

Commit and push the workflow to the project's default branch. Wait for Post a pull request review to sync.

Verify the external write

Open the test pull request and inspect the new Shipfox run.

1. Confirm that the agent reads the pull request before writing.
2. Confirm that it calls only the selected read and review-write operations.
3. Open GitHub and confirm that one COMMENT review appears on the correct pull request.
4. Confirm that the pull request state, branch, and repository contents did not change.

If sync rejects the write selection, check the permission on your GitHub integration connection and the allow_write choice before sending another event.