Clarify mlflow gc command behavior for pinned runs and registered models by Copilot · Pull Request #18704 · mlflow/mlflow

Copilot · 2025-11-06T01:35:58Z

Related Issues/PRs

What changes are proposed in this pull request?

The mlflow gc command documentation did not clarify whether pinned runs or runs with registered models are protected from deletion. This caused confusion when using --older-than to preserve recent runs while potentially wanting to retain important older runs.

Changes:

Added a concise .. note:: section to gc command docstring documenting what is NOT considered:
- Pinned runs (UI-only feature, no effect on gc)
- Registered models (presence does not prevent deletion)
- Tags and other metadata (not evaluated)
Clarified --older-than filters by deletion time (when moved to deleted lifecycle stage), not creation time
Made explicit that runs must be in deleted lifecycle stage before gc can remove them

How is this PR tested?

Existing unit/integration tests
New unit/integration tests
Manual tests

Verified existing gc tests pass: test_mlflow_gc_sqlite, test_mlflow_gc_sqlite_older_than, test_mlflow_gc_file_store

Does this PR require documentation update?

Release Notes

Is this a user-facing change?

No. You can skip the rest of this section.
Yes. Give a description of this change to be included in the release notes for MLflow users.

Documentation now clarifies that mlflow gc operates solely on lifecycle stage and specified criteria (--older-than, --run-ids, --experiment-ids). Pinned runs, registered models, and metadata do not prevent deletion.

What component(s), interfaces, languages, and integrations does this PR affect?

Components

How should the PR be classified in the release notes? Choose one:

rn/none - No description will be included. The PR will be mentioned only by the PR number in the "Small Bugfixes and Documentation Updates" section
rn/breaking-change - The PR will be mentioned in the "Breaking Changes" section
rn/feature - A new user-facing feature worth mentioning in the release notes
rn/bug-fix - A user-facing bug fix worth mentioning in the release notes
rn/documentation - A user-facing documentation change worth mentioning in the release notes

Should this PR be included in the next patch release?

Yes (this PR will be cherry-picked and included in the next patch release)
No (this PR will be included in the next minor release)

Original prompt

This section details on the original issue you should resolve

<issue_title>Clarify mlflow gc functionality</issue_title>
<issue_description>If the "gc" cli tool is used with the "older-than" option, does it also delete pinned runs? It would be a good idea to be able to safeguard some runs from the garbage collection. Right now I am preserving all runs younger than a month, but I may have some important runs/models that are older than that. It should be clarified how the gc actually works in situations like:

run is "pinned"

run has a registered model under it</issue_description>

Comments on the Issue (you are @copilot in this section)
@harupy `mlflow gc` only considers the parameters passed to it and does not take into account the run’s state or metadata:

Pinned runs: Pinning is purely a UI feature and has no effect on mlflow gc.

Registered models: Similarly, the presence of a registered model under a run does not prevent it from being deleted.

In other words, mlflow gc operates solely based on the specified criteria (e.g., --older-than) and does not make exceptions for pinned runs or runs with registered models.</comment_new>

Fixes Clarify mlflow gc functionality #18694

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

github-actions · 2025-11-06T01:39:41Z

@Copilot Thank you for the contribution! Could you fix the following issue(s)?

⚠ Invalid PR template

This PR does not appear to have been filed using the MLflow PR template. Please copy the PR template from here and fill it out.

Add clarification to the gc command docstring about what factors are NOT considered when determining which runs to delete: - Pinned runs (UI-only feature) - Registered models - Tags or other metadata Also update the --older-than help text to clarify it filters based on when runs were moved to the deleted lifecycle stage, not their creation time. Co-authored-by: harupy <17039389+harupy@users.noreply.github.com>

mlflow/cli/__init__.py

🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: harupy <17039389+harupy@users.noreply.github.com>

github-actions · 2025-11-06T12:40:44Z

Documentation preview for 481566f is available at:

https://pr-18704--mlflow-docs-preview.netlify.app/docs/latest/

More info

Ignore this comment if this PR does not change the documentation.
The preview is updated when a new commit is pushed to this PR.
This comment was created by this workflow run.
The documentation was built by this workflow run.

coldhearti

This is good!

mlflow/cli/__init__.py

Co-authored-by: harupy <17039389+harupy@users.noreply.github.com>

