Skip to content

renovate-merge

A schedule-driven merge-sweep. One job enumerates a group's open merge requests, keeps the ones that are Renovate's, non-draft, and mergeable, and merges each with its head sha. Run it from one pipeline schedule on one repo and it drains the whole group — new repos need no wiring.

renovate-merge is a sibling of renovate-group, not a replacement:

renovate-group renovate-merge
Does runs Renovate to open MRs merges the green ones
Schedule var RENOVATE_TASK=scan RENOVATE_TASK=merge
Cadence daily/weekly frequent (e.g. hourly)

Why it exists

Every phpboyscout project uses GitLab's fast-forward (ff) merge method for linear, merge-commit-free history. GitLab's merge API requires a sha to perform an FF merge, and Renovate's automerge call does not send one — so every Renovate automerge returns 400 {"message":"SHA must be provided when merging"} and the MR sits open indefinitely (a known upstream limitation, renovatebot/renovate #26972). After a cicd release that means one green phpboyscout/cicd pin-bump MR per repo that never merges, piling up until a manual sweep.

renovate-merge does the merge Renovate can't: it re-fetches each candidate's head sha and PUT …/merges with it — the call that succeeds under FF. It is belt-and-braces behind Renovate's own (FF-broken) automerge, not a replacement for it; the preset still correctly marks these MRs automerge: true. See the design spec.

What it merges

For every open MR in the group, an MR is merged only if all hold:

  • its source branch starts with branch_prefix (default renovate/) — the hard guard that keeps the sweep inside Renovate's namespace, so it can never merge a human's MR;
  • it is not a draft — Renovate drafts every major, so majors (and anything Renovate is holding) are excluded automatically;
  • its detailed_merge_status is mergeable — green, up to date, no conflicts — or, with approve on, not_approved and it qualifies below.

With approve: true, the sweep approves an MR that only lacks an approval and then merges it. It approves only MRs opened by approve_author whose head pipeline succeeded, and passes the head sha, so it can't approve a commit that moved. The token's account must be an approver in the project's approval rule. A human pushing a renovate/* branch gets no approval from the sweep, and neither does a major, which is left for a person. A major is an MR on a major- branch or titled to vN with no minor, with or without a suffix such as [security], which is how Renovate names one.

A red, behind-base, or conflicted MR is left alone. The sweep never rebases — that is Renovate's job; a behind-base MR is rebased by Renovate on its next scan and merged by a later sweep. Per-MR merge failures (a repo that just went red, a moved head) are logged and skipped, never fatal. Only an enumeration/auth failure exits non-zero.

Token scope

Uses $RENOVATE_MERGE_TOKEN by default: a hidden group variable holding the merging service account's token, which must have api scope and merge permission on every project swept. It is deliberately not renovate-group's token. The account that opens Renovate's MRs need not be able to merge to a protected branch, so the one that merges is a separate identity (wiki spec 0108). The token is aliased internally to a non-colliding variable name (SWEEP_TOKEN) so the default never self-references; see Explanation: renovate automation.

Jobs

Job What it runs
renovate-merge A stdlib-only python3 sweep on the ci-base image: GET /groups/<group>/merge_requests?state=opened (paginated) → filter → GET each candidate for its head sha → PUT …/merge with sha=<head_sha>.

Inputs

Input Type Default Description
image_version string "v0.3.4" phpboyscout/images/ci-base tag. The sweep is a stdlib-only python3 script, so ci-base is all it needs.
stage string renovate GitLab CI stage. Consumers must declare it in stages:.
group string (required) Group path to sweep, e.g. phpboyscout (subgroups included). No default — a sweep bot must state its scope. The token needs merge rights on every project under it.
branch_prefix string "renovate/" Only MRs whose source branch starts with this are eligible. The safety guard keeping the sweep inside Renovate's namespace.
exclude string "" Comma-separated substrings of a project's full path to skip (e.g. phpboyscout/krites). Empty = sweep everything eligible. For holding a repo out of the sweep.
approve boolean false Approve an MR whose only obstacle is a missing approval, then merge it. For projects that require an approval. The token's account must be an approver in the project's rule.
approve_author string phpboyscout-svc-renovate The only account whose MRs approve will approve. The branch prefix isn't enough: anyone with push rights can create a renovate/* branch.
dry_run boolean false List the MRs that would be merged (with head sha) and merge nothing. Use for the first validation and for previews.
token string "$RENOVATE_MERGE_TOKEN" Token used to enumerate and merge; not renovate-group's. Needs group-wide api + merge permission. Aliased internally to avoid self-reference.
if string '$CI_PIPELINE_SOURCE == "schedule" && $RENOVATE_TASK == "merge"' Gating rules:if:. Fires on a schedule with $RENOVATE_TASK=merge, so a merge schedule coexists with the renovate-group scan schedule.

Usage

The estate's merge sweep runs in the private project phpboyscout-private/renovate, hourly (RENOVATE_TASK=merge), because its log names the MRs it merges, private repositories included (wiki spec 0112). Its phpboyscout scope still covers cicd:

include:
  - component: gitlab.com/phpboyscout/cicd/[email protected]
    inputs:
      group: "phpboyscout"

Driven by a separate, frequent renovate-merge pipeline schedule that sets RENOVATE_TASK=merge — distinct from the renovate-group scan schedule so the two never collide on one repo.

Preview before arming the schedule

Run one pipeline with dry_run: true (or a one-off with the input overridden) first — it lists the green renovate/* candidates and merges nothing, so you can confirm the scope and token before the hourly schedule starts merging for real.