Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 108 additions & 12 deletions .github/workflows/renovate-pr-cooldown.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,16 @@ name: Reusable — Renovate PR cooldown
# those registries the Renovate presets use `minimumReleaseAgeBehaviour:
# timestamp-optional`, so Renovate opens the PR immediately instead of blocking
# it forever. This workflow re-introduces the soak as a required
# `pr-cooldown` status check that only turns green once the PR branch head
# commit is at least `cooldown-days` old — measured from the commit so a rebase
# to a newer version correctly restarts the clock. GitHub auto-merge
# (Renovate `platformAutomerge`) then merges the PR once the check passes.
# `pr-cooldown` status check that only turns green once the PR has proposed
# its current change for at least `cooldown-days`. The clock starts at the
# oldest commit in the branch's force-push chain whose diff (the changed lines)
# equals the head commit's, so a rebase, a retitle or an autoclose/reopen that
# keeps the same version does not restart it, while any version or digest
# change does. Anything that cannot be compared (more than one commit, a
# missing patch, a paged file list, an unexpected push chain) falls back to the
# head commit date.
# GitHub auto-merge (Renovate `platformAutomerge`) then merges the PR once the
# check passes.
#
# Non-gated PRs (human PRs, or Renovate PRs from registries that DO provide a
# trusted timestamp) always receive a passing status so the required check
Expand Down Expand Up @@ -80,6 +86,101 @@ jobs:
const isGated = (branch) =>
prefixes.some((prefix) => branch.startsWith(prefix));

// At most this many earlier commits are compared per PR. Stopping
// early only makes the clock start later, never earlier.
const maxLookback = 30;

// The changed lines of a single-parent commit, per file. Renovate
// force-pushes its branch as one commit on top of the base, so two
// commits with the same signature propose the same change, whatever
// the base or commit message. null means "cannot compare".
const changeSignature = (commit) => {
const files = commit.files || [];
if (!commit.complete || (commit.parents || []).length !== 1 || files.length === 0) {
return null;
}
const parts = [];
const sorted = [...files].sort((a, b) =>
a.filename.localeCompare(b.filename),
);
for (const file of sorted) {
if (typeof file.patch !== 'string') return null;
const changed = file.patch
.split('\n')
.filter((line) => line.startsWith('+') || line.startsWith('-'));
const renamedFrom = file.previous_filename || '';
parts.push([file.status, renamedFrom, file.filename, ...changed].join('\n'));
}
return parts.join('\n\u0000\n');
};

// The endpoint returns at most 300 files and pages the rest; a
// partial list cannot be compared, so `complete` marks it.
const getCommit = async (ref) => {
const response = await github.rest.repos.getCommit({ owner, repo, ref });
const complete = !/rel="next"/.test((response.headers || {}).link || '');
return { ...response.data, complete };
};

// When the PR started proposing its current change: the committer
// date of the oldest commit in its force-push chain with the same
// signature as the head. Falls back to the head commit date.
const soakStart = async (pr) => {
const head = await getCommit(pr.head.sha);
const headDate = new Date(head.commit.committer.date);
const headSignature = changeSignature(head);
if (headSignature === null) return headDate;

let pull;
try {
const data = await github.graphql(
`query($owner: String!, $repo: String!, $number: Int!) {
repository(owner: $owner, name: $repo) {
pullRequest(number: $number) {
commits { totalCount }
timelineItems(last: 100, itemTypes: [HEAD_REF_FORCE_PUSHED_EVENT]) {
nodes {
... on HeadRefForcePushedEvent {
beforeCommit { oid }
afterCommit { oid }
}
}
}
}
}
}`,
{ owner, repo, number: pr.number },
);
pull = data.repository.pullRequest;
} catch (error) {
core.warning(
`PR #${pr.number}: timeline unavailable (${error.message}); using the head commit date`,
);
return headDate;
}
if (pull.commits.totalCount !== 1) return headDate;

const pushes = pull.timelineItems.nodes;
let since = headDate;
let expected = pr.head.sha;
const oldest = Math.max(0, pushes.length - maxLookback);
for (let i = pushes.length - 1; i >= oldest; i--) {
const push = pushes[i];
const after = push.afterCommit && push.afterCommit.oid;
if (after !== expected || !push.beforeCommit) break;
let before;
try {
before = await getCommit(push.beforeCommit.oid);
} catch (error) {
return headDate;
}
if (changeSignature(before) !== headSignature) break;
since = new Date(before.commit.committer.date);
expected = push.beforeCommit.oid;
}
return since;
};

