Skip to main content
The GitHub integration lets you attach issues and pull requests to your plans for context, and track PRs linked to plan tasks.

​
Setup

Set up GitHub in Settings > GitHub in Ref Plans. It has two parts.
  1. Install the Ref GitHub App under Installed on. Pick the accounts and repositories Ref can reach. On a GitHub organization, an org owner may need to approve it.
  2. Connect your GitHub account under Account. Agents can then review and merge as you, and your plan approvals post to GitHub as your own reviews.
The App gives Ref access to your repositories. Your account connection lets Ref act as you.

​
Attaching issues and PRs

Paste a GitHub issue or PR link directly into your plan editor. The agent can read the issue details for context when researching and structuring your plan.

​
PR tracking

As agents implement tasks and create pull requests, you can link those PRs to your plan:
  • Use the PR dropdown in the plan UI to attach PRs to specific tasks
  • The agent can also use the PrLinks tool via MCP to attach PRs programmatically
This gives you a single view of all the code changes associated with your plan. To post plan approvals on linked PRs, see Change Control.

​
Agent permissions

Under Agents can in Settings > GitHub, choose what agents may do:
  • Read issues and pull requests lets agents read issues, PRs and diffs in your installed repos.
  • Review pull requests lets agents approve, request changes, and edit PR titles and descriptions as you. It governs ReviewPR, UpdatePR, and marking drafts ready in MergePR.
  • Merge pull requests lets agents merge as you once checks and branch rules pass. It governs merging in MergePR, and needs your GitHub account connected.
SearchWorkflowRuns and ReadWorkflowRun use the Ref GitHub App’s optional Actions: read permission (or a connected PAT). ManageWorkflowRun and DispatchWorkflow have no Settings toggle; they need the Ref GitHub App’s Actions: Read and write permission approved on the installation (org owners see an approval prompt from GitHub), or a connected Personal Access Token with Actions access. Without either, the tools return a message naming the missing permission.

​
Tips

  • Attach GitHub issues before asking the agent to research — it provides valuable context about what needs to be built
  • Link PRs to tasks as agents create them to track implementation progress
  • The agent can read issue comments and PR descriptions for additional context

​
Get help

If you have any issues, please reach out to help@ref.tools. We’re happy to help you get started!