Set up the Stale Item Wizard

Use this page as a field-by-field reference for the Stale Bot task in Azure DevOps. It covers every current option exposed by the task wizard and the matching YAML input names.

What the task does

The Stale Bot scans work items for inactivity, adds a stale tag and comment when an item crosses your threshold, and can optionally close and archive items that stay inactive after being marked stale.

Before you begin

The first step is to create an account and configure your Azure DevOps connection details. In the setup flow, you will need to provide:

your Azure DevOps organization name
your product key
the project name, if you are using a free account

This configuration is required before the task can connect to your organization and begin evaluating work items.

To complete the setup flow, go to the signup page: https://greypilgrim.tech/signup

Then configure your Azure DevOps details here: https://greypilgrim.tech/configure

Option groups

Core behavior

Wizard label	YAML input	Type	Default	What it controls
Days Until Stale	`daysUntilStale`	integer	`30`	Number of days with no updates before a work item is marked stale. `0` is allowed and marks eligible items immediately.
Close Stale Items	`closeStaleItems`	boolean	`false`	Enables the second pass that revisits already-stale items and closes them if they remain inactive.
Close Stale Items After Days	`closeStaleItemsAfterDays`	integer	`7`	Number of days to wait after the stale tag is added before closing the item. This field is only shown when `closeStaleItems` is enabled.
Dry Run	`dryRun`	boolean	`false`	Logs what the task would mark, rescue, close, or archive without making any changes.

Stale markers

Wizard label	YAML input	Type	Default	What it controls
Stale Tag	`customStaleTag`	string	`stale`	Tag applied to items when they become stale. Do not use commas, semicolons, or `@`.
Stale Comment	`customStaleComment`	string	blank	Comment posted when an item is marked stale. If left empty, the task uses: `This item has been marked stale. Please update within X days or it will be closed.`
Included Work Item Types	`includedItemTypes`	comma-separated string	`User Story,Task`	Limits the scan to specific work item types such as `Bug`, `Issue`, `Task`, or `Product Backlog Item`.

Notifications

Wizard label	YAML input	Type	Default	What it controls
Notify Assignee	`notifyAssignee`	boolean	`false`	Adds an `@mention` for the assigned user in the stale or close comment when an assignee exists.
Notify Creator On Unassigned	`notifyCreatorOnUnassigned`	boolean	`false`	If the work item is unassigned, mention the creator instead. This only has an effect when `notifyAssignee` is also enabled.

Exemptions

Wizard label	YAML input	Type	Default	What it controls
Exempt Active Iterations	`exemptActiveIterations`	boolean	`false`	Skips items that are currently in active or future iterations.
Exempt Area Paths	`exemptAreaPaths`	comma-separated string	blank	Skips items under the listed area paths. You can provide paths with or without the project prefix.
Exempt Iterations	`exemptIterations`	comma-separated string	blank	Skips items under the listed iteration paths. You can provide paths with or without the project prefix.
Exempt Tags	`exemptTags`	comma-separated string	blank	Skips items that contain any of the listed tags. Tags cannot contain commas, semicolons, or `@`.

Archiving

Wizard label	YAML input	Type	Default	What it controls
Auto Archive	`autoArchive`	boolean	`false`	Moves items to an archive area path when they are closed by the bot.
Archive Path	`archivePath`	pick list	blank	Target area path used when `autoArchive` is enabled. This field is only shown when `autoArchive` is enabled.

Important option interactions

Combination	Result
`autoArchive: true` and `closeStaleItems: false`	Invalid configuration. The task throws an error because items are only archived as part of the close flow.
`autoArchive: true` with no `archivePath`	Invalid configuration. You must choose a valid area path.
`notifyCreatorOnUnassigned: true` and `notifyAssignee: false`	No mention is added. Creator fallback is only used inside the notification flow.
Activity after an item is marked stale	The bot removes the stale tag instead of closing the item. Both field updates and new comments count as activity.

Input format notes

Field	Expected format
`includedItemTypes`	Comma-separated names such as `User Story,Task,Bug`
`exemptTags`	Comma-separated tag names such as `do-not-stale,high-priority`
`exemptAreaPaths`	Comma-separated area paths such as `Project\Support,Project\Archive\Manual Review`
`exemptIterations`	Comma-separated iteration paths such as `Project\Sprint 20,Project\Release Train`
`archivePath`	A valid Azure DevOps area path using backslashes, for example `Project\Archive`

The task trims extra spaces around comma-separated values. For area and iteration paths, the project name is added automatically if you omit it.

Example YAML

- task: StaleItemWizardTask@1
  displayName: Run stale bot
  inputs:
    daysUntilStale: '30'
    closeStaleItems: true
    closeStaleItemsAfterDays: '7'
    dryRun: false
    customStaleTag: stale
    customStaleComment: This item has been marked stale. Please update it if work is still active.
    includedItemTypes: User Story,Task,Bug
    notifyAssignee: true
    notifyCreatorOnUnassigned: true
    exemptActiveIterations: true
    exemptTags: do-not-stale,keep-open
    exemptAreaPaths: Product\\Security,Product\\Leadership
    exemptIterations: Product\\Hotfix
    autoArchive: true
    archivePath: Product\\Archive

Recommended starting point

If you are enabling the task for the first time, start with a dry run and a narrow scope:

Set dryRun to true.
Limit includedItemTypes to the work item types your team actually uses.
Add any exemption tags or paths that should never be touched.
Turn on closeStaleItems only after reviewing one or two dry run reports.
Turn on autoArchive last, after you confirm the archive area path exists.