Skip to content

Commit c07be58

Browse files
committed
README: split auto-expiration into its own section
Addresses @raboof review feedback on #714: - Pull the `expires_at` + `remove_expired.yml` explanation out of the "Updating Version" section into its own "Automatic Expiration of Old Versions" subsection between "Manual Version Addition" and "Removing a Version Manually", with its own mini mermaid graph showing the daily cleanup edge that was previously a self-loop on the updating diagram. - Apply the line-288 wording suggestion: the manual-removal intro now says the manual path is needed only when you "can't wait for the entry to expire" rather than "the next daily run" — the daily cadence is a detail of the new section, not of the manual flow. Rebased onto current main; no content changes beyond the review feedback. Generated-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 7ee0884 commit c07be58

1 file changed

Lines changed: 21 additions & 4 deletions

File tree

README.md

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ This repository hosts GitHub Actions developed by the ASF community and approved
2929
- [Automated Verification in CI](#automated-verification-in-ci)
3030
- [Dependabot Cooldown Period](#dependabot-cooldown-period)
3131
- [Manual Version Addition](#manual-addition-of-specific-versions)
32+
- [Automatic Expiration of Old Versions](#automatic-expiration-of-old-versions)
3233
- [Removing a Version](#removing-a-version-manually)
3334

3435
## Submitting an Action
@@ -125,15 +126,13 @@ graph TD;
125126
dependabot-.verified by.-verify["verify_dependabot_action.yml"]
126127
composite--"update_actions.yml (on merge)"-->actions.yml
127128
actions.yml--"update_actions.yml"-->approved["approved_patterns.yml"]
128-
actions.yml--"remove_expired.yml (daily)"-->actions.yml
129129
```
130130

131131
In most cases, new versions are automatically added through Dependabot:
132132
- Dependabot opens PRs against `.github/actions/for-dependabot-triggered-reviews/action.yml` to update actions to the newest releases
133133
- **`verify_dependabot_action.yml`** runs on each such PR, rebuilds the action's compiled JavaScript in Docker, and diffs it against the published version (see [Automated Verification in CI](#automated-verification-in-ci))
134134
- Once a reviewer merges the PR, **`update_actions.yml`** reflects the new commit SHAs back into `actions.yml` and regenerates `approved_patterns.yml`
135-
- The previously approved version is marked with an `expires_at` date 3 months out, giving projects a grace period to update their workflows
136-
- Once that date passes, the daily **`remove_expired.yml`** workflow (02:04 UTC) deletes the entry and regenerates `approved_patterns.yml` — no manual PR needed
135+
- The previously approved version is marked with an `expires_at` date 3 months out, giving projects a grace period to update their workflows; see [Automatic Expiration of Old Versions](#automatic-expiration-of-old-versions) for how the cleanup runs
137136

138137
Projects are encouraged to help review updates to actions they use. Please have a look at the diff and mention in your approval what you have checked and why you think the action is safe.
139138

@@ -283,9 +282,27 @@ If you add older version of the action and want to set an expiration date for it
283282
> [!WARNING]
284283
> Older versions may contain security vulnerabilities or performance issues. Always evaluate if using the latest version is possible before requesting older versions.
285284

285+
### Automatic Expiration of Old Versions
286+
287+
```mermaid
288+
graph TD;
289+
entry["actions.yml entry<br/>with expires_at"]--"remove_expired.yml (daily, 02:04 UTC)"-->actions.yml
290+
actions.yml--"update_composite_action.yml"-->composite[".github/actions/for-dependabot-triggered-reviews/action.yml"]
291+
actions.yml--"update_composite_action.yml"-->approved["approved_patterns.yml"]
292+
```
293+
294+
Routine cleanup of superseded versions is automated:
295+
296+
- Any entry in `actions.yml` with an `expires_at: YYYY-MM-DD` field is a candidate for removal.
297+
- Dependabot-driven updates (see [Updating Version of Already Approved Action](#updating-version-of-already-approved-action)) set `expires_at` to **3 months out** on the previously approved version. For manually added older versions, set `expires_at` explicitly (see [Manual Addition of Specific Versions](#manual-addition-of-specific-versions)).
298+
- The **`remove_expired.yml`** workflow runs daily at **02:04 UTC**. Every entry whose `expires_at` date has passed is deleted from `actions.yml`; the workflow then commits the change and lets `update_composite_action.yml` regenerate `approved_patterns.yml` and the dependabot composite.
299+
- Entries without `expires_at` (for example, `keep: true` wildcards and the current approved version) are never auto-removed — removal of those requires a manual PR.
300+
301+
No human action is required for the routine case: projects get a 3-month grace window after a version bump, and the old entry disappears on its own afterwards.
302+
286303
### Removing a version manually
287304

288-
Routine removal is already automated: set `expires_at` on the entry and the daily `remove_expired.yml` workflow will delete it once the date passes. Use the manual process below only when you need an immediate removal that can't wait for the next daily run.
305+
Routine removal is already automated: set `expires_at` on the entry and the daily `remove_expired.yml` workflow will delete it once the date passes. Use the manual process below only when you need an immediate removal that can't wait for the entry to expire.
289306

290307
> [!IMPORTANT]
291308
> If a version or entire action needs to be removed immediately due to a security vulnerability:

0 commit comments

Comments
 (0)