const setStatus = async (sha, state, description) => {
await github.rest.repos.createCommitStatus({
owner,
Expand Down Expand Up @@ -113,13 +214,8 @@ jobs:
continue;
}

const commit = await github.rest.repos.getCommit({
owner,
repo,
ref: sha,
});
const committedAt = new Date(commit.data.commit.committer.date);
const ageDays = (Date.now() - committedAt.getTime()) / dayMs;
const since = await soakStart(pr);
const ageDays = (Date.now() - since.getTime()) / dayMs;

if (ageDays >= cooldownDays) {
await setStatus(
Expand All @@ -136,7 +232,7 @@ jobs:
`Soaking: ${remaining} day(s) left of ${cooldownDays}-day cooldown`,
);
core.info(
`PR #${pr.number} (${branch}): ${remaining} day(s) left`,
`PR #${pr.number} (${branch}): ${remaining} day(s) left (proposed since ${since.toISOString()})`,
);
}
}
3 changes: 3 additions & 0 deletions .mise.toml
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ git-cliff = "2.14.2"
"pipx:checkov" = "3.3.30"
"pipx:json5" = "0.17.3"
"pipx:yamllint" = "1.38.0"
# tests/renovate-pr-cooldown.py runs the pr-cooldown github-script under Node.
node = "26.13.1"
ruff = "0.17.5"
shellcheck = "0.11.0"
shfmt = "3.14.1"
Expand All @@ -31,6 +33,7 @@ run = [
"bash ./tests/config-sync-scripts.sh",
"bash ./tests/vendored-file-sync-scripts.sh",
"uv run --script ./tests/workflow-script-fetch.py",
"uv run --script ./tests/renovate-pr-cooldown.py",
Comment thread
DevSecNinja marked this conversation as resolved.
Resolved
"bash ./tests/renovate-custom-manager-coverage.sh",
"bash ./tests/renovate-apm-manager.sh",
"bash ./tests/renovate-annotation-managers.sh",
Expand Down
2 changes: 1 addition & 1 deletion .renovate/packageRules.json5
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,7 @@
// lose the `docker-gated-` prefix — so pr-cooldown would not gate it and
// it would auto-merge with no soak at all — and every new release of any
// grouped dependency would reset the cooldown clock.
description: "Every registry except Docker Hub lacks a trusted release timestamp, so the default timestamp-required behaviour marks every release 'pending' forever and no PR is ever created. Treat missing timestamps as stable so Renovate opens the PR (and enables automerge); the 14-day soak is instead enforced by the pr-cooldown required status check, which measures the PR branch head commit age. rebaseWhen:conflicted (an exception to the global rebaseWhen:auto, ADR 0013) stops behind-base-branch rebases from rewriting that commit on every base change and perpetually resetting the cooldown clock. A behind-base gated PR therefore only auto-merges where branch protection does not require branches to be up to date, so repositories that require pr-cooldown keep that setting off. groupName:null keeps each gated dependency out of the weekly non-major group so it keeps its own docker-gated- branch and cooldown clock. Placed after the generic docker rule so it wins. See docs/design-decisions/0005-pr-age-cooldown-for-untrusted-timestamps.md.",
description: "Every registry except Docker Hub lacks a trusted release timestamp, so the default timestamp-required behaviour marks every release 'pending' forever and no PR is ever created. Treat missing timestamps as stable so Renovate opens the PR (and enables automerge); the 14-day soak is instead enforced by the pr-cooldown required status check, which measures how long the PR has proposed its current change (ADR 0005). rebaseWhen:conflicted (an exception to the global rebaseWhen:auto, ADR 0013) stops behind-base-branch rebases on every base change, which would cost a CI run each while the PR soaks. A behind-base gated PR therefore only auto-merges where branch protection does not require branches to be up to date, so repositories that require pr-cooldown keep that setting off. groupName:null keeps each gated dependency out of the weekly non-major group so it keeps its own docker-gated- branch and cooldown clock. Placed after the generic docker rule so it wins. See docs/design-decisions/0005-pr-age-cooldown-for-untrusted-timestamps.md.",
matchDatasources: ["docker"],
matchPackageNames: [
"/^[^/]*\\./",
Expand Down
8 changes: 4 additions & 4 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -1213,10 +1213,10 @@ CI), Renovate batches its work
repositories) is every automerged update guaranteed to be tested against
the latest `main`; elsewhere GitHub's native automerge can merge a
behind-base PR before Renovate rebases it. No per-repository override is
needed. `docker-gated-` PRs keep `rebaseWhen: "conflicted"`, because a
rebase restarts their cooldown clock; repositories that require
`pr-cooldown` therefore keep "require branches to be up to date" off for
now.
needed. `docker-gated-` PRs keep `rebaseWhen: "conflicted"` to save CI runs
while they soak (a Renovate rebase no longer restarts their cooldown clock,
but "Update branch" does); repositories that require `pr-cooldown`
therefore keep "require branches to be up to date" off for now.

### Auto-merge strategy

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,9 @@
Accepted. Amended by
[ADR 0013](0013-rebase-automerge-branches-when-behind.md): the
non-strict branch protection this relies on is now a stated requirement
for repositories that require `pr-cooldown`.
for repositories that require `pr-cooldown`. Amended again: the clock now
starts when the PR began proposing its current change, not at the latest
head commit (see "Clock start" below).

## Context

Expand Down Expand Up @@ -67,21 +69,44 @@ release age**.
failed silently: `dhi.io` was never added, and its images went ~3.5 months
with no updates at all (`DevSecNinja/truenas-apps#634`). A registry nobody
has wired up is now gated by default rather than slipping through.
2. A required **`pr-cooldown`** status check holds the merge until the PR branch
head commit is at least 14 days old, provided by the reusable workflow
2. A required **`pr-cooldown`** status check holds the merge until the PR has
proposed its current change for at least 14 days, provided by the reusable
workflow
[`renovate-pr-cooldown.yml`](../../.github/workflows/renovate-pr-cooldown.yml).
GitHub auto-merge then merges the PR the moment the check turns green.

Age is measured from the **branch head commit**, not PR creation: when Renovate
rebases the PR to a newer version the clock correctly restarts, so the exact
content being merged has always soaked for the full period.

Because the gate reads the branch head commit date, the gated rule also sets
**`rebaseWhen: "conflicted"`**. Renovate's default (`auto`, which becomes
`behind-base-branch` once automerge is enabled) would rebase the PR every time
`main` advances, rewriting the head commit and resetting the cooldown clock
forever on an active repo. `conflicted` limits rebases to genuine merge
conflicts; branch protection is non-strict
### Clock start

