---
title: "Branches & Pull Requests"
canonical: "https://admiral.io/docs/concepts/branches-and-pull-requests"
description: "How an environment follows a branch, how a pull request's head is planned before it merges, what the GitHub App posts on the pull request, and how the reviewed plan applies after the merge."
---
# Branches & Pull Requests
An environment can follow a branch. A push publishes what the repository declares, a pull request's head is planned where its base branch is followed, the plan appears on the pull request as one check and one comment, and once the pull request merges the reviewed plan applies without a second step. Nothing unreviewed ever applies, and nothing moves an environment except a changeset.
```mermaid
flowchart LR
P["Push
to a listened branch"] -->|publishes| R["Revision
tagged with the branch
and sha-<short>"]
R -->|tracking| D["Draft changeset
in each environment
that follows the branch"]
D -->|plans| Pl["Plan"]
PR["Pull request
head published as pr-<n>"] -->|planned where the
base is followed| D
Pl -->|on the pull request| C["One check,
one comment"]
C -->|approved, merged,
same bytes| Ap["Apply"]
```
## Tracking
Tracking is an environment's policy for following publishes. An environment that does not track is **pinned**: it moves only when someone writes a changeset. An environment that tracks matches exactly one of:
| Policy | Matches | Example |
| --------------- | ----------------------------------------------------------------- | ------------------- |
| a branch | a branch name or glob, which is a floating tag the publisher sets | `main`, `release/*` |
| a tag pattern | a glob over the component's tags | `v*`, `stable-*` |
| a version range | a semver range over the component's version tags | `>=1.4.0 <2.0.0` |
When a newly published revision matches, the environment's draft changeset for that component opens or is updated, moved to the new revision, and planned. The same draft is reused for every later match, so a branch that moves ten times a day leaves one draft, planned ten times, not ten drafts. Tracking never applies on its own. A tracking environment also shows how far behind the newest match it is.
```bash
admiral env update checkout/dev --track branch=main
admiral env update checkout/staging --track range='>=1.4.0 <2.0.0'
admiral env update checkout/prod --track none
```
Among several matches, the newest wins: by publish time for a branch or tag pattern, by semver order for a range. A range reads only version tags, which never move; a pre-release matches a range only when the range names one.
## A push publishes
A [source](https://admiral.io/docs/concepts/sources.md) that publishes on push is a git repository reached through Admiral's GitHub App, with the branches it listens to. A push to a listened branch fetches the repository at that commit and publishes every component the repository's `admiral.yaml` declares, within what the source allows, tagged with the branch name and `sha-`. Publishing the same tree twice yields the same revision. A push to any other branch publishes nothing.
A tag push publishes nothing today. A branch name that cannot be a tag, such as one with a `#` in it, publishes under `sha-` only.
## A pull request is planned before it merges
A pull request into a listened branch publishes its head as `pr-` and `sha-`, the same way a push does. Every environment whose component tracks the base branch opens one draft changeset for the pull request, moves the components the head changed to `pr-`, and plans. A later push to the pull request moves the same draft and plans again. Closing the pull request discards its drafts.
The pull request's drafts never apply on their own. Branch tracking never reads a `pr-` tag either, so an environment that follows every branch is not swept along by every pull request.
A pull request from a fork is not planned: its code would be planned with the environment's credentials. A pull request into a branch the source does not listen to is not planned.
## One check, one comment
The GitHub App posts one check run named **Admiral** on the pull request's head and one comment, and edits both for every plan, failure, apply and close. There is never a second comment, so the pull request's subscribers are notified once for its whole life.
The check is in progress while any environment is still planning, fails when any plan failed, and passes otherwise. Its one button, **Re-plan**, plans the drafts again.
What the comment carries is a setting on the push source:
| Setting | The comment shows |
| -------------------- | -------------------------------------------------------------------------- |
| Summary, the default | counts per component, with destroys and replaces listed first and expanded |
| Full | every resource with its action |
| Off | nothing; the check run only |
A plan too long for one comment becomes counts and a link to the changeset in the console. Attribute-level diffs stay in the console.
## The reviewed plan applies after merge
Approval happens in Admiral, on the plan. Once a pull request's plan is approved in an environment and the pull request merges, the push of the merge publishes the merged components. When every component the draft moves publishes the same bytes the pull request's head had, the approved plan applies with no second step: the revisions are content-addressed, so the same bytes are the same revision, and the plan reviewed is the plan applied.
When the merge publishes something else, because the base branch moved or a module the component calls changed, the pull request's draft is discarded and the environment's own tracking draft plans the merged version afresh, with no approvals. Someone reviews and approves it again.
An environment can keep a person in the loop:
```bash
admiral env update checkout/prod --track branch=main --after-merge wait
```
With `wait`, a merge that publishes the same bytes leaves the pull request's draft open, planned and approved, for a person to apply. The default is `apply`.
A kept draft that never sees its merge published, because the merge commit was pushed as part of a larger batch or the branch moved past it, is discarded, and tracking follows the branch as usual.
## Where to go next
* [Sources](https://admiral.io/docs/concepts/sources.md): Where a component's bytes come from, and the grant that reaches them
* [Changesets & Runs](https://admiral.io/docs/concepts/changesets-and-runs.md): How a staged change becomes a live deployment