[JENKINS-60730] Add stale branch, tag, and pull request filter traits

[cdarninsuang-bamfunds]

Description

See JENKINS-60730 for background — a previous attempt at this landed as #263 in 2020 and was closed in favor of installing scm-filter-aged-refs-plugin. I'd like to make the case for revisiting that, and to be upfront about the one open design question from #263 that still applies here.

What this adds: three opt-in SCMSourceTraits that exclude stale heads from GitHub multibranch/org-folder indexing:

• StaleBranchFilterTrait — branches with no commits in the last N days
• StaleTagFilterTrait — tags older than N days
• StalePullRequestFilterTrait — PRs with no activity (commits/comments/reviews/labels) in the last N days

Each supports an include/exclude regex to scope filtering by head name, and a dry-run mode that logs what would be filtered without excluding it. StaleBranchFilterTrait additionally never filters the repository's default branch or a GitHub-protected branch, regardless of age.

Why here instead of the separate plugin: the underlying problem (JENKINS-60730) is unwanted mass rebuild/indexing load from stale refs — a first-class concern for this plugin's users, not a niche one. Filtering lives alongside every other "Behaviours" option users already configure, rather than requiring a second plugin install. Compared to scm-filter-aged-refs-plugin, this adds include/exclude regex scoping, a dry-run preview, and a protected/default-branch guard — none of which that plugin currently has.

The open design question from #263: bitwiseman's core objection to the 2020 PR wasn't just "use the other plugin" — it was that an SCMHeadFilter-based discovery trait makes stale heads disappear entirely (job node removed), rather than just skipping their builds via a BranchBuildStrategy (as ChangeRequestBuildStrategyImpl does). This PR uses the same discovery-filter mechanism as #263, for the same reason it did: tags and pull requests have no BranchBuildStrategy-equivalent hook, only branches do, so SCMHeadFilter is the only mechanism that covers all three ref types uniformly. I've tried to make that discovery-time removal as safe as reasonably possible — dry-run to preview impact before enabling, and default/protected branches are never filtered regardless of age — but I'd rather flag this trade-off explicitly than leave it for review to rediscover.

Submitter checklist

• Link to JIRA ticket in description, if appropriate.
• Change is code complete and matches issue description
• Automated tests have been added to exercise the changes
• Reviewer's manual test instructions provided in PR description. See below.

Manual test instructions

1. Install this plugin build on a controller with a GitHub org folder or multibranch project.
2. Add a "Filter stale branches" behaviour to the GitHub source, set "Days stale" to e.g. 30, and tick "Dry run".
3. Re-index and confirm the build log lists which branches WOULD be filtered (with their last-commit age), and that none are actually removed from the job tree.
4. Untick "Dry run", re-index, and confirm branches with no commits in 30 days no longer appear as jobs, while recently-updated, default, and protected branches remain.
5. Repeat with "Filter stale tags" and "Filter stale pull requests"; verify the include/exclude regex fields correctly scope or exempt heads by name.

Reviewer checklist

• Run the changes and verify that the change matches the issue description
• Reviewed the code
• Verified that the appropriate tests have been written or valid explanation given

Documentation changes

• Link to jenkins.io PR, or an explanation for why no doc changes are needed

No separate jenkins.io doc changes proposed; each trait ships inline help.html describing its behaviour, consistent with the plugin's existing traits.

Users/aliases to notify

@bitwiseman — you reviewed #263 / JENKINS-60730 in 2020; tagging you given the history, and because I've tried to directly address the discovery-vs-build-strategy trade-off you raised then.

[jglick]

Briefly: no, this is handled by separate plugins.

[cdarninsuang-bamfunds]

Would you reconsider? For our teams the operational cost of an extra plugin — another artifact to install, trust, security-scan, and keep in lockstep across controllers — is real, and JENKINS-60730 suggests this is a first-class need for this plugin's users. This PR also adds include/exclude regex scoping, a dry-run preview, and a default/protected-branch guard that the separate plugin doesn't have. Happy to iterate on the approach if the discovery-filter mechanism is the sticking point.