The clock starts at the **oldest commit in the branch's force-push chain that
makes the same change as the head commit**, not at PR creation and not at the
latest push. "The same change" means the same changed lines (`+`/`-` lines of
every file's patch), so the exact content being merged has always been
proposed for the full period:

- a new version or digest changes those lines, so the clock restarts;
- a rebase onto a moved base, a retitle (for example a commit-type change in
the shared presets) or an autoclose/reopen recreates the commit with the
same lines, so the clock keeps running.

The first design measured the age of the head commit itself. Every Renovate
push restarted it, including pushes that did not change the version:
`DevSecNinja/truenas-apps#810` proposed traefik-forward-auth v4.14.4 for 18
days, but a conflict rebase on day 5 reset the clock and the next release
arrived before it passed again.

The workflow walks back through the PR's `HeadRefForcePushedEvent`s (one
GraphQL call, then one commit read per earlier push, at most 30) while each
earlier commit has the same changed lines. Anything it cannot compare falls
back to the head commit date, which can only make the soak longer: more than
one commit on the branch, a merge commit, a missing patch, a file list the
API pages (more than 300 files), a push chain that does not end at the head,
or an earlier commit that cannot be read.

The gated rule also sets **`rebaseWhen: "conflicted"`**. Renovate's default
(`auto`, which becomes `behind-base-branch` once automerge is enabled) would
rebase the PR every time `main` advances. Such a rebase no longer resets the
clock, but each one still costs a CI run. `conflicted` limits rebases to
genuine merge conflicts; branch protection is non-strict
(`strict_required_status_checks_policy: false`), so a behind-base gated PR still
auto-merges once the soak completes — no rebase required.

