Pull requests

When a worktree space’s work is ready, the control in its header takes it the rest of the way: open a pull request from the space’s branch into your project’s home branch, watch checks, and merge.

This is a worktree-space feature. A local space is working on a branch you already have checked out, so there’s nothing for Astra to open a PR from — ask the agent to open one instead.

Connecting GitHub

The control needs two things: a GitHub connection (Settings › Connections) and a GitHub remote on the project. Missing either, it says so plainly — Connect GitHub to open PRs or Not on GitHub — rather than failing when you press it.

Opening a PR additionally needs the GitHub CLI (gh) installed and authenticated, for the reason in Opening a PR below.

What the control shows

It reflects real state from GitHub, polled while the space is open:

State	Meaning
Even	The branch has no commits your home branch doesn’t. Nothing to open.
Ahead	There’s work to open a pull request for.
Checks	The PR is open and CI is still running — or GitHub hasn’t finished working out whether it can merge.
Failed	A check is red.
Conflicts	The branch conflicts with the base and needs a merge or rebase.
Review	Checks are fine, but the PR is a draft or blocked on a required review.
Ready	Checks pass and GitHub will take the merge.
Merging	The merge is in flight.
Merged / Closed	The PR has landed, or been closed without landing.

Astra is deliberately conservative about Ready. A red check reads as failed even in cases where GitHub would still allow a merge, so the button is never offered on a PR you’d regret merging.

The sidebar carries the same state as a small glyph on each space, so a set of open PRs is readable at a glance.

Opening a PR

Pressing Open PR doesn’t call the GitHub API — it asks the space’s agent to do it, as a normal turn in the conversation. The agent pushes the branch, reads its own diff against the base, and opens the PR with gh pr create, writing the title and description from what actually changed.

That’s a deliberate choice: the agent has just done the work, so it’s the thing best placed to describe it. It also means the turn shows up in the transcript like any other, and you can follow up in the same breath — “add a testing section to that description”.

The instructions it gets are yours to edit, in Settings › General › System › Pull requests. It’s plain prose with no placeholders, so you can rewrite it to match your team’s PR conventions.

Merging

Merging is the other half, and this one Astra does itself through the GitHub API: from Ready, it squashes the branch and lands it on your home branch. If it fails, it fails loudly — Astra won’t report a merge it didn’t do.

Afterwards, the space is finished work. Archive it to reclaim its checkout; the branch, the transcript and the diff stats stay.

Fixing a red PR

Checks failing is the normal case, and the space is already the right place to fix it: the branch is checked out, the agent has the context, and the terminal drawer is right there. Paste the failure in, let it fix, push, and the control picks up the new state on its own.