Pull requests

Opening a pull request

A pull request proposes the commits of one branch (the head) for another branch of the same repository (the base, usually the default branch). The head can also be one of your sandboxes. Writers of the repository open pull requests; everyone who can read the code can read them.

• On the web: push a branch, then use Compare & pull request on the repository's page or its Pull requests tab, or New pull request on the Branches page. The new pull request page shows the commits and the changes before you open it, and fills in the title and description from the commits.
• From a terminal: rebasely pr create --title "Fix the login redirect" on the branch you pushed.
• Agents: the pr.create tool, or POST /api/v1/repos/<org>/<repo>/pulls.

Open it as a draft when it is not ready: a draft cannot be merged until its author (or a writer) marks it ready for review. A branch can have one open pull request per base. Every push to the head shows up in the conversation, and the pull request always shows the head's latest commit.

The server keeps the head's commits in refs/pull/<n>/head, so they stay reachable even when the branch is deleted, and the result of merging the head into the base in refs/pull/<n>/merge. Neither shows up in branch lists or clones; git fetch origin refs/pull/12/head or rebasely pr checkout 12 gets them.

Reviewing

The Conversation tab has the description, comments, reviews and what happened (pushes, title changes, review requests). Commits lists the commits, and Files changed shows the diff of the head against the point where it left the base.

• To comment on a line, select its line number in Files changed. Comment now posts the comment at once; Add to review keeps it pending, visible only to you, until you submit your review.
• Submit a review at the bottom of Files changed: Comment, Approve or Request changes, with a summary. Nobody can approve or request changes on their own pull request.
• Reply to a thread under its comments, and resolve it once it is addressed: the pull request's author, writers and whoever started the thread can resolve it.
• A thread whose line changed in a later push is marked Outdated; it stays in the conversation with the line it was about.
• The author and writers ask people for a review in the Reviewers box; they get an email. An approval counts for the commit it was given on: a new push needs a new approval.
• Comments, descriptions and reviews are Markdown. Raw HTML is shown as text and images from other sites become links.

Visual

When a pull request changes .rebasely/architecture (system.yaml, a view or a dataflow) or .rebasely/kb, Files changed has a Code and Visual switch. Code is the line diff. Visual draws what the pull request does to the architecture, with a picker for the diagram:

• System shows the system as the pull request leaves it: components and connections it adds are marked added, ones it changes (kind, description, owned paths, binding) changed, and ones it removes stay in place, dashed and struck through, marked removed. Select a component for what changed in it.
• Each view is diffed on its own: the view at the merge base against the view at the head. The picker marks the views the pull request adds, changes or removes.
• Each dataflow (flows/*.yaml) is drawn as numbered steps between its participants: steps the pull request adds are marked added, removed ones are dashed and struck through, a step that goes between other participants is rerouted (its old route dashed under it), and one with a new label is relabelled; a step that moved in the order says where it was.

Below each diagram every change is listed, and then the notes and decisions the pull request adds, changes or supersedes in .rebasely/kb. The view and the diagram are in the address (?view=visual&diagram=flows/upload), so a link opens the same picture. See the .rebasely folder.

Merging

The merge box at the bottom of the conversation says what stands between the pull request and a merge: its checks, its approvals, conflicts with the base. When nothing does, writers (and the base branch's allowed roles) merge it on the server with one of four methods:

Merges, squashes and rebases write commits, which needs an account at least 7 days old or a verified one (an agent's owner's). Tick Delete the branch after merging to remove the head branch in the same step; a protected or live branch, or the default branch, is kept, and a sandbox is ended.

When the branches conflict, nothing is written and the merge box lists the files. Merge the base into your branch with git, resolve the conflicts and push: git merge origin/main. Histories Rebasely cannot merge on the server (several merge bases, unrelated histories, or changes to .gitmodules, .gitattributes, symlinks or submodules) say so; merge those with git and push.

Pushing the head's commits to the base yourself also counts: the pull request is marked merged by that push.

Protection, approvals and checks

Owners set rules for a branch in the repository's settings, under Branch protection. A merge has to meet the rules of its base:

• Required approvals (0 to 6): approvals of the latest commit by people with write access other than the author and anyone who pushed to the branch. An agent's approval never counts, and neither does the approval of an agent's owner on the agent's own pull request. A request for changes by a writer blocks the merge until that reviewer approves or an owner dismisses the review.
• Required checks: commit statuses that must have succeeded on the pull request's head commit, such as actions/duragit/ci/test.
• Checks against the current base (strict): a required check counts only when it ran against the base as it is now; after the base moves, it has to run again.
• A branch that requires approvals takes changes only through pull requests: pushes that update it are refused for everyone (changes need a pull request), as are force-pushes and deletes. Such a branch cannot be live.

The server checks every rule again when the merge is written, whatever the merge box showed.

Checks from Rebasely Actions

Workflows run for pull requests when they declare on: pull_request. They run on the result of the merge (refs/pull/<n>/merge), read their workflow files from it, and report their status on the head commit, which is what the merge box and required checks look at.

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]                      # the base branch
    paths: ["src/**"]                     # files that differ from the base
    types: [opened, synchronize, reopened]  # the default; closed is refused
    rerun-on-base-change: true            # off by default

• opened, reopened and synchronize (a push to the head) run the workflow. A pull request that is closed or merged starts nothing; types: [closed] is refused.
• When the base moves, the head's latest results are marked stale. With rerun-on-base-change: true the workflow runs again on the new merge, at most once every 10 minutes per pull request.
• A pull request whose author and pushers are all established writers of the organization (people, not agents) runs with the repository's and the organization's secrets; anything else runs without secrets and waits for a different writer to approve the run, at that head. Pull request runs never get deployment environments, never push, and write caches only to their own pull request's scope.
• A merge conflict starts nothing and reports duragit/<workflow> as an error saying so, on the head.
• Steps see DURAGIT_PR_NUMBER, DURAGIT_HEAD_REF, DURAGIT_HEAD_SHA, DURAGIT_BASE_REF and DURAGIT_BASE_SHA, and expressions duragit.pull_request.
• Limit push to the base branch, as above: a workflow that runs for both a push to the head and its pull request writes the same check on the head commit, and the later result wins.

Agents

Agents open pull requests, comment, review and merge within their token's repositories, scopes (repo:write) and ref patterns, like any writer, with one difference: their approvals are recorded but never count toward required approvals. Over MCP (https://rebasely.com/mcp, see rebasely mcp):

The CLI

rebasely pr list [--state open|closed|merged|all] [--mine]
rebasely pr create --title "..." [--body "..."] [--base main] [--draft] [--reviewer ada@example.com]
rebasely pr view 12 [--diff]
rebasely pr checkout 12
rebasely pr comment 12 --body "..." [--path src/app.ts --line 42]
rebasely pr review 12 --approve | --request-changes | --comment [--body "..."] [--expect <sha>]
rebasely pr merge 12 [--method merge|squash|rebase|ff] [--delete-branch] [--expect <sha>]
rebasely pr close 12 · rebasely pr reopen 12 · rebasely pr edit 12 --ready

Run these in a clone whose remote is https://<host>/<org>/<repo>. The CLI uses REBASELY_TOKEN (only for rebasely.com, staging, $REBASELY_HOST or a local server), else the remote URL's password, else the token rebasely auth login stored for git; it never prints it. --expect <sha> binds a review or a merge to the head you read: if someone pushed since, the server refuses. rebasely alone opens the terminal UI, whose first panel lists the pull requests.

The API

Under /api/v1/repos/<org>/<repo>, with an access token in Authorization: Bearer:

A private repository the token cannot reach, a repository that does not exist and a pull request number that does not exist all get the same 404.

Limits

Emails go to people asked for a review, and to a pull request's author and reviewers when it is reviewed or merged; never to whoever did it. They carry the pull request's number and title, nothing anyone else wrote.