Expand Down Expand Up @@ -134,9 +159,14 @@ Docker Hub branches are unaffected.
- Updates from every timestamp-less registry flow again and auto-merge after a
14-day PR-age soak, preserving the ADR 0004 risk posture without trusting a
forgeable timestamp.
- The soak clock for these registries starts when Renovate first opens (or last
rebases) the PR rather than at publish time; because Renovate opens the PR
shortly after detecting a release, the two are close in practice.
- The soak clock for these registries starts when Renovate first proposes the
version (or digest) in the PR rather than at publish time; because Renovate
opens or updates the PR shortly after detecting a release, the two are close
in practice.
- An upstream that releases more often than every 14 days never merges on its
own: each release restarts the clock (`DevSecNinja/truenas-apps#724`,
`#829`). That is the price of soaking the exact version that merges; such
PRs need the owner.
- `pr-cooldown` becomes a load-bearing required check: it must stay in the
branch ruleset, and the scheduled workflow must keep running for soaked PRs to
merge.
Original file line number Diff line number Diff line change
Expand Up @@ -49,17 +49,21 @@ to `true`, so open branches are also rebased between windows._
to `behind-base-branch` when the branch automerges, has the keep-updated
label, or the repository requires up-to-date branches; to `conflicted` when
the base branch has a merge queue or none of those apply.
2. **The docker-gated rule keeps `rebaseWhen: "conflicted"`.** The
`pr-cooldown` check measures the age of the PR head commit
([ADR 0005](0005-pr-age-cooldown-for-untrusted-timestamps.md)); a rebase
rewrites that commit and restarts the 14-day clock.
2. **The docker-gated rule keeps `rebaseWhen: "conflicted"`.** When this ADR
was written, the `pr-cooldown` check measured the age of the PR head commit
([ADR 0005](0005-pr-age-cooldown-for-untrusted-timestamps.md)), so a rebase
restarted the 14-day clock. The clock now starts when the PR began
proposing its current change, so a Renovate rebase keeps it; `conflicted`
stays to avoid a CI run per base change on PRs that wait two weeks anyway.
3. **Strict required status checks on public repositories**, with one
exception: **repositories that require `pr-cooldown` keep strict off**
(today only `truenas-apps`). Under strict protection a behind-base gated PR
can only merge after "Update branch" or a rebase, both of which create a new
head commit and restart the cooldown, so on an active repository it would
never merge. Lifting this exception needs a cooldown that is not reset by
rebases.
can only merge after "Update branch" or a rebase. "Update branch" adds a
merge commit, which the cooldown cannot compare, so it restarts the clock;
on an active repository such a PR would never merge. Since the cooldown no
longer resets on a Renovate rebase, this exception could be lifted by
letting Renovate rebase gated PRs (`rebaseWhen: "behind-base-branch"` for
them) instead; that is a separate decision.
4. No per-repository `rebaseWhen` override is needed any more:
ADR 0010 asked strict repositories to set `rebaseWhen: "behind-base-branch"`
themselves; `auto` already resolves to that for them.
Expand Down
Loading
Loading