Feature request - cooldown period on autoupdate

[Owen-OptiGrid]

I was wondering if prek autoupdate could support a cooldown period (like dependabot) or an absolute cut off date like uv update so you can choose to only install tool updates that have been live for a while (for security reasons).

This is kind of similar / related to #174

I'm not sure of the complexity of implementing though. I would think it would only apply to online, e.g. GitHub sourced tools (I guess that's all autoupdate would touch anyway).

[namurphy]

I'd use the cooldown feature! There's related discussion in astral-sh/uv#14992 and astral-sh/uv#16814, and this article about using dependency cooldowns helped me better understand the motivation.

[lmmx]

I'm not sure of the complexity of implementing though. I would think it would only apply to online, e.g. GitHub sourced tools (I guess that's all autoupdate would touch anyway).

The hooks are all git repos except the ones that are repo: local, so you’d be checking the release dates in the autoupdate logic (by ‘releases’ here I mean the git tags).

The autoupdate logic is here, specifically the auto_update function and its helper update_repo.

The logic for tag selection is in get_best_candidate_tag

prek/src/cli/auto_update.rs

Lines 320 to 323 in 8e74998

	/// Multiple tags can exist on an SHA. Sometimes a moving tag is attached
	/// to a version tag. Try to pick the tag that looks like a version and most similar
	/// to the current revision.
	async fn get_best_candidate_tag(repo: &Path, rev: &str, current_rev: &str) -> Result<String> {

Current logic selects the tag by [Levenshtein] string edit distance from the current revision (the git commit SHA), so the cooldown logic would add consideration here…

To achieve a cooldown on releases, you’d need to filter out candidates more recent than some cooldown period before the distance selection. If that leaves you with an empty list, then I’d think you’d just return Ok(current_rev.to_string()) (nothing to do) and log something like

trace!("No candidate tags older than cooldown, skipping update for `{}`", rev);

That just leaves the matter of how to pass in the cooldown (I’d expect in units of seconds/hours/days/weeks/months that get converted to seconds) and how to set the cooldown by users (I haven’t really touched any code around this, I’ve only used env vars but I don’t imagine users primarily want to configure this via env var). CLI flag and/or YAML config flag?

[Owen-OptiGrid]

CLI or YAML config flag would be good. I don't know if its the best practise but for one of my tools if the user passed an integer I assumed it was days (I don't think you'd care about hours/minutes/seconds for a cooldown) or if they passed a string I treated it as an ISO8601 duration which is pretty succinct and gives you any granularity you like... but not so human readable unless people are familiar with it.

[lmmx]

Yeah days is a good default period!

• 2 days minimum is the default cooldown period adopted by StepSecurity
• pnpm’s is 24h docs
  • They say typically an “attack [is] discovered within 1-24 hours”
  • I find their approach of specifying the number of minutes pretty unreadable
• dependabot has minimum 24h maximum 3 months (90d): docs

The number of cooldown days must be between 1 and 90.

I’d suggest we should just support a single integer unit, days, and that way avoid bothering with the unit handling and ambiguity at all. Converting from “30d” from weeks or months is pretty easy, and since the maximum used in other tools is 90 the real range probably doesn’t warrant unit parsing at all.

To make it completely clear we could put the time unit in the name like some tools do (e.g. Grafana)

So we might call it:

• cooldown-days
• delay-days
• min-days

Note dependabot calls it

cooldown:
  default-days: 4

We could even be forward thinking here and not set its default to 0, i.e. make cooldown opt-out (secure by default)

That seems totally warranted given the context:

With the recent attacks like Shai Hulud - it's only question of time that prek/pre-commit hooks will be used as vector of attack.

Originally posted by potiuk in #174

• Update implemented in Support--cooldown-days in prek auto-update #1172

• Default cooldown: 1 day, secure by default

• Minimum cooldown: 0 days (no cooldown), making it opt-out

• Maximum cooldown: 255 days (u8::MAX), this is more than is typical (Dependabot's is 90 days).

• No particular handling exists (yet?) for users attempting to put an excessive/invalid number of days

Demo

If I rewind the crate-ci/typos hook in the prek repo itself to the last tagged release before 1.40

• v1.40.0 of the typos hook was released on 2025-11-26, 5½ days ago from today 2025-12-02

• 7 day cooldown would mean it had another day to cool off

louis 🌟 ~/dev/prek $ prek auto-update --cooldown-days 7
[https://github.com/crate-ci/typos] already up to date

• 6 day cooldown would mean it would be ready today (at the exact hour)
  • The exact time was 8:26PM GMT, current time is 11:55AM GMT (so it would still be cooling off)

louis 🌟 ~/dev/prek $ prek auto-update --cooldown-days 6
[https://github.com/crate-ci/typos] already up to date

• 5 day cooldown would mean it would have been ready yesterday (so will definitely update)

louis 🌟 ~/dev/prek $ prek auto-update --cooldown-days 5
[https://github.com/crate-ci/typos] updating v1.39.0 -> v1.40.0

[potiuk]

You can look on how astral implements it in uv and do it in similar way. Draft PR here: astral-sh/uv#16814

[lmmx]

They are currently drafting support for both absolute and relative styles, in unambiguous human-readable units with unmixed integers by the looks of it (i.e. only one unit at a time):

Accepts RFC 3339 timestamps (e.g., 2006-12-02T02:07:43Z), local dates in the same format (e.g., 2006-12-02) which use your system's configured time zone, and relative durations (e.g., 24 hours, 1 week, 30 days).

Calendar units such as months and years are not allowed.

I see Nick left a comment asking to rename "exclude newer" to something with "cooldown" in:

I'm wondering if it would be helpful to add the term "cooldown" in the documentation for --exclude-newer since it's been gaining traction, and might be what a lot of people would do web searches for. 🤔

I wonder if they will rename...

[j178]

The PR at #1172 is ready for testing if anyone wants to take a look. I’d love to get some feedback before I cut a release. And big thanks to @lmmx for the awesome work!

[potiuk]

Cool !