Cross-repo work lands as several pull requests with separate CI runs. Polygraph ties those PRs and CI runs to one session, so a change touching five repos behaves as closely as possible to a change touching one.
What sessions track
Section titled “What sessions track”A session can track:
- Branches pushed from each repo
- Draft PRs opened for related repo changes
- Existing PRs associated with the session
- CI status for the related PRs
- PR readiness across all repos in the session
- Session descriptions and links that explain why the PRs belong together
Create and link PRs
Section titled “Create and link PRs”The agent can push branches and open draft PRs for each repo in the session. Ask an agent to do it:
Push the changes and open PRs.Or use polygraph git push-branch and polygraph git create-pr when you want to drive that flow from the CLI.
Polygraph pushes branches and opens PRs through its own integration, not the GitHub CLI, for efficiency and security reasons.
Draft PRs keep related changes reviewable before the full cross-repo set is ready. Ask the agent to mark them ready for review:
Mark the created PRs as ready for review.Or use polygraph git mark-pr-ready from the CLI.
Polygraph syncs the status of each PR in the session, so you get the same view from the Polygraph web app or from an agent using the Polygraph CLI.
Associate existing PRs
Section titled “Associate existing PRs”Not every PR has to be created by Polygraph. If a PR already exists, ask the agent to attach it to the session:
Associate https://github.com/myorg/backend/pull/482 with this session.Or use polygraph git associate-pr from the CLI. That keeps manual PRs, agent-created PRs, and follow-up PRs in the same cross-repo record.
Track CI across repos
Section titled “Track CI across repos”Ask the agent to get CI green and it treats the session's CI runs as one thing. When one repo fails, the agent decides whether the fix is local to that repo, whether the shared change breaks a downstream consumer, or whether the plan itself needs to change.
Wait for CI for this Polygraph session and address any failures.Test downstream repos before release
Section titled “Test downstream repos before release”Many cross-repo changes involve an artifact published by one repo and consumed by another. Polygraph handles this automatically: you validate downstream before anything lands, with no registry round-trip.
For example, change a design system, install the unpublished version into an application that depends on it, and run the application's CI before the design-system PR merges. For package-based validation, the agent can use pack_and_copy to pack the publisher and install the tarball into the consumer repo inside the session.
Can you pack and copy <package-name> package and update <app-name> to use it?This is the validation loop a monorepo gives you, applied across separate repos.
Review the whole change
Section titled “Review the whole change”Each linked PR carries session context. Reviewers can open the session to see the repos involved, a description of the work, sibling PRs, CI state, and the agent traces.