Migrating from Dosu Stale Bot to better-stale-bot#

This guide is for existing Dosu customers using Dosu's internal stale bot who want to migrate to better-stale-bot, the open-source replacement built on GitHub Agentic Workflows.

better-stale-bot is the official migration path from Dosu's hosted stale bot. Dosu pulled the stale-bot idea out of the hosted product, rewrote it as a standalone workflow, and made it open source.

Step 1: Disable Dosu's stale bot#

Turn off the previous automation (Dosu's deployment stale bot and/or any other stale workflows like actions/stale) so two bots do not compete on items.

In the Dosu dashboard, go to Connections → Deployments → [your repo] → Issues → Stale Bot toggle and disable it.

Deprecation note: Dosu's hosted stale bot was deprecated on January 21, 2026, and is scheduled for full removal on August 1, 2026. It is being replaced by the standalone open-source better-stale-bot using GitHub Agentic Workflows. For existing deployments that still have stale bot enabled, the deployment details view includes a one-way disable toggle and a deprecation warning that reads "Once disabled, you will not be able to re-enable it." Once disabled, the section disappears permanently from the UI. After the August 1 removal date, better-stale-bot will be the only stale bot running — stale label removal happens on the next scheduled run, not in real time.

System independence: Dosu's event handler is independent from better-stale-bot and only responds to labels applied by Dosu bot accounts. That said, it's still recommended to disable Dosu's stale bot so you don't end up with redundant stale labelling on your issues.

Step 2: Install better-stale-bot#

Prerequisites:

• GitHub Actions enabled
• GitHub CLI 2.0+
• AI account: Copilot, Claude, or Codex

Repository secret (engine auth) — repo Settings → Secrets and variables → Actions (the wizard in Option A can help set this; Option B assumes you add it yourself)

The workflow defaults to Claude Haiku in YAML frontmatter (engine: id: claude, model: haiku). Use ANTHROPIC_API_KEY unless you change the engine and recompile. The template schedules a daily run (on: schedule: daily); adjust in frontmatter or during Option A setup if you want a different frequency.

Option A: add-wizard (recommended)#

Run from a clone of the repository where you want the bot (you need write access so the wizard can open a PR).

# 1. Authenticate with GitHub
gh auth login

# 2. Install the gh-aw CLI extension
gh extension install github/gh-aw

# 3. Add the workflow (sets secret, adds workflow, opens a PR — may need to manually merge)
# add a --skip-secret flag if you wish to set secret via GitHub UI instead
gh aw add-wizard dosu-ai/better-stale-bot/better-stale-bot

# 4. Pull locally (if needed)
git pull

Option B: Manual setup (alternative)#

In a local clone of the target repository, download the distribution markdown, compile, commit, and push.

# 1. Install gh-aw
gh auth login
gh extension install github/gh-aw

# 2. Add your engine secret in repo Settings → Secrets and variables → Actions
# ANTHROPIC_API_KEY (Claude), COPILOT_GITHUB_TOKEN (Copilot), or OPENAI_API_KEY (Codex)

# 3. Download, compile, and push
mkdir -p .github/workflows
curl -fsSL -o .github/workflows/better-stale-bot.md \
  https://raw.githubusercontent.com/dosu-ai/better-stale-bot/main/workflows/better-stale-bot.md
gh aw compile better-stale-bot
git add .github/ .gitattributes
git commit -m "Add better-stale-bot workflow"
git push

Run: gh aw run better-stale-bot, or open the Actions tab and run the workflow manually.

Billing: LLM usage is billed directly to your provided API key (Anthropic, OpenAI, or GitHub Copilot). See the billing section in the README for details.

Step 3: Map your old settings#

Map old settings using the ## Configuration section and frontmatter in better-stale-bot.md:

• Edit the Configuration table for thresholds and exempt labels; use label names as they appear on GitHub.
• Change per-run caps (safe-outputs → max:) only in frontmatter, then run gh aw compile. Each output type is capped separately; see Safe Outputs.

Label IDs vs. label names: Dosu's stale bot used internal GitHub label IDs for exclusions (excluded_label_ids), while better-stale-bot uses label names as plain text in the markdown. You don't need to look up IDs, just write the label names as they appear on GitHub.

Note: Since days-before-stale drops from 90 to 60, you may want to set it to 90 initially to avoid a sudden wave of stale labels on your first run.

Maintainer tagging: Dosu's hosted bot had a maintainer-tagging path that the standalone version does not include by default. The standalone workflow keeps the default behavior simpler. It removes the stale label when a non-bot user replies. If you want maintainer tagging, add that instruction to the Markdown policy and widen the safe outputs only as needed.

Policy/instruction changes in the markdown body take effect on the next run without recompile. Only YAML frontmatter changes (engine, safe-outputs max, schedule) need gh aw compile better-stale-bot.

To switch engines (e.g., Codex): set engine: codex with optional model:, add OPENAI_API_KEY, and recompile — see the engines reference.

That's it. The full README has additional details at https://github.com/dosu-ai/better-stale-bot.