# GitHub integration At its core, PM on Rails is about working on the same graph over MCP from Claude Web, Claude Code, and Codex. The GitHub integration is the outbound integration that supports that development flow. You can write stories out as issues and feed pull request status back into tasks. ![PM on Rails GitHub settings. Repository connection and the path to link pull requests. Before: done was a verbal report. After: a pull request that reaches main returns the task to done.](https://pmonrails.com/docs-img/gh-settings.png) ## What it does - **Story → issue** — write a user story out as a GitHub issue. The acceptance scenarios linked to it are listed in the body. It reads as Markdown, so you can take it outside PM on Rails. - **Issue → back into the graph** — Gherkin edited in the issue body syncs into Neo4j on pull, and the latest state is pushed back into the issue. - **Two-way sync** — `sync_story_to_github` creates the issue if there is none, and updates it if there is. - **CI test results → scenarios** — reads the per-scenario report (artifact) a workflow leaves behind and records pass/fail on the scenario tasks (no PAT or secret needed). See "Record from CI automatically" under [Tests](https://pmonrails.com/en/docs/test-results.md) for the setup. ## Linking pull requests and tasks (three ways) Satisfy any one of these and a change in pull request status moves the task automatically (merged into the default branch → done, merged into a feature branch → waiting, open → review). 1. **Explicit link** — link the pull request directly to the task (`link_pr`). 2. **Identifier line in the pull request body** — put `PMR-Task: ` or `PMR-Story: ` on one line. 3. **Branch naming** — `feat/-` (the first 8 characters of the task ID). > When you start a task over MCP you get the branch name and the identifier line for the pull request body back, so you never have to type a UUID by hand ([MCP integration](https://pmonrails.com/en/docs/mcp.md)). - When a merge moves a task to done, **the parent story's status is recalculated automatically** too. - **Merge targets are distinguished** — a merge into a feature branch (the base of a stacked pull request, for example) does not complete the task. It is recorded as "Merged into branch (not in main yet)" with the branch it is waiting on. Once that branch reaches the default branch, every task waiting on it completes together. The pull request badge on the task screen shows the state, and "Reconcile pull requests with tasks" (`reconcile_task_prs` over MCP) recovers anything left behind. - If the spec changed after work started, the task is marked as needing a re-check (spec drift detection). ## Configuration The GitHub App is installed once per GitHub organization and shared by the projects in the workspace (no token or webhook to paste). 1. In **Workspace settings > Integrations > GitHub**, click "Add to GitHub" and approve the organization and repositories on GitHub (a workspace admin does this). 2. In **Project settings > Integrations > GitHub**, choose the repository this project uses. > Narrowing the repositories on GitHub affects **every project** that uses that organization's repositories. Do not remove repositories other projects use for the sake of one project. ### When you are not an owner of the GitHub organization If someone who is not an owner of the GitHub organization clicks "Add to GitHub", GitHub does not install the app. It sends a request to the organization owners instead. PM on Rails shows "Waiting for organization owner approval" together with a request message for the owner (the app name and the permissions it requests, with what each is used for). 1. Copy the request message and ask an organization owner to approve it. The PM on Rails GitHub App requests repository-level permissions only, never organization permissions. 2. After the owner approves, click "Import an installation approved on GitHub" in **Workspace settings > Integrations > GitHub** and verify your identity on GitHub. Only installations you can access on GitHub are imported into this workspace. ## No lock-in - Stories and design documents can be written out as Markdown. - They can also be synced to GitHub issues, so they fit into your development team's existing workflow. - You can work with them directly from Claude Web, Claude Code, and Codex over MCP, so nothing is trapped behind the PM on Rails screens. > Auto-closing on merge **requires the GitHub App connection** ('Add to GitHub' in Workspace settings > Integrations > GitHub, then choose the repository in Project settings > Integrations > GitHub). No webhook has to be registered by hand. Without it the automatic transitions do not fire (manual linking still works). When it is not connected, the error explains the cause and how to configure it. --- https://pmonrails.com/en/docs/github