harupy · 2025-11-07T05:53:35Z

mlflow/cli/__init__.py

+    .. note::
+
+        This command only considers lifecycle stage and the specified deletion criteria.
+        It does **not** check for pinned runs, registered models, or tags. Pinning is a


not sure if we need to mention pinned runs but it doesn't hurt anyone.

mlflow/cli/__init__.py

Signed-off-by: Harutaka Kawamura <hkawamura0130@gmail.com>

B-Step62

LGTM!

Initial plan

e356dfe

Copilot AI assigned Copilot and harupy Nov 6, 2025

Copilot started work on behalf of harupy November 6, 2025 01:36 View session

harupy marked this pull request as ready for review November 6, 2025 01:39

harupy added the rn/none List under Small Changes in Changelogs. label Nov 6, 2025

Copilot AI changed the title ~~[WIP] Clarify mlflow gc handling of pinned runs~~ Clarify mlflow gc command behavior for pinned runs and registered models Nov 6, 2025

Copilot AI requested a review from harupy November 6, 2025 01:52

Copilot finished work on behalf of harupy November 6, 2025 01:52

harupy reviewed Nov 6, 2025

View reviewed changes

mlflow/cli/__init__.py Outdated Show resolved Hide resolved

harupy added the team-review Trigger a team review request label Nov 6, 2025

github-actions bot requested review from B-Step62, BenWilson2, TomeHirata, WeichenXu123, daniellok-db, harupy, kevin-lyn, serena-ruan and xq-yin November 6, 2025 02:00

github-actions bot added area/docs Documentation issues area/tracking Tracking service, tracking client APIs, autologging rn/documentation Mention under Documentation Changes in Changelogs. labels Nov 6, 2025

Address PR review comments

951441e

🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: harupy <17039389+harupy@users.noreply.github.com>

harupy requested a review from coldhearti November 6, 2025 12:27

coldhearti reviewed Nov 6, 2025

View reviewed changes

harupy reviewed Nov 7, 2025

View reviewed changes

mlflow/cli/__init__.py Outdated Show resolved Hide resolved

Copilot started work on behalf of harupy November 7, 2025 05:40 View session

Simplify gc command note section per review feedback

8883fec

Co-authored-by: harupy <17039389+harupy@users.noreply.github.com>

Copilot finished work on behalf of harupy November 7, 2025 05:47

harupy reviewed Nov 7, 2025

View reviewed changes

mlflow/cli/__init__.py Outdated Show resolved Hide resolved

Update mlflow/cli/__init__.py

c33054a

Signed-off-by: Harutaka Kawamura <hkawamura0130@gmail.com>

B-Step62 approved these changes Nov 10, 2025

View reviewed changes

Merge branch 'master' into copilot/clarify-mlflow-gc-functionality

481566f

harupy added this pull request to the merge queue Nov 10, 2025

Merged via the queue into master with commit b98e624 Nov 10, 2025
45 checks passed

harupy deleted the copilot/clarify-mlflow-gc-functionality branch November 10, 2025 05:52

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Clarify mlflow gc command behavior for pinned runs and registered models#18704

Clarify mlflow gc command behavior for pinned runs and registered models#18704
harupy merged 6 commits intomasterfrom
copilot/clarify-mlflow-gc-functionality

Copilot AI commented Nov 6, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Nov 6, 2025

Uh oh!

Uh oh!

github-actions bot commented Nov 6, 2025 •

edited

Loading

Uh oh!

coldhearti left a comment

Uh oh!

Uh oh!

harupy Nov 7, 2025

Uh oh!

Uh oh!

B-Step62 left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

Copilot AI commented Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related Issues/PRs

What changes are proposed in this pull request?

How is this PR tested?

Does this PR require documentation update?

Release Notes

Is this a user-facing change?

What component(s), interfaces, languages, and integrations does this PR affect?

How should the PR be classified in the release notes? Choose one:

Should this PR be included in the next patch release?

Comments on the Issue (you are @copilot in this section)

Uh oh!

github-actions bot commented Nov 6, 2025

⚠ Invalid PR template

Uh oh!

Uh oh!

github-actions bot commented Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coldhearti left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

harupy Nov 7, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

B-Step62 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Nov 6, 2025 •

edited

Loading

github-actions bot commented Nov 6, 2025 •

edited

Loading