|
| 1 | +# Landing real changes against a provider |
| 2 | + |
| 3 | +How to run the whole pipeline against a live repository and watch a change actually land. This is the manual tier: it needs a scratch repository and a token, which is why it is not automated in CI. |
| 4 | + |
| 5 | +Two tiers below it run with no credentials at all and cover most of what can break: |
| 6 | + |
| 7 | +| | Command | Covers | Secrets | |
| 8 | +|---|---|---|---| |
| 9 | +| Tier 1 | `make e2e-test` | pipeline choreography, on the noop merger | none | |
| 10 | +| Tier 2 | `make e2e-git-test` | real git: provisioning, cherry-pick, atomic push, head-branch updates | none | |
| 11 | +| Tier 3 | this document | the change provider: reading metadata, its CI, changes marked merged | a token | |
| 12 | + |
| 13 | +Run tier 2 first. If the merge machinery is broken, it will say so in under a minute and without a repository to clean up afterwards. |
| 14 | + |
| 15 | +## What you need |
| 16 | + |
| 17 | +A **scratch repository** you are willing to have commits pushed to and branches force-moved on. Do not point this at anything you care about — the merger pushes to the target branch and rewrites the head branch of every change it lands. |
| 18 | + |
| 19 | +A **token** for it, scoped to that one repository. |
| 20 | + |
| 21 | +For a **fine-grained** token, grant these repository permissions. Each is here because a specific component needs it, so you can drop the last two if you are not using those pieces: |
| 22 | + |
| 23 | +| Permission | Access | Needed by | |
| 24 | +|---|---|---| |
| 25 | +| Metadata | Read | mandatory on every fine-grained token; GitHub adds it for you | |
| 26 | +| Contents | Read and write | the git merger — clone, fetch, push to the target branch, and force-move each landed change's head branch | |
| 27 | +| Pull requests | Read | the change provider reads pull request metadata, and `land -pr` reads the head commit | |
| 28 | +| Pull requests | Read **and write** | only for `make demo-prs`, which opens pull requests | |
| 29 | +| Actions | Read and write | only if you switch the build runner to GitHub Actions — dispatch a run, poll it, cancel it | |
| 30 | + |
| 31 | +A **classic** PAT needs `repo`, plus `workflow` if you use the GitHub Actions build runner. |
| 32 | + |
| 33 | +Two things people get caught by. Fine-grained tokens must have the repository explicitly selected under "Repository access" — org-owned repositories also need the org to have approved fine-grained tokens at all. And **Contents: Read and write is the one that cannot be reduced**: landing *is* pushing, so a read-only token fails at the last step, after everything else has appeared to work. |
| 34 | + |
| 35 | +## Configure |
| 36 | + |
| 37 | +Everything provider-specific is one directory: [`service/submitqueue/demo/provider/github/`](../../service/submitqueue/demo/provider/github). Edit the three marked lines in `merge.yaml`: |
| 38 | + |
| 39 | +```yaml |
| 40 | +remoteUrl: https://github.com/<you>/<your-scratch-repo>.git |
| 41 | +target: main |
| 42 | +checkoutPath: /var/runway/checkouts/<your-scratch-repo> |
| 43 | +``` |
| 44 | +
|
| 45 | +Neither file holds a secret — `tokenEnv: GITHUB_TOKEN` names the variable, and the value comes from your environment. |
| 46 | + |
| 47 | +## Run |
| 48 | + |
| 49 | +```bash |
| 50 | +export GITHUB_TOKEN=ghp_... |
| 51 | +make local-provider-start PROVIDER=github |
| 52 | +``` |
| 53 | + |
| 54 | +The stack refuses to start without the token rather than falling back to the fake integrations. That is deliberate: a stack that silently runs on fakes reports changes as landed without having gone near the provider, which is a much worse way to find out. |
| 55 | + |
| 56 | +`local-provider-start` prints the gateway's port. Export it so the commands below are shorter: |
| 57 | + |
| 58 | +```bash |
| 59 | +export GATEWAY_ADDR=localhost:<port> |
| 60 | +``` |
| 61 | + |
| 62 | +## Land a single change |
| 63 | + |
| 64 | +Open a pull request against `main` in the scratch repo, then: |
| 65 | + |
| 66 | +```bash |
| 67 | +make land PR=https://github.com/<you>/<repo>/pull/1 |
| 68 | +``` |
| 69 | + |
| 70 | +`land` resolves the pull request's head commit and prints the change URI it built, so there is no 40-character SHA to copy. It returns an `sqid`; follow it with: |
| 71 | + |
| 72 | +```bash |
| 73 | +make land-status SQID=<sqid> GATEWAY_ADDR=$GATEWAY_ADDR |
| 74 | +``` |
| 75 | + |
| 76 | +The status walks `accepted → started → validated → batched → landed`. When it reaches `landed`, on GitHub the pull request shows **Merged** and its commit is on `main`. |
| 77 | + |
| 78 | +Worth understanding *why* it shows merged, because nothing called an API to close it. A provider marks a change merged once its head commit is reachable from the target branch. `SQUASH_REBASE` rewrites the commits, so the pull request's original head is nowhere in `main` — and `updateHeadBranch` therefore moves the pull request's branch to the commit it landed as. GitHub draws its own conclusion from that. |
| 79 | + |
| 80 | +## Land a stack |
| 81 | + |
| 82 | +Open a chain of pull requests where each targets the previous one's branch, then submit them in order: |
| 83 | + |
| 84 | +```bash |
| 85 | +make land PRS="https://github.com/<you>/<repo>/pull/1 \ |
| 86 | + https://github.com/<you>/<repo>/pull/2 \ |
| 87 | + https://github.com/<you>/<repo>/pull/3" |
| 88 | +``` |
| 89 | + |
| 90 | +The order of `PRS` is the stack order. All three land as **one push** to `main` — there is no window where a reader sees the stack half-applied — and all three show as merged. Tier 2 asserts the single-push property mechanically, by counting ref updates in the target's reflog. |
| 91 | + |
| 92 | +## Watching it work |
| 93 | + |
| 94 | +```bash |
| 95 | +docker compose -p submitqueue-provider logs -f runway-service |
| 96 | +``` |
| 97 | + |
| 98 | +Runway logs each merge and each head-branch move: |
| 99 | + |
| 100 | +``` |
| 101 | +moved change head branch to its landed commit {"change": "you/repo#1", "branch": "refs/heads/feature-a", ...} |
| 102 | +``` |
| 103 | + |
| 104 | +## When it does not work |
| 105 | + |
| 106 | +**The push is rejected on the first try.** Branch protection on `main` — required status checks, or a linear-history or no-force-push rule — applies to the merger like anyone else. Either relax it on the scratch repo or add the token's identity to the bypass list. |
| 107 | + |
| 108 | +**The change lands but the pull request stays open.** Two causes, distinguishable in Runway's logs. |
| 109 | + |
| 110 | +If the change came from a **fork**, this is expected and permanent: the head branch lives in the contributor's repository, which this stack has no business writing to. The log says `no head branch on this remote for change`. The change is on `main`; only the pull request's status is wrong. |
| 111 | + |
| 112 | +Otherwise it is **protection on the head branch** blocking the force update. The log says `could not move change head branch`. Note the land itself succeeded — the failure is reported and deliberately not retried, because the push already happened and cannot be undone. |
| 113 | + |
| 114 | +**A change is rejected as stale.** Its head moved after it was submitted, so the commit named is no longer the one under review. Re-submit it. This also happens if you re-land a change that already landed, since landing moved its branch. |
| 115 | + |
| 116 | +**Everything reports `error` immediately.** Check the queue name exists in [`queues.yaml`](../../service/submitqueue/gateway/server/queues.yaml) and matches the one in `profiles.yaml` and `merge.yaml`. A queue with no entry in `merge.yaml` gets the noop merger by design, so it will appear to land without pushing anything. |
| 117 | + |
| 118 | +## Using real CI |
| 119 | + |
| 120 | +The demo keeps the build runner fake so a land finishes in seconds. Switching to real GitHub Actions takes three things. |
| 121 | + |
| 122 | +**1. The workflow must be dispatchable.** The runner triggers builds with `POST /actions/workflows/{id}/dispatches`, which only works if the workflow declares `workflow_dispatch`. A typical scratch-repo `ci.yml` triggered on `pull_request` alone cannot be dispatched at all — GitHub rejects it. Add the trigger and the inputs the runner sends: |
| 123 | + |
| 124 | +```yaml |
| 125 | +on: |
| 126 | + pull_request: |
| 127 | + merge_group: |
| 128 | + workflow_dispatch: |
| 129 | + inputs: |
| 130 | + sq_head_uris: |
| 131 | + description: "JSON array of change URIs in the batch under test" |
| 132 | + required: false |
| 133 | + sq_base_uris: |
| 134 | + description: "JSON array of in-flight change URIs this batch speculates on top of" |
| 135 | + required: false |
| 136 | + sq_queue: |
| 137 | + description: "SubmitQueue queue name" |
| 138 | + required: false |
| 139 | + sq_metadata: |
| 140 | + description: "Caller-supplied build metadata, as JSON" |
| 141 | + required: false |
| 142 | +``` |
| 143 | + |
| 144 | +**2. Point the runner at it.** Replace the `buildRunner` line for the queue in `profiles.yaml`: |
| 145 | + |
| 146 | +```yaml |
| 147 | +buildRunner: |
| 148 | + type: githubactions |
| 149 | + owner: behinddwalls |
| 150 | + repo: sq-demo |
| 151 | + workflow: ci.yml # file name or numeric workflow id |
| 152 | + ref: main # the branch the workflow definition is read from |
| 153 | +``` |
| 154 | + |
| 155 | +**3. Grant Actions: Read and write** on the token (see the permissions table above). |
| 156 | + |
| 157 | +One caveat worth understanding before you rely on the result. A workflow that only checks out the pull request tests *that change alone* — which is not what a submit queue is for. The point of speculation is to test the **combination**: `sq_base_uris` are the in-flight changes assumed to land first, and `sq_head_uris` is the batch under test on top of them. Until the workflow actually applies both, a green run says nothing about whether the batch lands cleanly, and the queue is only exercising its trigger-and-poll loop. |
| 158 | + |
| 159 | +## Clean up |
| 160 | + |
| 161 | +```bash |
| 162 | +make local-provider-stop |
| 163 | +``` |
| 164 | + |
| 165 | +The scratch repository keeps whatever landed; reset it with `git push --force` from a known-good commit. |
| 166 | + |
| 167 | +## Another provider |
| 168 | + |
| 169 | +Nothing above is GitHub-specific except the contents of the config directory and the URI parser behind it. Adding GitLab or another provider is a new directory here plus a handful of new files beside the existing ones — the complete list is in [`service/submitqueue/demo/provider/README.md`](../../service/submitqueue/demo/provider/README.md). |
0 commit comments