Quick Answer

Annual Copilot Pro and Pro+ subscribers stayed on the legacy Premium Request Unit system when monthly plans moved to AI Credits on June 1, 2026. GitHub revised that multiplier table the same day: Claude Opus 4.6 through 4.8 now cost 27 premium requests per call, and GPT-5.5 costs 57. Check the live table before assuming your old math still holds.

Two June 1 changes, and only one hit annual plans

GitHub shipped two separate billing changes on the same date, and the timing makes them easy to conflate. Every monthly-billed Copilot plan retired Premium Request Units for AI Credits on June 1, 2026, a real-per-token pricing system covered in GitHub Copilot’s PRU to AI Credits Migration, Explained. Annual-billed Pro and Pro+ subscribers didn’t move at all. They stayed on the old multiplier system, unchanged in mechanism.

What did change for that group, on the exact same date, was the multiplier table itself. GitHub’s own documentation draws a firm line between the two systems: multipliers belong to the old request-based model and have no equivalent under Credits at all, a distinction that only makes sense once you know the table underneath it kept moving after the surrounding system was declared legacy. This post is about that table: what it charges today, why the most-cited number about it undersells the real cost, and what an annual subscriber can actually do before the next renewal.

What GitHub’s live multiplier table shows today

GitHub still publishes a full multiplier table for this legacy system, at a URL that says “legacy” in the path. The page itself narrows its own audience: Copilot Pro and Pro+ buyers, annual billing only, and only those who never left the old request-based system once June 1, 2026, arrived. Fetched directly from that page on 2026-08-19, here is every model it lists and the exact multiplier attached to it:

That’s sorted highest to lowest for readability; GitHub’s own table runs alphabetically. Every value above is copied directly from GitHub’s model-multipliers-for-annual-plans documentation, a page GitHub itself warns can move without notice. A separate table on the same page sets Copilot code review at a flat 13x multiplier for every pull request or IDE review it runs, regardless of which chat model is configured elsewhere. Turning on auto model selection anywhere it’s offered, chat, the CLI, the mobile app, or a cloud agent run, knocks 10% off whatever multiplier applies, so a 1x model bills at 0.9x instead.

Structural Comparison Matrix

Every figure in that table traces to GitHub’s own current documentation, cited by section below.

The 27x figure most people cite isn’t the table’s ceiling

Third-party coverage of this multiplier table, published as the June 1 changes were rolling out, described some models’ multipliers as rising “as much as 27x.” That figure isn’t wrong. Claude Opus 4.6, 4.7, and 4.8 really do sit at 27x on GitHub’s live table today, and that’s a real, heavy number for anyone whose workflow leans on Opus-class reasoning.

It’s also not the whole picture. GPT-5.5 carries a 57x multiplier on that same live table, more than double the number that’s been repeated across recap posts and community threads. Whether GPT-5.5 already had that multiplier when the 27x figure first circulated, or was added to the catalog afterward, isn’t something GitHub’s documentation records and isn’t something this post can verify against a primary source. What’s verifiable, directly, right now, is that 27x understates the current ceiling. A subscriber budgeting against “worst case, 27x” is actually budgeting against a number more than half of what the table can charge.

The specific claim that Claude Opus rose from a lower baseline to 27x traces to third-party technical coverage, not a GitHub announcement or changelog entry. GitHub’s own “What changed with Copilot billing” page describes the June 1 shift from PRU to token-based billing in general terms and doesn’t publish a before/after multiplier comparison anywhere. Read the specific “before” number as reported, not confirmed, and treat the current 57x and 27x figures above as the only parts of this story verified straight from GitHub’s own page.

What a 27x multiplier costs against a 1,500-request pool

The multiplier only means something once it’s run against an actual monthly allowance. GitHub’s own plan documentation sets that allowance at 300 premium requests a month for an annual Copilot Pro plan, and 1,500 for annual Pro+.

Run the current table’s numbers against those pools directly:

1. Pro+ (1,500 requests) against Claude Opus 4.7 at 27x: 1,500 / 27 = 55 calls before the pool empties.
2. Pro+ (1,500 requests) against GPT-5.5 at 57x: 1,500 / 57 = 26 calls, roughly half as many.
3. Pro (300 requests) against Claude Opus 4.7 at 27x: 300 / 27 = 11 calls for the entire month.
4. Pro (300 requests) against GPT-5.5 at 57x: 300 / 57 = 5 calls for the entire month.

Compare that against a lightweight model on the same plan. Claude Haiku 4.5 sits at 0.33x, so a Pro+ subscriber gets roughly 4,545 Haiku calls out of the same 1,500-request pool, a gap of two orders of magnitude between the cheapest and most expensive model on one table. Model choice was already a real lever under PRU. At today’s revised multipliers, it’s a much sharper one: reaching for Opus or GPT-5.5 by default on an annual plan burns through a month’s allowance in single digits to low double digits of calls, not the hundreds a lighter model affords.

Legacy also means frozen out of new models

The multiplier increase isn’t the only structural cost of staying on an annual plan past June 1. GitHub’s own documentation says so directly, on the same page as the multiplier table, not buried in a separate FAQ:

Users on legacy annual Copilot plans will not receive access to new models and features.

That’s a second, quieter tax on top of the pricing one. A monthly subscriber gets each new model as GitHub ships it, priced under Credits from day one. An annual subscriber on the legacy track is working from whatever model catalog existed when they last checked, with no guarantee a future model gets added to their table at all. Whether GPT-5.5 shows up as row 57x or doesn’t show up for a given annual account isn’t something this post can verify beyond what GitHub’s own table lists today.

What annual subscribers can actually do about it

GitHub lays out three explicit options for a Copilot Pro or Pro+ subscriber on an existing annual plan, described directly on its own “What changed with Copilot billing” page:

• Stay on the current annual plan under the legacy multiplier system. When the plan ends, the account is automatically downgraded to Copilot Free, not moved to AI Credits.
• Cancel the plan outright for a prorated refund, with the option to re-subscribe to the equivalent monthly plan afterward.
• Upgrade to a monthly paid plan now and receive prorated credit for the annual plan’s remaining value, landing on AI Credits immediately instead of waiting for the term to end.

None of those is obviously correct for every subscriber. Someone with months left on an annual term and a workflow that leans on Haiku-tier models at 0.33x isn’t facing the same math as someone burning Opus or GPT-5.5 calls regularly against a 300-request Pro pool. The multiplier table above is what makes that comparison concrete instead of hypothetical: run your own actual model mix against it before deciding whether to ride out the renewal or upgrade early.

Before your annual plan renews

Check which billing system an account actually runs on before assuming the September 1 credits reversion or the June 1 Credits migration applies to it. Neither one touches an annual Pro or Pro+ subscriber still inside their term; this multiplier table is the only mechanism actively affecting that group right now, and it’s the one most likely to go unnoticed because nothing about it required an email or a dashboard banner to take effect.

If an annual plan still has months left and the workflow on it leans on GPT-5.5 or Claude Opus regularly, run the math from this post against the actual monthly call count before the next renewal decision. Upgrading early trades the annual plan’s remaining value for prorated credit toward a monthly plan, landing on per-token Credits pricing right away instead of waiting for the term to end. Riding out the term only makes sense if the real usage pattern fits comfortably inside 300 or 1,500 premium requests at the multipliers that model mix actually costs today, not the multipliers it cost before this table was last revised.

Browse more coverage like this in the AI Productivity archive, or start from GitHub Copilot’s AI Credits Cliff hub for the full reversion story.

Quick Answer

GitHub added three ways to see AI Credits consumption in mid-2026: a per-user ai_credits_used field in the usage metrics API (2026-06-19), an individual per-cycle view in Copilot settings (2026-07-20), and an org- and enterprise-level usage dashboard (2026-07-22). Check all three before September 1, 2026, when promotional Business and Enterprise credit allowances revert to standard levels.

Three blind spots GitHub just closed

Before mid-2026, nobody using GitHub Copilot could see their real AI Credits consumption anywhere in the product. Not the seat holder burning through them, not the org owner managing the budget, not the enterprise admin rolling it up across teams. The number existed somewhere on GitHub’s billing backend, but the product gave you no live view of it.

That changed fast, in three separate shipments over about five weeks. GitHub added a per-user ai_credits_used field to the Copilot usage metrics API on 2026-06-19, an individual per-cycle usage view in Copilot settings on 2026-07-20, and an org- and enterprise-level usage dashboard on 2026-07-22, according to GitHub’s own changelog. None of these are budget controls. They are visibility, the thing you need before a budget control is even worth configuring.

That distinction matters for this specific series. GitHub’s promotional AI Credits allowance (3,000 credits per Business seat, 7,000 per Enterprise seat) reverts to the standard allowance (1,900 and 3,900) on September 1, 2026, per GitHub’s own billing docs. The pillar hub on that cliff covers the reversion itself. This post covers the narrower, more immediate question: how do you actually check where you stand right now, at each of the three levels GitHub just made visible.

See your own number: Copilot settings, Usage

If you hold a Copilot Business or Copilot Enterprise seat, your own consumption is two clicks away. Click your profile picture in the upper-right corner of GitHub, select Copilot settings, and look under Usage. The section is labeled “Usage this cycle”, confirmed directly on GitHub’s own AI Credits monitoring docs, and it shows how many AI credits you have used in the current billing period.

This view needs no admin role. It is your own consumption, gated only by holding a Business or Enterprise seat, not by being an org owner or billing manager. If you have never opened it, that is the two-minute check to run before reading the rest of this post.

Pull ai_credits_used straight from the API

The individual view answers “what did I use.” It does not answer “who on my team is closest to the cliff.” That is what the API field is for.

GitHub’s Copilot usage metrics API added an ai_credits_used field to its per-user reports on 2026-06-19. The per-user report family (*-users-1-day and *-users-28-day in GitHub’s own reference docs) returns one record per user, and ai_credits_used is defined there as the total AI credits a user consumed, one combined number across all of that user’s Copilot activity, without a separate breakdown by which model, feature, or surface generated it. The same reference page is explicit that this is a metrics signal for analyzing consumption, not a billed total, worth remembering before you treat it as an invoice line item.

Each per-user record carries more than the credit total. It also includes user_id, user_login, eight boolean used_* flags covering surfaces like chat, CLI, agent mode, and code review, and an ai_adoption_phase field. That last one is worth a closer look, since it is what powers the org-level dashboard covered next.

{
  "user_id": 4181923,
  "user_login": "octocat",
  "ai_credits_used": 742,
  "used_chat": true,
  "used_cli": false,
  "used_agent": true,
  "used_copilot_coding_agent": false,
  "used_copilot_code_review_active": false,
  "ai_adoption_phase": 1
}

The field names and their descriptions above are verified against GitHub’s own Copilot usage metrics reference. The specific values are illustrative, not a captured live response, since pulling a real one requires an org’s own API token. Per GitHub’s own docs, this endpoint is available to enterprise administrators and organization owners with access to Copilot usage metrics, not to an individual seat holder pulling their own record.

Structural Comparison Matrix

The dates are not decorative. All three views shipped inside a five-week window that ends five weeks before the September 1 allowance cut, which is a narrow amount of runway to notice a problem and act on it if nobody checks until the bill changes.

The dashboard ties credits to outcomes, not just spend

The 2026-07-22 dashboard is not a bigger version of the per-cycle number. It groups engaged users into four adoption phases, built from the same ai_adoption_phase field the API returns: Phase 0, no cohort, for users who did not meet the engagement bar for any phase; Phase 1, code first, for users who engaged with code completion or IDE agent mode; Phase 2, agent first, for users who touched exactly one of Copilot’s agent surfaces, its cloud agent, code review, or CLI; and Phase 3, multi-agent, for users who touched two or more of those same surfaces, or used the GitHub Copilot app, according to GitHub’s own changelog on the adoption-phase cohorts.

For each cohort, the dashboard surfaces average pull requests merged per month, median merge velocity, user counts, and lines of code produced, alongside a six-month trend and an adoption multiplier comparing passive users against engaged ones. That framing changes the conversation an org owner can have about credits. A team burning through its allowance in Phase 3 is a different problem than one burning through it in Phase 0, even if the raw ai_credits_used totals look identical.

Check this before September 1, not after

Three checks, three different owners. If you hold a seat, open Copilot settings and look at “Usage this cycle” today, not the week the allowance drops. Org owners should pull the dashboard from the Insights tab and see which adoption phase their heaviest users sit in before deciding where to draw a budget line. Enterprise admins need the same check at the enterprise level, since a spike hiding in one org’s numbers can stay invisible until everything gets rolled up.

None of the three views in this post set a limit or send an alert. They only show you the number. Once you know where you actually stand, setting Copilot budget controls before the cliff is the next step, the one that turns this visibility into an actual guardrail instead of a number you have to remember to keep checking.

Browse more coverage like this in the AI Productivity archive, or start from GitHub Copilot’s AI Credits Promo Cliff hub for the reversion itself.

Quick Answer

Agent Mode spends AI credits once per step in its read-edit-test-reread loop, not once per chat message. Each step resends the growing conversation history and every enabled tool’s full JSON schema, so a modest six-step bug fix already costs roughly 12 times a single chat question on the same model. Route routine steps to a cheaper model to control it.

Why a chat message and an agent step aren’t the same unit of spend

Copilot Chat’s per-token pricing is straightforward once you’ve seen it: the sibling piece in this series on how AI Credits are priced walks through the exact math, one prompt in, one response out, each priced per token at that model’s published rate. A single chat question against a lightweight model rarely reaches even a full credit.

Agent Mode reuses that same per-token pricing. The multiplier isn’t a different rate. It’s a different number of billed round trips. GitHub’s own Agent Mode 101 post describes it as an agentic loop that plans, edits, runs commands, checks the result, and course-corrects, naming three of its underlying tools by their function names: run_in_terminal executes a command, edit_file applies a change, read_file pulls a file’s contents into context. Each of those tool calls, and each result that comes back from one, is its own request to the model. A per-message mental model of cost, the one that made sense for Chat, quietly stops describing what you’re actually being billed for the moment Agent Mode starts looping.

What actually happens inside one Agent Mode step

Each step costs more than a chat message not only because there are more of them, but because of what gets resent on every single one. The VS Code team, who ship Copilot’s agent mode inside the editor, explained part of the mechanism directly in a June 2026 post on token efficiency:

Each tool is sent to the model with a full definition (a name, a description, and a complete JSON parameter schema), and historically every one was loaded into context on every request.

The same post describes the loop itself just as plainly:

An agentic coding turn can involve many sequential requests to the inference provider; one for each step the model takes as it calls tools and works towards a solution.

Put those two observations together and the mechanism is straightforward. Enable a handful of tools, and their full schemas ride along on every step, whether that step needs them or not. Run a test and get back a stack trace, and that stack trace becomes part of the context every step after it has to resend. A six-step bug fix doesn’t send six independent, similarly-sized requests. It sends six requests that each carry more than the one before it.

Structural Comparison Matrix

A real case: a month’s credits gone in a day

The clearest evidence for this mechanism isn’t a marketing multiplier. It’s GitHub Community discussion #197557, opened June 1, 2026, the same day GitHub’s AI Credits system went live. A Copilot Student-plan user reported their entire monthly allowance, 200 credits ($2.00), gone after what they described as around 10 to 20 Agent Mode requests, on the first day of a fresh billing cycle. That 200-credit figure comes from the reporting user’s own dashboard, not from a GitHub-published Student-plan table, so treat the allowance size as one user’s reported number rather than an official spec.

The poster’s own usage breakdown names three models against a credit total for each: 145.01 credits against GPT-5.4 mini, 35.98 against GPT-5 mini, and 18.93 against Claude Haiku 4.5, adding up to the full 200. Other users replied inside days of the same cutover with the same pattern: one reported 180 of 200 monthly credits gone within two to three days, another reported an entire allowance spent on roughly 10 to 15 agent requests against 4 to 5 simple chat messages that barely moved the number by comparison. That’s not one isolated complaint. It’s the same read-edit-test-reread loop, run by different people on different tasks, converging on the same outcome: Agent Mode requests cost meaningfully more than chat messages, consistently, not occasionally.

Why the multiplier compounds: the arithmetic on one bug fix

Real sessions vary too much to reduce to one universal number, so here’s a deliberately simple version of the mechanism, built from GitHub’s own published per-token rates rather than a captured trace. A single chat question, roughly 3,000 tokens of prompt and file context in, 400 tokens of answer out, against GPT-5 mini’s Lightweight-tier rate of $0.25 input and $2.00 output per million tokens, costs $0.00075 plus $0.0008, about $0.00155, or roughly 0.16 credits.

Now walk the same model through a six-step Agent Mode loop fixing one bug: read the failing file, propose an edit, run the tests, read back a failing result, revise, run the tests again. Because each step resends the conversation so far, plausible input token counts climb from around 4,000 on step one to around 14,500 by step six, while each step’s own output stays modest, a few hundred tokens for a tool call or a short summary. Total that across all six steps, 57,000 input tokens and 2,200 output tokens, at GPT-5 mini’s same rate, and the session costs about $0.0187, or roughly 1.87 credits, about 12 times the single chat question on the identical model.

Run the same six-step shape against a frontier model instead, Claude Opus 4.8’s Powerful-tier rate of $5.00 input and $25.00 output per million tokens (the same rate the pricing sibling in this series verifies directly), and the session costs 34 credits against a 2.5-credit chat question on that model, a comparable 12 to 14 times. Step count and growing context drive the multiplier. Model choice multiplies the dollar amount on top of that, but it isn’t what causes the multiplier in the first place.

Where the “roughly 1,000x” figure actually comes from

A number bigger than 12x shows up everywhere this topic gets covered: “GitHub’s own research found agentic tasks use roughly 1,000x more tokens than single-turn queries.” It’s a real sentence, written by a secondary aggregator, fireup.pro, syndicated through daily.dev, published July 14, 2026, and it attributes the figure to GitHub without linking to a GitHub blog post, changelog entry, or dataset that actually states it.

Checking that claim directly against GitHub’s own writing on the subject doesn’t confirm it. Neither GitHub’s Agent Mode 101 post nor the VS Code team’s token-efficiency piece, the two most relevant GitHub-authored sources on exactly this question, states a 1,000x figure or any single comparable multiplier. That doesn’t make the underlying pattern false: the arithmetic above and the real 197557 thread both point the same direction, agent sessions cost meaningfully more than chat messages. It does mean this post won’t repeat “1,000x” as a confirmed GitHub number, because the trail to confirm it runs out at a secondary source repeating an unlinked claim, not at GitHub itself.

The same secondary coverage states real bills jumped from $29 to $750 and from $50 to $3,000 a month, again without naming the developer, the thread, or the invoice behind either figure. This post treats those two numbers the same way: unconfirmed against a named source, worth noting as a widely repeated claim, not worth repeating as fact. The 197557 thread above is the concrete, checkable version of the same pattern, a real account, a real dashboard, and a credit total that adds up.

What actually reduces Agent Mode’s credit burn

None of this is an argument against Agent Mode. It’s an argument for spending its steps deliberately, and three levers are real, not hypothetical.

Route routine steps to a lighter model. The step count and context growth happen regardless of which model answers each step, but a Lightweight-tier model’s per-token rate is a fraction of a Powerful-tier one, and the arithmetic above shows that gap compounds across every step in the loop, not just one.

Work in checkpoints instead of one open-ended prompt. This site’s own prompting guide for AI coding assistants covers asking for a short plan before a multi-file change starts. The same habit caps how many exploratory read-edit-test cycles Agent Mode runs before you’ve confirmed it’s headed the right way, which caps the step count the arithmetic above multiplies against.

Let tool search and prompt caching do the rest. Neither requires a different prompt from you. They’re GitHub and the VS Code team optimizing what gets sent under the hood, cutting total session tokens for the median user by the percentages cited above, not a setting you configure by hand.

Agent Mode’s credit cost was never really about which model answers your question. It’s about how many times that model has to check its own work before the task is done. Watch the step count on a task before you watch the model name, cap exploratory loops with a plan first, and let the cheaper-model, cache-friendly defaults handle the rest. For the full reversion story this cluster sits inside, see the AI Credits cliff hub, and browse more coverage in the AI Productivity archive.

Quick Answer

Use gh agent-task create "<description>" to start a GitHub Copilot coding-agent session from your terminal instead of opening a browser tab; add --follow to watch it work live. Use gh agent-task view <id> to check progress later. It requires GitHub CLI v2.80.0+, an OAuth-authenticated login (not a PAT), and stays labeled preview.

What gh agent-task actually does

gh agent-task is a command group, not a single command: create, view, and list, plus the aliases gh agent, gh agents, and gh agent-tasks. All three subcommands operate on the same underlying object. GitHub’s own manual page defines it plainly:

“a task is a GitHub issue that triggers automated code changes from natural language instructions”

Run gh agent-task create with a description, and gh opens a GitHub issue behind the scenes, hands it to GitHub’s Copilot coding agent, an asynchronous background process that runs on GitHub’s own infrastructure, not your machine, and that agent makes the actual code changes, then opens a draft pull request for you to review. Nothing runs locally except the CLI call that kicks the session off.

It’s worth being precise about what’s shipping here, the same way the gh skill command needed the same clarification. gh agent-task is part of the standard GitHub CLI, cli/cli, the same binary that runs gh pr create and gh issue list. It is a different product from GitHub Copilot CLI (github/copilot-cli), which is an interactive terminal coding assistant with its own separate release history. gh agent-task doesn’t run Copilot’s reasoning in your terminal at all; it delegates the work to GitHub’s servers and lets you check in on it.

Where gh agent-task actually came from

It’s a fair question given how gh handles other optional functionality: did gh agent-task start life as a separate gh extension install-able package before becoming a built-in command? It didn’t. GitHub’s changelog entry, published 2025-09-25, introduced the agent-task command set as part of GitHub CLI v2.80.0 directly, no separate gh extension install step involved. The implementation itself confirms it: cli/cli pull request #11600, “Introduce gh agent-task,” added the command under pkg/cmd/agent inside the main cli/cli repository, the same tree every other built-in gh command lives in. No github/gh-agent-task or similar standalone extension repository exists; checking for one returns a 404. GitHub’s own release notes for v2.80.0 state the status without ambiguity: “The agent-task commandset is in preview and is subject to change without notice.” Nearly a year later, that’s still the current state: the live manual page at cli.github.com/manual/gh_agent-task still labels it preview today.

Structural Comparison Matrix

Before you run anything: version and auth

Check what you’re running first:

gh --version

gh agent-task needs GitHub CLI v2.80.0 or later. Update through whatever channel installed gh in the first place if you’re behind: brew upgrade gh on macOS, apt update && apt install gh on Debian/Ubuntu, scoop update gh on Windows, or a fresh binary from cli.github.com if you installed manually.

Try gh agent-task create with a PAT instead of an OAuth login and this is exactly what comes back:

“this command requires an OAuth token. Re-authenticate with: gh auth login”

Create a task

This is the documented example command from GitHub’s own manual:

gh agent-task create "build me a new app"

That alone opens a new agent task on the current repository and returns immediately, the session keeps running on GitHub’s servers after your terminal moves on. A few flags change that behavior:

# stream the session's logs in your terminal instead of returning immediately
gh agent-task create "build me a new app" --follow

# read a longer task description from a file instead of a shell string
gh agent-task create -F task-desc.md

# pipe a description in from stdin
echo "build me a new app" | gh agent-task create -F -

# target a specific base branch instead of the repo's default
gh agent-task create "fix errors" --base branch-name

# use a specific custom agent, defined in a <name>.md agent file, instead of the default
gh agent-task create "build me a new app" --custom-agent my-agent

1. -F/--from-file reads the task description from a file, or from standard input when the value is -, useful once a description is longer than fits comfortably in a shell argument.
2. --follow keeps the command running and prints session logs as they happen, instead of handing control back to your shell right away.
3. -b/--base sets which branch the resulting pull request targets, instead of the repository’s default branch.
4. -a/--custom-agent points at a named custom agent instead of the default Copilot coding agent.
5. Omit the description entirely and gh agent-task create opens your configured editor for one instead.

Check progress and list your tasks

gh agent-task view accepts either a session ID or a pull request number, since a task’s identity and its resulting PR are two ways of pointing at the same underlying run:

# by session ID
gh agent-task view e2fa49d2-f164-4a56-ab99-498090b8fcdf

# by pull request number in the current repo
gh agent-task view 12345

# by PR number in a different repo
gh agent-task view --repo OWNER/REPO 12345

# open it in the browser instead of the terminal
gh agent-task view 12345 --web

Add --follow to an already-running task the same way create --follow does, or --log to print what’s happened so far without following live. gh agent-task list shows your most recent tasks, 30 by default, controllable with -L/--limit:

gh agent-task list

Both view and list support --json with fields including id, state, pullRequestNumber, pullRequestUrl, createdAt, and completedAt, so a script can poll a task’s state without scraping terminal output.

It’s also one of the commands the July security fix touched

gh agent-task view and gh agent-task create were two of the seven commands patched in v2.97.0’s terminal-injection fix, GHSA-3m3g-3wcr-px46, because task output streamed from GitHub’s servers reached your terminal unsanitized before that release. This post only covers what gh agent-task does; for the vulnerability itself and the other six affected commands, see gh CLI 2.97.0 Fixes Terminal Injection in 7 Commands.

gh agent-task is also part of gh’s broader shift into an agent-tooling hub through 2026, alongside gh skill and gh discussion. See How GitHub CLI Became an AI-Agent Control Surface for that wider pattern across all ten changes in this series.

Reach for gh agent-task create the next time you want to delegate a well-scoped, described-in-words change, a refactor, a dependency bump, a small feature, without switching to a browser to file the issue and assign it. Skip it for CI automation for now; the OAuth-only requirement means it still needs a human to authenticate at least once, and issue #11845 shows GitHub hasn’t shipped a PAT-friendly path yet.

Browse more coverage like this in the Dev Tools archive, or start from GitHub CLI’s 2026 agent-era expansion for the full ten-part series.

Quick Answer

Update gh to v2.97.0 or later if you run gh api, gh pr diff, gh gist view, gh codespace logs, gh release download --output -, gh agent-task, or gh skills preview against repos, gists, or codespaces you don’t fully trust. Versions through v2.96.0 printed that content raw, letting embedded terminal escape sequences hijack what’s on your screen, tracked as GHSA-3m3g-3wcr-px46.

What GHSA-3m3g-3wcr-px46 actually breaks

A terminal escape sequence is a short byte sequence, usually starting with ESC (\x1b), that a terminal emulator interprets as a command instead of literal text: move the cursor, clear the screen, change colors, set the window title, or, on some emulators, quite a bit more than that. Normal output leans on these constantly, that’s how gh’s own colored diffs and progress spinners work. The bug is what happens when those bytes come from someone else’s file instead of from gh itself.

GitHub’s advisory states the flaw plainly:

“Several GitHub CLI commands print externally controlled content to the terminal without neutralizing terminal escape sequences. An attacker who can influence that content (for example a gist file, a pull request diff, a release asset, a codespace log) can embed escape sequences that are interpreted by a user’s terminal when they run one of the affected commands.”

Versions through v2.96.0 printed that untrusted content straight through, unfiltered. A gist author, a PR contributor, or anyone with push access to a Codespace could plant escape sequences that fire the moment a victim ran the ordinary, read-only command that displays their content, no click required beyond running gh itself. GitHub tracks this as GHSA-3m3g-3wcr-px46 and CVE-2026-64654, scored medium severity at a CVSS v4 base score of 5.1.

The advisory is direct about what a successful hit can do:

“An attacker who can influence the content shown by an affected command can inject terminal escape sequences into the terminal of a user who views that content. The practical impact depends on the user’s terminal emulator and ranges from cosmetic (title or on screen content manipulation) to, on some emulators, command execution.”

That range matters more than it first looks. Most terminal emulators only let an injected sequence rewrite what’s on-screen or rename the window title, which is annoying but not dangerous on its own. A smaller set of emulators support escape sequences that reach further, and “further” is the part that stops this from being merely cosmetic.

The 7 commands v2.97.0 sanitizes

Every affected command reads content someone else wrote and prints it straight to your terminal. Not every invocation is exposed, though, the advisory lists a specific triggering condition for each command:

Four of the seven, gh agent-task view/create, gh skills preview, gh pr diff, and gh codespace logs, have no unaffected case listed. Printing exactly that kind of content is what those commands are for, so v2.97.0’s fix has to run every time, not just under a specific condition.

How gh fixes it: sanitize by default, opt out only with —allow-escape-sequences

v2.97.0 (2026-07-31) closes all seven paths the same way: neutralize escape sequences before the bytes reach your terminal, on by default, no configuration required. Check what you’re running first:

gh --version

Anything before 2.97.0 needs an update, through whatever installed gh in the first place: brew upgrade gh on macOS, apt update && apt install gh on Debian/Ubuntu, scoop update gh on Windows, or a fresh binary from cli.github.com if you installed manually.

gh’s own source shows what the fix actually does. This is the relevant check inside gh gist view, one of the seven affected commands, in cli/cli’s current pkg/cmd/gist/view/view.go:

if !opts.AllowEscapeSequences && !opts.IO.IsStdoutTTY() {
    if iostreams.ContainsEscapeSequence(content.RawBytes()) {
        return errors.New("gist file contains terminal escape sequences; pass --allow-escape-sequences to view it anyway")
    }
    opts.IO.SetContentSanitization(false)
}

On a real terminal, gh renders escape sequences inert automatically, no error, no flag needed, you just see plain text where a hidden sequence would have been. When the output is piped somewhere else instead, gh gist view <id> | less, or into a script, it takes the stricter path: it refuses the content outright rather than silently rewriting the bytes, unless you pass the new flag deliberately:

gh gist view <id> --allow-escape-sequences

Not gh’s first escape-sequence bug

This isn’t a new bug class for gh, and the advisory says so directly:

“This extends the same class of issue addressed by CVE-2026-45803, which covered only gh run view --log, to the other command paths that reach the terminal without sanitization.”

CVE-2026-45803 fixed exactly one command. GHSA-3m3g-3wcr-px46 found six more paths doing the identical thing and fixed all of them in one release. If you patched for the earlier CVE and assumed the underlying bug class was closed, v2.97.0 is the release that says it wasn’t.

Where this fits in gh’s two 2026 security releases

v2.97.0 wasn’t a single-issue release. GitHub’s own release notes for that version open with four separate security advisories fixed the same day, not four terminal-injection bugs specifically: GHSA-3m3g-3wcr-px46 (this one), a URL-path-escaping bug in outbound request building (GHSA-4fjg-2h4q-fwg3), a partial-token leak in gh auth status for token types like github_pat_* and ghs_* (GHSA-cg6r-mpgc-h9mm), and a regex-escaping bypass in gh attestation verify’s --signer-repo/--signer-workflow matching (GHSA-mm27-mwq9-fr5g). This post covers only the terminal-injection one; the other three are a different bug class in different commands entirely.

v2.97.0 also wasn’t gh’s first security-driven release of the year. The month before, v2.96.0 (2026-07-02), the release right before this one, closed a real remote-code-execution path in gh codespace jupyter. See Update gh CLI Now: Codespace Jupyter RCE Fixed for that fix in full.

Two of the seven patched commands, gh agent-task’s view and create subcommands, also belong to the newest command surface gh shipped in 2026, still labeled preview. This post only covers the security fix; for what gh agent-task actually does and how to drive a Copilot coding session from it, see gh agent-task: Run Copilot Coding Sessions From gh.

Both releases are part of the same wider wave covered in GitHub CLI’s 2026 agent-era expansion.

Update to v2.97.0 today if you haven’t already, that’s the entire fix, no configuration required on your end. If you’re stuck on an older version for now, treat gh skills preview, gh codespace logs, gh gist view, gh agent-task, gh api, gh pr diff, and gh release download --output - the same way you’d treat opening an attachment from someone you don’t know: fine against your own repos and gists, risky against anything else. Skip --allow-escape-sequences entirely unless you already trust exactly what you’re about to print.

Browse more coverage like this in the Dev Tools archive.

Quick Answer

gh codespace jupyter opened a Codespace-supplied URL without checking it was a loopback address, letting a malicious Codespace hand your local VS Code a vscode:// link and run commands on your machine. It affected v2.10.0 through v2.95.0. Update to gh CLI v2.96.0 or later now; the fix validates the URL before opening it.

How gh codespace jupyter opened the door

gh codespace jupyter -c <name> is supposed to do one thing: start a remote JupyterLab server inside a Codespace and open it in your browser. The URL for that server doesn’t come from gh itself. A process running inside the Codespace generates it and hands it back to your local CLI, which then opens it without checking what it actually points to.

That’s the entire bug. GitHub’s advisory, tracked as GHSA-8cg3-r6g9-fpg2 and assigned CVE-2026-59831, states the root cause plainly:

“The CLI trusts the URL provided by the Codespace and opens it as-is, without confirming that it is a loopback JupyterLab web address.”

The part that turns a missing validation check into remote code execution is what the browser launcher itself accepts. It doesn’t just open http:// and https:// links. It also honors vscode:// and vscode-insiders:// URLs, handing them straight to VS Code. A compromised or malicious Codespace can return one of those instead of a normal JupyterLab address. Once the OS forwards that link, VS Code treats it like any other link it’s been handed and follows it.

“Successful exploitation requires the victim to accept one VS Code ‘open URL’ or Workspace Trust prompt.”

The advisory also places this bug in context rather than treating it as new territory:

“This is a variant of CVE-2024-52308. That remediation validated the SSH connection details for gh codespace ssh and gh codespace logs, but did not cover the equivalent Jupyter code path.”

In other words, gh fixed this exact class of bug for two other Codespace commands back in 2024 and missed the third. GitHub CLI v2.96.0, shipped 2026-07-02, closes that gap by checking the Jupyter server URL first: anything other than a loopback http or https address now gets rejected before the CLI ever opens it.

GitHub rates the bug Medium severity, CVSS 3.1 base score 4.4:

CVSS:3.1/AV:N/AC:H/PR:L/UI:R/S:C/C:L/I:L/A:N

Network attack vector, high attack complexity, low privileges required, user interaction required: that last part is the same single trust-prompt click the quote above describes, not a marketing gloss on the score.

Structural Comparison Matrix

Check your gh version and update

Run this first, before anything else in this post matters:

gh --version

If the output reports anything from v2.10.0 up to and including v2.95.0, you’re running the vulnerable code path. gh has no built-in self-update command, so update through whatever installed it in the first place:

# macOS (Homebrew)
brew upgrade gh

# Debian/Ubuntu
sudo apt update && sudo apt install gh

# Windows (winget)
winget upgrade --id GitHub.cli --source winget

# Windows (Scoop)
scoop update gh

If none of those match your setup, grab a fresh binary from cli.github.com directly. Run gh --version again afterward and confirm it reports v2.96.0 or later before you run gh codespace jupyter against anything again.

Until you’ve confirmed the update, GitHub’s own remediation guidance is worth following for real: only run gh codespace jupyter against Codespaces you actually trust, and prefer Codespaces built from default or pre-built devcontainers rather than custom setup scripts you haven’t reviewed.

What shipped alongside this fix

v2.96.0 wasn’t a single-issue release. The same version also dropped the authentication requirement for gh release download against public repositories, an unrelated behavior change, not a security fix, covered on its own in gh release download No Longer Needs Auth (Public Repos).

One month later, v2.97.0 fixed a different class of problem entirely: four terminal escape-sequence injection bugs across seven commands, including gh api and gh pr diff, tracked as a separate advisory. That release doesn’t touch the Jupyter URL path this post covers. See gh CLI 2.97.0 Fixes 4 Terminal Injection Bugs for what it changed and whether it affects commands you actually run.

Both fixes are part of the same wave covered in GitHub CLI’s 2026 agent-era expansion, which walks through everything gh shipped between April and July 2026, new commands and security fixes together.

Update now if you haven’t. This isn’t a theoretical hardening measure; it’s a patched remote-code-execution path with a CVE and a working exploit chain, and the fix costs you one package-manager command. Skip gh codespace jupyter against any Codespace you don’t fully trust until gh --version reports v2.96.0 or later.

Browse more coverage like this in the Dev Tools archive.

Quick Answer

GitHub rotated the PGP key that signs gh CLI’s apt and RPM Linux packages on 2026-04-08, publishing a keyring with both the current and new key so installs don’t break mid-rotation. The old key expires September 5, 2026. If you installed gh via apt, dnf, or yum before then and haven’t updated since, re-fetch the keyring now.

What’s actually rotating, and why now

GitHub’s own changelog entry states the change plainly:

“We’ve published an updated PGP keyring for GitHub CLI’s Linux package repositories. The keyring now includes both the current signing key and a new replacement key.”

That’s the whole announcement in two sentences, dated 2026-04-08. The detail that makes it worth a dedicated post is what it’s protecting against. The key currently signing every gh package built for apt, dnf, yum, and zypper repositories expires on September 5, 2026. GitHub generated a replacement ahead of that date and published a combined keyring file containing both fingerprints, so anyone who re-runs their distro’s install steps between April 8 and September 5 already has the new key in place before the old one stops working.

This isn’t GitHub’s first time handling a gh key expiration. Back in September 2024, the previous signing key expired without a replacement ready, breaking Linux installs and updates until GitHub shipped an emergency extension, tracked in cli/cli issue #9569. This time, the rotation shipped nearly five months ahead of the expiry date instead of after it, specifically to avoid a repeat.

Structural Comparison Matrix

Every row above is confirmed against GitHub’s own remediation guide in cli/cli issue #13118, not summarized from memory.

Confirm which keyring you’re actually running

Before changing anything, check what your system already has. On Debian or Ubuntu:

gpg --show-keys /etc/apt/keyrings/githubcli-archive-keyring.gpg

Two pub entries in the output mean you’re already covered:

pub   rsa4096 2022-09-06 [SC] [expires: 2026-09-05]
      2C6106201985B60E6C7AC87323F3D4EA75716059
uid                      GitHub CLI <opensource+cli@github.com>
sub   rsa4096 2022-09-06 [E] [expires: 2026-09-05]

pub   rsa4096 2026-04-07 [SC]
      7F38BBB59D064DBCB3D84D725612B36462313325
uid                      GitHub CLI <opensource+cli@github.com>
sub   rsa4096 2026-04-07 [E]

Only the first block means you still need to update. On Fedora, RHEL, CentOS, Amazon Linux 2, or openSUSE, check the RPM keyring instead:

rpm -qa gpg-pubkey | xargs -I{} sh -c 'rpm -qi {} | grep -q "opensource+cli@github.com" && echo {}'

One matching entry means the old key only; two means you’re already set. If gpg --show-keys can’t find the apt keyring at /etc/apt/keyrings/, check the older location instead: gpg --show-keys /usr/share/keyrings/githubcli-archive-keyring.gpg.

Update the apt keyring (Debian/Ubuntu)

If you’re down to one key, replace the local keyring file, then refresh and reinstall gh:

sudo mkdir -p -m 755 /etc/apt/keyrings
sudo wget -qO /etc/apt/keyrings/githubcli-archive-keyring.gpg https://cli.github.com/packages/githubcli-archive-keyring.gpg \
    && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg
sudo apt update
sudo apt install gh

Prefer curl? Swap the middle line for sudo curl -fsSL -o /etc/apt/keyrings/githubcli-archive-keyring.gpg https://cli.github.com/packages/githubcli-archive-keyring.gpg, same effect. Re-run the gpg --show-keys check from the previous section afterward and confirm both pub entries are present.

Update the RPM repo config (Fedora/RHEL/CentOS/Amazon Linux 2)

RPM-based systems import keys at install time from the repo config file itself, so the fix is re-fetching that file rather than swapping a standalone keyring. Match the block below to the package manager you originally installed with:

sudo dnf config-manager addrepo --overwrite --from-repofile=https://cli.github.com/packages/rpm/gh-cli.repo
sudo dnf update gh

sudo dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo
sudo dnf update gh

sudo yum-config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo
sudo yum update gh

Your package manager prompts you to confirm the new key during that update. Check the fingerprint it shows against 7F38BBB59D064DBCB3D84D725612B36462313325 before accepting; it should match exactly.

Docker builds and CI base images

A base image that installs gh in one layer and runs apt update in a later, separate build is the case most likely to break silently, since the keyring layer doesn’t get rebuilt just because a downstream layer changed. Own that keyring-adding layer yourself? Trigger a fresh build of it instead of patching around it, so the image bakes in the current file automatically. When you don’t control it, add a dedicated layer before any apt update:

RUN wget -qO /etc/apt/keyrings/githubcli-archive-keyring.gpg https://cli.github.com/packages/githubcli-archive-keyring.gpg \
    && chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg

If a base image happens to carry the gh repo but your build never actually installs gh, the simpler fix is dropping the repo instead of tracking its key rotations:

sudo rm /etc/apt/sources.list.d/github-cli.list

Installing gh for the first time needs none of this

Everything above is remediation for a gh install that already exists. Run apt, dnf, or yum fresh today and you already pull the current keyring file, which has carried both fingerprints since April 8, 2026. Follow GitHub CLI’s standard Linux install instructions, and you’re covered without touching any command on this page.

This key rotation is one piece of a wider wave of gh changes across 2026, alongside new command groups like gh skill and two separate security-driven releases. See GitHub CLI’s 2026 Agent-Era Expansion for the full picture of what shipped and when.

Update your keyring the next time you touch a Linux box or CI image that provisions gh, not on September 5 when it starts failing. It’s a two-command fix today and a broken pipeline later if you wait.

Browse more coverage like this in the Dev Tools archive.

Quick Answer

Use gh issue edit <number> --parent <number> to link an issue under a parent, --add-sub-issue/--remove-sub-issue on the parent to manage its children, and --add-blocked-by/--add-blocking for cross-issue dependencies. All of it needs GitHub CLI v2.94.0 or later. Skip the web UI or hand-rolled GraphQL calls once you’re scripting bulk changes to an issue tree.

GitHub CLI’s gh issue command picked up issue types, parent/sub-issue relationships, and cross-issue dependencies in v2.94.0, shipped 2026-06-10. Before that release, every one of those relationships lived only in the GitHub.com web UI. Reading or changing a project’s issue tree from a script meant writing raw gh api graphql calls against the Issues GraphQL schema by hand, since gh issue itself had no concept of a parent, a sub-issue, or a dependency.

Structural Comparison Matrix

Check your gh version before any of this works

gh --version

Every flag in this post needs GitHub CLI v2.94.0 or later. If your version is older, update through whatever channel installed gh: brew upgrade gh on Homebrew, winget upgrade --id GitHub.cli --source winget on Windows, or your Linux package manager. This machine is running v2.97.0, and every command below was run against that install.

Set, change, or remove a parent issue

gh issue edit takes one number or URL argument for the parent, straight from GitHub’s own manual page:

gh issue edit 23 --parent 100

--parent does double duty. Run it once to link an unparented issue, or run it again later with a different number to move that issue under a new parent. There’s no separate flag for the two cases.

gh issue edit 23 --remove-parent

GitHub’s own 2026-06-10 announcement describes the same capability this way:

Link, change, or remove a parent with --parent, --set-parent, and --remove-parent.

Create a new issue directly as a sub-issue

gh issue create takes the same --parent flag, so a new issue can join the hierarchy at creation instead of needing a follow-up edit call:

gh issue create \
  --title "Fix login redirect loop after SSO callback" \
  --body "Users land back on /login after a successful SSO callback instead of the app." \
  --parent 100

The parent accepts a URL too, useful when the parent lives in a different repository: --parent https://github.com/cli/go-gh/issues/42, straight from the flag’s own documented example.

Link and unlink sub-issues from the parent side

The same relationship can be managed from the parent issue instead of the child, and --add-sub-issue takes a comma-separated list for more than one at a time:

gh issue edit 100 --add-sub-issue 123,124

gh issue edit 100 --remove-sub-issue 124

Read the hierarchy back with —json

gh issue view and gh issue list both expose parent, subIssues, and subIssuesSummary as JSON fields, so a script can read the tree without scraping HTML. Run against a real public issue on cli/cli itself, this is the actual shape gh returns:

gh issue view 5545 --repo cli/cli --json parent,subIssues,subIssuesSummary

{
  "parent": null,
  "subIssues": { "nodes": [], "totalCount": 0 },
  "subIssuesSummary": { "completed": 0, "percentCompleted": 0, "total": 0 }
}

That particular issue has no sub-issues linked, which is why the fields are empty. When they’re populated, subIssues.nodes holds the full list of child issue objects, and subIssuesSummary gives a ready-made completed/total/percentCompleted count, so a script doesn’t have to iterate the array itself to show progress.

Set and filter by issue type

gh issue edit 23 --type Bug

gh issue edit 23 --remove-type

gh issue list filters by the same field. This is real output from cli/cli’s own tracker, showing the full issueType object a populated field actually returns:

gh issue list --repo cli/cli --type Bug --limit 1 --json number,title,issueType

[
  {
    "issueType": {
      "id": "IT_kwDOA48Fh84AtH84",
      "name": "Bug",
      "description": "An unexpected problem or behavior",
      "color": "RED"
    },
    "number": 9569,
    "title": "Can't install / update `gh` due to expired GPG key?"
  }
]

Set cross-issue dependencies

Dependencies are separate from parent/child hierarchy. “Blocked by” and “blocking” describe ordering between two issues that don’t need a parent-child relationship at all:

gh issue edit 123 --add-blocked-by 200 --add-blocking 300,301

Both flags take comma-separated lists, and both directions can be set in the same call, as shown in gh issue edit’s own --help output. Remove either side the same way:

gh issue edit 123 --remove-blocked-by 200

gh issue create has the equivalent flags for setting dependencies at creation time: --blocked-by and --blocking, both accepting the same comma-separated issue-number or URL lists.

Where this fits in the wider gh CLI wave

Sub-issue and dependency support shipped in the same v2.94.0 release as gh discussion, GitHub CLI’s new command group for GitHub Discussions. Neither depends on the other; they landed the same day because both closed a gap where GitHub.com had a feature gh couldn’t touch at all. See gh discussion: GitHub Discussions in Your Terminal for that side of the same release, and GitHub CLI’s 2026 Agent-Era Expansion for the full ten-part wave this cluster belongs to.

Reach for these flags the moment you’re managing more than a handful of issues in one hierarchy, triaging a big feature into sub-issues from a script, or wiring an agent to file work broken down by parent task automatically. For a one-off parent link on a single issue, the GitHub.com sidebar is still fewer keystrokes. Once you’re doing it more than once, gh issue edit --parent is the version that survives being scripted.

Browse more coverage like this in the Dev Tools archive.

Quick Answer

Use gh discussion list, view, create, edit, and comment for day-to-day terminal work on GitHub Discussions: browsing threads, reading replies, opening a new discussion, or answering one. Reach for gh api graphql only when you need to close, lock, delete, or react to a discussion, since the command group doesn’t cover those yet. Requires GitHub CLI v2.94.0 or later.

What gh discussion replaces

GitHub Discussions has had a public GraphQL API for years. A repository exposes its threads through a discussions connection, and creating one meant firing a createDiscussion mutation by hand, but until 2026-06-10 there was no first-class gh command wrapping any of it.

Reading a thread’s replies meant writing a GraphQL query against that discussions connection yourself and paging through the results with after/before cursors, the same generic pagination pattern every list field in GitHub’s GraphQL schema uses. Starting a new discussion meant looking up the target category’s internal node ID first, then composing a createDiscussion mutation with that ID, the repository’s ID, a title, and a body, all through gh api graphql -f query=.... gh issue and gh pr never asked a user to know GraphQL to do routine work. gh discussion closes that specific gap.

GitHub’s changelog entry for the release states the fix plainly:

“Install or upgrade to GitHub CLI v2.94.0 to get started on any repository where GitHub Discussions is enabled.”

That’s the same v2.94.0 release that added sub-issue and dependency flags to gh issue, shipped the same day. See Manage GitHub Sub-Issues and Dependencies via gh CLI for that half of the release; this post covers gh discussion only.

Structural Comparison Matrix

| Operational Aspect | Before gh discussion (raw gh api graphql) | After (gh discussion, v2.94.0+) | | :--------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- | -------- | | Listing recent discussions | Write a query against the repository’s discussions connection, handle cursor pagination by hand | gh discussion list --state <state> --label <names> | | Reading a thread’s replies | Query nested comment/reply connections, tracking your own after cursor between pages | gh discussion view <number> --comments --order <oldest | newest> | | Starting a new discussion | Look up the category’s node ID separately, then send a createDiscussion mutation with repository ID, category ID, title, and body | gh discussion create --title <title> --category <category> --body <body> | | Editing title, body, or labels | Send an updateDiscussion mutation with only the fields you’re changing | gh discussion edit 123 --title "Updated title" --add-label bug | | Scripting against results | Parse raw GraphQL JSON yourself | --json plus -q/--jq for a filtered, scriptable field list |

Before you run anything: version and scope

gh --version

gh discussion needs GitHub CLI v2.94.0 or later, and it only works against a repository that has GitHub Discussions turned on; run it against a repo without that feature enabled and there’s nothing for the command to list. Every subcommand also accepts -R/--repo <[HOST/]OWNER/REPO> to target a repository other than the one in your current working directory.

List discussions from the terminal

# every open discussion, most recently updated first (the defaults)
gh discussion list

# only General-category discussions
gh discussion list --category General

# closed discussions from one author
gh discussion list --state closed --author monalisa

# any state, filtered by label
gh discussion list --state all --label bug,enhancement

# unanswered discussions, JSON output for scripting
gh discussion list --answered=false --json number,title,url

Every one of those is a real example from gh’s own manual for gh discussion list. --state accepts open, closed, or all (default open); --sort takes created or updated (default updated); --order takes asc or desc (default desc). The short alias gh discussion ls works too, matching the gh issue ls / gh pr ls convention the rest of gh already uses.

Read a discussion and its replies

gh discussion view 123
gh discussion view 123 --comments
gh discussion view 123 --comments --order oldest
gh discussion view 123 --comments --limit 10

Pass a bare number, a full discussion URL, a comment’s node ID, or a comment’s URL as the target; all four forms are documented and work interchangeably. --comments pulls the replies alongside the discussion body, --order controls whether they print oldest-first or newest-first (default newest), and --limit caps how many replies come back per page (default 30). Add -w/--web instead to skip the terminal output entirely and open the discussion in a browser.

Start a new discussion

# interactive: gh prompts for category, title, and body
gh discussion create

# non-interactive: pass everything as flags
gh discussion create --title "My question" --category "Q&A" --body "Details here"

Both are the documented examples from gh’s manual. Running gh discussion create with no flags on an interactive terminal walks you through category, title, and body one at a time. For scripts, pass --title, --category, and either --body or --body-file - (the trailing - reads the body from stdin) to skip the prompts entirely. --category takes the category’s name or slug, not an internal ID, which is the piece the raw GraphQL mutation made you look up separately.

Edit a discussion, then comment on it

# change title, body, and category together
gh discussion edit 123 --title "Updated title" --body "Updated body" --category "Ideas"

# add and remove labels in the same call
gh discussion edit 123 --add-label "bug,help wanted" --remove-label "stale"

gh discussion edit takes the same shape as create, plus --add-label/--remove-label for label changes that create doesn’t handle.

# top-level comment
gh discussion comment 123 --body 'Thanks'

# reply to a specific comment, by its URL
gh discussion comment 'https://github.com/OWNER/REPO/discussions/123#discussioncomment-456' --body 'Thanks'

# edit or delete a comment or reply
gh discussion comment 'https://github.com/OWNER/REPO/discussions/123#discussioncomment-456' --edit --body 'Updated'
gh discussion comment 'https://github.com/OWNER/REPO/discussions/123#discussioncomment-456' --delete --yes

gh discussion comment takes the same four target forms as view: a discussion number posts a new top-level comment, while a comment’s own URL or node ID replies to (or, with --edit/--delete, modifies) that specific comment. --yes skips the delete confirmation prompt, useful in a script where nothing is watching the terminal to answer it.

What gh discussion still can’t do

The five subcommands cover browsing and content, not moderation. GitHub’s GraphQL reference for Discussions lists mutations that gh discussion doesn’t wrap at all: closeDiscussion, reopenDiscussion, deleteDiscussion, addUpvote/removeUpvote, and markDiscussionCommentAsAnswer. The Discussion type also implements GitHub’s generic Lockable interface, so lockLockable/unlockLockable apply too. Closing a discussion as resolved, deleting one outright, upvoting a reply, locking a thread, or marking a comment as the accepted answer all still mean dropping to gh api graphql and calling the matching mutation by hand, the exact friction this command group otherwise removes.

That gap is worth knowing before you script anything that depends on discussion state changing beyond editing content. A bot that needs to auto-close stale discussions, for instance, can list and read them through gh discussion but still needs a raw GraphQL call for the actual close.

Where this fits in GitHub CLI’s 2026 agent push

gh discussion is one piece of a wider wave covered in GitHub CLI’s 2026 agent-era expansion, which also added gh skill for managing AI agent skills and, in this same v2.94.0 release, sub-issue and dependency flags on gh issue (see Manage GitHub Sub-Issues and Dependencies via gh CLI).

Reach for gh discussion the next time you’d otherwise open a browser tab to check on a repository’s Discussions tab, or the next time a script needs to read or post to one. Skip the raw gh api graphql route unless you land on one of the gaps above; hand-writing GraphQL for something gh discussion list already does in one line is wasted typing.

Browse more posts like this in the Dev Tools archive.

Quick Answer

gh release download used to require an authenticated session even for public repos, hitting the same auth-gate error every other unauthenticated command threw. GitHub CLI v2.96.0 removes that gate for public repositories, matching gh extension install. Drop the GH_TOKEN line from CI steps that only pull public release assets; keep it for private repos.

What the auth gate actually blocked

gh runs one shared check before most subcommands execute: is there a token, or a logged-in host, available. Individual commands don’t get their own custom login logic; they either run behind that shared gate or they’re explicitly marked to skip it. Before v2.96.0, gh release download wasn’t marked to skip it, so a CI step pulling a release asset from a completely public repo still hit the same “please authenticate” wall as any command that genuinely needed write access.

gh extension install got the same exemption three months earlier, in v2.90.0. The problem there was more specific: Codespaces issues SAML-scoped tokens that fail authorization checks against extension repos they were never scoped for, so installing a public extension from inside a Codespace could fail even though installing it never needed elevated access. PR #13176 fixed it with a one-line opt-out, cmdutil.DisableAuthCheck, added specifically to the extension install subcommand.

PR #13723, which shipped the gh release download change in v2.96.0, points at that exact precedent:

“Release endpoints for public repositories are readable anonymously over REST, so the login gate is unnecessary. Removing it is the same one-line cmdutil.DisableAuthCheck change that #13176 made for gh extension install.”

Both fixes trace back to the same tracking issue, #2680, “Allow certain requests to be unauthenticated” - a running list of gh commands that were gated by default even when the underlying GitHub API endpoint never required a session in the first place.

Structural Comparison Matrix

What actually happens now, verified live

With that isolated, credential-free config, gh release download against a real public release succeeds with no token at all:

$ gh release download v2.96.0 --repo cli/cli -p "gh_2.96.0_checksums.txt"
$ ls
gh_2.96.0_checksums.txt

No prompt, no error, exit code 0. That’s gh’s own v2.96.0 checksums file, pulled from cli/cli’s public release, using the exact repo the release notes’ own example points at.

The shared auth gate is still very much alive elsewhere in the same binary. gh release view never got the same opt-out gh release download did, so running it against the same isolated, unauthenticated session reproduces the exact wall gh release download itself used to hit before v2.96.0:

$ gh release view v2.96.0 --repo cli/cli --json assets
To get started with GitHub CLI, please run:  gh auth login
Alternatively, populate the GH_TOKEN environment variable
with a GitHub API authentication token.

Exit code 4. That message comes from the same shared pre-command check gh release download was routed through before v2.96.0; only the per-command opt-out changed, not the message itself.

Use it in CI: drop the token for public assets

gh ships preinstalled on GitHub-hosted runners, so a workflow step pulling a public release asset no longer needs a token wired in just to clear the auth gate:

name: Fetch a public release asset
on:
  workflow_dispatch:

jobs:
  download:
    runs-on: ubuntu-latest
    steps:
      - name: Download checksums from a public release
        run: >
          gh release download v2.96.0 --repo cli/cli
          -p "gh_2.96.0_checksums.txt" --clobber

No env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} line, and no PAT stored as a repo secret for a step that never needed write access in the first place. --clobber overwrites a stale file from a previous run instead of failing; --skip-existing does the opposite if the goal is to avoid re-downloading unchanged assets, and -D <directory> picks a target other than the current directory, per gh’s own manual for gh release download.

One caveat worth keeping in mind: dropping the token doesn’t remove every reason to keep one. Unauthenticated requests share GitHub’s public rate limit of 60 requests per hour, against 5,000 per hour for an authenticated request. A workflow that only downloads one asset from one public repo won’t notice. A workflow that also calls the API repeatedly in the same run, across matrix jobs sharing the same runner IP, might still want the token, for the rate limit headroom, not because the download itself demands it anymore.

What else shipped in the same release

v2.96.0 wasn’t a single-change release. The same version fixed a real remote-code-execution path in gh codespace jupyter, where a malicious Codespace could hand the CLI a vscode:// URL and get command execution on the victim’s machine after one click-through. That fix is unrelated to the auth-gate change here and covered on its own in Update gh CLI Now: Codespace Jupyter RCE Fixed.

Both changes, along with the rest of gh’s 2026 expansion into agent-skill management and Discussions support, are covered in GitHub CLI’s 2026 agent-era expansion, the hub this post is part of.

Drop the token from any CI step that only downloads a public release asset; it’s dead weight now, not a requirement. Keep it anywhere the repo is private, or where the same job leans on the API enough that the rate-limit gap actually matters.

Browse more coverage like this in the Dev Tools archive.

Quick Answer

Use gh skill install <repo> <skill> --agent <name> to add a published skill to one agent with no manual cloning. Run gh skill search <query> first when you don’t know the exact skill name; it queries GitHub’s Code Search API for SKILL.md files. Requires GitHub CLI v2.90.0 or later; the feature is still labeled preview.

What gh skill replaces

Before GitHub announced gh skill on 2026-04-16, installing an agent skill, a portable package of instructions, scripts, and resources built to the Agent Skills spec, for a specific coding agent meant finding the right repository, cloning or downloading it, and copying files into whatever directory that particular agent expected. You did that by hand, once per agent, with no install command, no update path, and no way to publish a skill back out that any agent’s CLI understood natively.

gh skill puts that whole lifecycle behind a binary most developers already have installed. It ships five subcommands: install, preview, search, update, and publish, all sharing the same --agent flag so the same command works whether the target is Claude Code, GitHub Copilot, Cursor, Codex, Gemini CLI, or Antigravity. Beyond those six, the flag recognizes more than 30 agents total.

It’s worth being precise about what’s shipping here: gh skill is part of the standard GitHub CLI, cli/cli, the same binary that runs gh pr create and gh issue list. It’s a different product from the separate GitHub Copilot CLI.

Structural Comparison Matrix

Before you install: version and scope

gh --version

gh skill needs GitHub CLI v2.90.0 or later. If your version is older, update through whatever channel you installed gh with (brew upgrade gh on Homebrew, winget upgrade --id GitHub.cli --source winget on Windows, or your Linux package manager) before any command below will work.

Two more things worth knowing before your first install:

• --scope controls where a skill lands. The default, project, installs into the current git repository. user installs into your home directory instead, making the skill available across every project.
• Project scope isn’t a separate folder per agent, either: GitHub Copilot, Cursor, Codex, Cline, OpenCode, and Warp all point at the same .agents/skills path, so installing once there covers every one of those six without repeating the command.

Install a skill for one agent

This is the documented example command from GitHub’s own manual:

gh skill install github/awesome-copilot documentation-writer --agent claude-code --scope user

1. github/awesome-copilot is the repository the skill lives in.
2. documentation-writer is the skill’s name inside that repo. Add @v1.2.0 or @<commit-sha> after the name to pin an exact version instead of resolving to the latest tag.
3. --agent claude-code is the target agent. Omit this flag in a non-interactive run and gh defaults to github-copilot instead, which is easy to miss if you’re scripting installs for a different agent.
4. --scope user installs to your home directory instead of the current repo, so the skill is available to Claude Code across every project you open, not just the one you ran the command from.

Search, preview, update, and publish

Four more subcommands round out the surface, each with a real, documented example:

# find a skill when you don't know its exact name
gh skill search terraform

# read a skill's SKILL.md in your terminal before installing it
gh skill preview github/awesome-copilot documentation-writer

# check every installed skill for updates and apply them
gh skill update --all

# validate a skill you're building against the Agent Skills spec, without publishing yet
gh skill publish --dry-run

gh skill search runs against the GitHub Code Search API, matching your query against a skill’s name and description inside SKILL.md files; add --owner <name> to scope results to one organization. gh skill preview fetches and renders a skill’s SKILL.md without installing anything, useful for reading what a skill actually does before it touches your agent’s config. gh skill update compares each installed skill’s local tree SHA, stored in its own frontmatter, against the remote repository, and skips anything installed with --pin unless you also pass --unpin. gh skill publish checks a local skill’s frontmatter and naming against the Agent Skills spec before creating a GitHub release; --fix autocorrects what it can, stripping install metadata, for example, without publishing.

Pinning matters most for CI and provisioning scripts, where a moving tag could resolve to a different commit between runs. Covering when to reach for a tag versus a commit SHA is its own topic; for reproducible CI installs, see gh skill —pin: Tag vs Commit SHA, Which to Use.

Where this fits in GitHub CLI’s 2026 agent push

gh skill is one of ten changes covered in GitHub CLI’s 2026 agent-era expansion, the wider wave that also added gh discussion, sub-issue management, and gh agent-task between April and July 2026.

Reach for gh skill install the next time you’re setting up a new machine or onboarding a teammate onto an agent your team already standardized on. It replaces a clone-and-copy step that used to look different for every agent with one command that stays the same across all of them. Skip it for a one-off skill you’re only testing locally; a plain git clone into the right folder is still less typing than learning five new subcommands for something you’ll delete in an hour.

Browse more posts like this in the Dev Tools archive.

That difference only matters once pinning is worth doing at all, which usually means a CI pipeline or a provisioning script installing the same skill on every run, not a one-off skill you’re trying out locally on your own machine.

What --pin actually resolves to

Run without --pin, gh skill install resolves to the latest tagged release, falling back to the default branch’s HEAD if no tag exists. --pin overrides that resolution. GitHub’s manual for gh skill install states the mechanism plainly:

“The version is resolved as a git tag or commit SHA.”

Both of the following are documented, working commands, taken directly from GitHub’s own changelog announcement:

# Pin to a release tag
gh skill install github/awesome-copilot documentation-writer --pin v1.2.0

# Pin to a commit for maximum reproducibility
gh skill install github/awesome-copilot documentation-writer --pin abc123def

Both commands install the same skill from the same repository. The only difference is what --pin points at, and that’s exactly where the two options stop being interchangeable.

Why a tag is a mutable pointer

A git tag is a name attached to a commit, not the commit itself. By default, nothing stops a repository owner from deleting v1.2.0 and recreating it against a different commit, whether that’s an honest re-release, a compromised account, or a supply-chain attack. --pin v1.2.0 run today and the identical command run six months from now can resolve to different content, even though the flag and the value never changed on your end.

GitHub gives repo owners a way to close that gap. Its changelog describes gh skill publish offering to enable immutable releases:

“Enabling immutable releases, for example, means even if someone gets control of your repository they cannot change existing releases, so users installing via tag pinning are fully protected.”

That’s real protection, but notice whose decision it is. Enabling immutable releases is a setting the source repository turns on, not something the --pin flag or your own install command controls. The install command from the previous section doesn’t tell you whether github/awesome-copilot has that setting flipped on; nothing about the command line changes when it does.

Why a commit SHA can’t move

A commit SHA isn’t a label someone assigned; it’s computed from the commit’s own content: its tree, its parent, its author and message. Change any of that and the SHA changes with it. GitHub’s changelog calls this “content-addressed change detection,” and the same principle backs gh skill update’s own change checks: each installed skill’s git tree SHA gets recorded locally and compared against the remote, catching real content changes rather than just version bumps.

That same property is what makes a SHA a safe thing to automate against. Nobody can push a different commit that reuses abc123def and have gh skill install --pin abc123def silently fetch something else. The tradeoff is readability: a tag tells a human roughly what they’re getting at a glance, and a 7-to-40-character hex string doesn’t mean anything without looking up what it points to first.

Structural Comparison Matrix

What happens after you pin

Pinning doesn’t just change what gets installed once. It also changes how gh skill update treats that skill afterward, for either kind of value. GitHub’s manual is direct about it:

“Pinned skills (installed with --pin) are skipped with a notice. Use --unpin to clear the pinned version and include those skills in the update.”

# a skill installed with --pin gets a notice here, not an update
gh skill update --all

# clear every pin and let those skills update normally again
gh skill update --unpin

That skip behavior is identical for a tag pin and a SHA pin, which is worth stating plainly because it’s easy to assume otherwise: --unpin doesn’t care which kind of value you originally passed. What it doesn’t do is retroactively fix a tag-based install if the tag it resolved to at install time already pointed at compromised content. Pinning protects an already-installed skill from moving out from under you later. It doesn’t protect the moment of installation itself, and for a tag, that moment is exactly where the mutability risk lives.

Which one to reach for

Reach for --pin abc123def anywhere a script installs the skill without a person watching: CI, a provisioning step, an onboarding script that runs unattended on a new machine. The reproducibility guarantee comes from git’s own object model, not from trusting a repo’s settings or a person’s memory. Reach for --pin v1.2.0 for a skill you’re installing yourself, at your own keyboard, where a version tag is faster to read and a moved tag is something you’d likely notice going wrong in real time. This choice is one piece of gh skill’s broader install/manage/publish surface; see gh skill: Manage AI Agent Skills From GitHub CLI for the rest of that command group, and GitHub CLI’s 2026 agent-era expansion for how this fits the wider wave of changes gh shipped around it.

Browse more posts like this in the Dev Tools archive.

Quick Answer

GitHub CLI (gh) shipped a dense wave of changes between April and July 2026: new gh skill, gh discussion, and sub-issue commands, a PGP signing-key rotation, and two security-driven point releases fixing a real remote-code-execution bug and a terminal-injection issue spanning seven commands. This is the hub for a 10-part series covering every piece, not the separate GitHub Copilot CLI product. Update to at least v2.97.0 first, then work through the table below.

Why gh became more than an API wrapper

gh started as a terminal front end for the same actions the GitHub web UI already handled: open an issue, review a PR, check a workflow run. Between April and July 2026, that scope expanded in two directions at once, inside the same four-month window, without either direction being announced as a coordinated plan.

On the agent side, gh skill (2026-04-16) gave gh a first cross-agent command for installing, pinning, and publishing agent skills. gh agent-task extended that further, letting a terminal session kick off GitHub’s own asynchronous Copilot coding-agent runs. Neither of these is the separate GitHub Copilot CLI product (github/copilot-cli), which had its own unrelated general-availability release in February 2026 and a terminal-interface GA in June 2026. This guide is about the classic gh tool, the cli/cli project, not that product.

On the security side, two point releases landed within a month of each other and fixed real, dated vulnerabilities rather than theoretical ones. v2.96.0 patched a remote-code-execution path in gh codespace jupyter. v2.97.0 sanitized terminal escape sequences across seven separate commands. Neither was cosmetic, and both are reasons to check your installed version today rather than just read about the new commands below.

Structural Comparison Matrix

Every row is confirmed against gh’s own changelog entry, official manual page, or the relevant GHSA advisory for that release, not summarized from memory. Full mechanism, exact commands, and the fix live in each linked post below.

New command surfaces: skill, discussion, and issue hierarchy

gh skill is the biggest structural addition. The changelog puts the scope plainly:

“install, pin, search, update, and publish agent skills”

That is the full lifecycle, across Claude Code, GitHub Copilot, Cursor, Codex, Gemini CLI, and Antigravity, through one --agent flag rather than six separate per-tool workflows. Installing a skill from a repo looks like this:

gh skill install github/awesome-copilot documentation-writer --pin v1.2.0

Pinning matters more than it looks. A tag like v1.2.0 can be reassigned to point at a different commit unless the repo owner has Immutable Release turned on, so a CI pipeline pinned to a tag isn’t guaranteed reproducible. Pinning to a commit SHA instead is the option that’s actually reproducible:

gh skill install github/awesome-copilot documentation-writer --pin abc123def

That distinction is documented directly in gh’s own manual for gh skill install, not buried in a GitHub issue thread.

Two months later, v2.94.0 (2026-06-10) shipped two more command groups in the same release. gh discussion (list, view, create, edit, comment) gave GitHub Discussions the same terminal parity issues and PRs already had, so working with a Discussion no longer means falling back to raw gh api calls against the Discussions GraphQL schema. The same release added issue types, sub-issues, and cross-issue dependencies to gh issue, through --parent, --set-parent, and --remove-parent flags, turning issue hierarchy from a GitHub.com-only feature into something a script can read and change directly.

gh agent-task (create, view, list) is the newest of the group and still labeled preview. Per its own manual page, a task is what the command actually operates on:

“a task is a GitHub issue that triggers automated code changes from natural language instructions”

That makes gh agent-task a terminal driver for the same class of automation GitHub’s Actions platform tackled from a different angle around the same time. See Set Up GitHub Agentic Workflows in Actions for that Actions-side surface, a separate product from gh agent-task covered here, built on Markdown-to-YAML compilation instead of a CLI-driven task.

Security: two point releases and a key rotation worth acting on

v2.96.0 (2026-07-02) fixed a real remote-code-execution path. gh codespace jupyter opened a JupyterLab URL handed to it by the Codespace itself, without checking that the URL actually pointed at a loopback address. The advisory states the risk plainly:

“connecting to a malicious Codespace via gh codespace jupyter can allow command execution”

A crafted vscode:// URL from inside a malicious or compromised Codespace could hand off command execution to the victim’s own machine, tracked as GHSA-8cg3-r6g9-fpg2. The same release changed gh release download to work against public repos without requiring authentication, matching how gh extension install already behaved, useful for a CI pipeline that was carrying a token for no real access-control reason.

Four weeks later, v2.97.0 (2026-07-31) fixed a single terminal escape-sequence injection issue, tracked as GHSA-3m3g-3wcr-px46, that spanned seven separate commands. (v2.97.0’s release notes also fixed three other, unrelated advisories that same day, a URL-path-escaping bug, an auth-token leak, and an attestation-verify bypass, worth naming so “four” isn’t mistaken for the count of terminal-injection bugs specifically.) Seven commands printed content someone else controlled, a gist body, an API response, a PR diff, agent-task output, without stripping raw terminal escape sequences first: gh gist view, gh api, gh pr diff, gh release download --output -, gh codespace logs, gh skills preview, and gh agent-task view/create. Any of those run against a malicious repo, gist, or PR could manipulate the victim’s own terminal, not just print unwanted text.

Underneath both releases sits a smaller but still real change: a PGP signing-key rotation for gh’s Linux package repos, shipped 2026-04-08. GitHub published a dual-key keyring, the current key alongside its replacement, so an apt/yum-style install or update during the rotation window doesn’t fail on a signature mismatch.

The 10 pieces of this guide

This hub is the starting point for a 10-part series. All ten pieces are published below.

1. gh skill: Manage AI Agent Skills From GitHub CLI: the command itself, cross-agent install/manage/publish.
2. gh skill —pin: Tag vs Commit SHA, Which to Use: version pinning mechanics.
3. gh discussion: GitHub Discussions in Your Terminal: the new Discussions command group.
4. Manage GitHub Sub-Issues and Dependencies via gh CLI: issue hierarchy flags.
5. Update gh CLI Now: Codespace Jupyter RCE Fixed: the v2.96.0 security fix.
6. gh CLI 2.97.0 Fixes Terminal Injection in 7 Commands: the v2.97.0 security fixes.
7. gh release download No Longer Needs Auth (Public Repos): the auth-behavior change.
8. gh CLI’s New PGP Signing Key for Linux Packages: the key rotation.
9. gh agent-task: Run Copilot Coding Sessions From gh: driving Copilot coding agent from the CLI.
10. How GitHub CLI Became an AI-Agent Control Surface: closing synthesis.

Update your own gh install before you rely on any of this

None of the commands above help if the copy of gh on your machine predates them. Check what you’re actually running first:

gh --version

gh has no built-in self-update command, so update through whatever installed it in the first place: brew upgrade gh on macOS, apt update && apt install gh on Debian/Ubuntu, scoop update gh on Windows, or a fresh binary from cli.github.com if you installed manually. If an apt/yum-style update fails on a signature error, the April 2026 key rotation is the first thing worth checking, not a broken mirror. Anything before v2.94.0 is missing gh discussion and sub-issues entirely. Anything before v2.97.0 is missing both security fixes.

Five months of changelog entries don’t usually deserve one guide. This wave does, because it’s the same tool becoming two different things at once: a control surface for AI-agent tooling, and a CLI that needed two security-driven releases in one month. Update first, then decide which of the ten pieces above actually changes your own workflow.

Browse more coverage like this in the Dev Tools archive.

Quick Answer

Update gh to v2.97.0 or later regardless of which commands you use; two of this wave’s six changes are security fixes, not features. Then adopt gh skill and gh agent-task if you drive AI agents from a terminal, and gh discussion plus the sub-issue flags if you manage repo hierarchy or Discussions by script.

Six changes, two directions, one four-month window

Between April and July 2026, gh shipped four new command groups and two security-driven point releases. Read as separate changelog entries, each looks routine: a new command here, a patched CVE there. Read together, against real dates, they point the same direction twice.

gh skill (2026-04-16) and gh agent-task (still preview) give gh a terminal surface for AI-agent tooling: installing skills across more than 30 agents, and driving GitHub’s own asynchronous Copilot coding-agent runs. gh discussion and the sub-issue and dependency flags on gh issue, both shipped in the same v2.94.0 release on 2026-06-10, give gh a terminal surface for repo hierarchy that used to live only in the web UI or a handwritten GraphQL call. Underneath both threads, v2.96.0 and v2.97.0 closed a real remote-code-execution path and a real terminal-injection bug, hardening the same command surface that now touches more content it didn’t write itself: agent output, someone else’s PR diff, someone else’s gist.

That’s the actual synthesis, not a single command worth learning. gh spent four months becoming a control surface for two things GitHub used to gate behind a browser: an AI agent’s own tooling, and a repository’s own issue tree.

Structural Comparison Matrix

Every row above is sourced from the cluster post that actually researched it, linked below, not re-derived here.

Thread one: gh becomes agent tooling

gh skill gave gh its first real lifecycle for AI-agent skills: install, preview, search, update, and publish, all behind one --agent flag that recognizes more than 30 coding agents by name. gh skill: Manage AI Agent Skills From GitHub CLI covers the full command set and the tag-versus-commit-SHA pinning distinction that matters for reproducible CI installs.

gh agent-task extends the same thread further. Its own manual page states plainly what it operates on:

“a task is a GitHub issue that triggers automated code changes from natural language instructions”

That makes it a terminal driver for GitHub’s own Copilot coding agent, still labeled preview, and one of the newest command groups this wave shipped. No dedicated cluster post exists for it yet in this series, so this synthesis leans on that manual definition and the hub’s own description rather than research this article didn’t do. It’s worth distinguishing from a separate GitHub product covering similar ground from a different angle: see the FAQ below on how it differs from GitHub Agentic Workflows in Actions.

Thread two: gh becomes a repo-hierarchy client

gh discussion and the sub-issue and dependency flags on gh issue landed in the same v2.94.0 release, 2026-06-10, closing two unrelated gaps at once. Neither depends on the other; they shipped together because both moved a GitHub.com-only feature into a scriptable terminal command.

gh discussion: GitHub Discussions in Your Terminal covers list, view, create, edit, and comment, plus what the command group still can’t do (closing, locking, or deleting a discussion still needs raw gh api graphql). Manage GitHub Sub-Issues and Dependencies via gh CLI covers --parent, --add-sub-issue, and --add-blocked-by, and one real correction worth repeating here rather than re-deriving: GitHub’s own changelog for that release names a --set-parent flag that does not exist in the shipped CLI. Only --parent and --remove-parent are registered; --parent handles both the first link and any later change.

The security cost of touching more untrusted content

A command surface that reads more content it didn’t write, gist files, PR diffs, agent-task output, is also a command surface with more to sanitize before printing it to your screen. Both of this wave’s security releases fall out of that same expansion.

v2.96.0 (2026-07-02) closed a real remote-code-execution path in gh codespace jupyter: a crafted vscode:// URL from inside a malicious or compromised Codespace could hand off command execution to the victim’s own machine, tracked as GHSA-8cg3-r6g9-fpg2. Full detail in Update gh CLI Now: Codespace Jupyter RCE Fixed.

v2.97.0 (2026-07-31) is worth one correction here, because a single changelog line invites a conflation that isn’t accurate. GitHub’s own release notes for that version list four separate security advisories fixed the same day, not four terminal-injection bugs. Only one of them, GHSA-3m3g-3wcr-px46, is the terminal-injection issue, and it touches seven separate command paths, not four, gh api and gh pr diff among them, both gh agent-task subcommands included. The other three advisories fixed that same day cover an unrelated URL-path-escaping bug, a partial auth-token leak in gh auth status, and a regex-escaping bypass in gh attestation verify, three different bug classes in three different commands. See gh CLI 2.97.0 Fixes Terminal Injection in 7 Commands for the full seven-command list and the fix itself.

Two of the seven sanitized commands, gh agent-task view and gh agent-task create, belong to the same agent-tooling thread this post opened with. That’s not a coincidence worth glossing over: the newest, least-tested command surface is also the one that needed a security patch in its first few months.

What’s still preview, and what already shipped stable

Not every command in this wave carries the same production confidence. GitHub’s own gh manual states the same caveat for two of the four, word for word except for the one swapped noun:

“Working with agent skills in the GitHub CLI is in preview and subject to change without notice.”

Swap “agent skills” for “discussions” and that’s the exact sentence covering gh discussion too. gh agent-task carries its own preview label directly on its manual page, a shorter but equally direct signal.

Issue hierarchy is the exception. The --parent, --add-sub-issue, and --add-blocked-by flags shipped in v2.94.0 without a preview caveat attached anywhere in GitHub’s changelog or gh’s own docs. If you’re choosing where to script first, that’s a real, sourced reason to start with the hierarchy flags over the other three.

This is the tenth and closing post in a 10-part series; it earns its place the same way Same Prompt, Different Bill closes this site’s LLM pricing series, tying several individually-dated changes into one decision instead of adding an eleventh isolated fact. See GitHub CLI’s 2026 Agent-Era Expansion for the hub linking all ten pieces.

Update first, then adopt selectively

Check your version before anything else:

gh --version

Anything before v2.97.0 is missing a real security fix, not a feature. Update through whatever channel installed gh: brew upgrade gh, apt update && apt install gh, scoop update gh, or a fresh binary from cli.github.com. Past that baseline, adopt selectively rather than all at once. gh skill and gh agent-task earn their place the moment you’re managing AI-agent tooling across more than one machine or one agent. gh discussion and the sub-issue flags earn theirs the moment a script needs to read or change something that used to require a browser tab. None of the four demand adoption on day one, but the pattern behind them does demand attention: gh isn’t just tracking GitHub’s web features anymore, it’s becoming the terminal’s own control point for them, and a version bump in this series is worth reading before you skip it.

Browse more coverage like this in the Dev Tools archive.

Quick Answer

GitHub’s promotional AI Credits allowances, granted when Premium Request Units retired June 1, 2026, revert to standard levels September 1: Business drops 3,000 to 1,900 credits/user/month, Enterprise 7,000 to 3,900. Check usage and set budgets before then: by default, Copilot doesn’t halt at zero, it bills metered usage automatically and uncapped.

Why a promotional number felt like the real one

GitHub Copilot changed its billing model twice in three months, and it’s easy to conflate the two changes. On June 1, 2026, GitHub retired Premium Request Units (PRU) in favor of AI Credits for every monthly-billed Pro, Pro+, Business, and Enterprise plan. At that same cutover, Business and Enterprise orgs got a promotional allowance, more credits than the tier’s standard allotment, to cushion the transition.

That promotional number was never the permanent one. It reverts to each tier’s real allotment on September 1, 2026. For a Business org running close to its promotional 3,000-credit ceiling, that’s not a policy footnote. It’s a drop to 1,900 credits/user/month, roughly a third less headroom overnight. Enterprise falls further, from 7,000 down to 3,900, a cut of about 44%. Nothing about the billing mechanism itself changes that day. Only the number does.

Structural Comparison Matrix

Every figure in that table comes from GitHub’s own living documentation or its billing changelog, not aggregated secondary pricing trackers. The one exception is the “as much as 27x” characterization of the annual-plan multiplier table’s extremes, further down, that’s a third-party reading of the table, not GitHub’s own wording, and it’s labeled as such where it appears.

From flat multipliers to real per-token pricing

Premium Request Units billed every premium model call against a flat multiplier, a request against GPT-4-class models cost roughly the same number of units regardless of how long the prompt or response actually was. AI Credits replaced that on June 1, 2026, with 1 credit equal to $0.01, priced per-token and per-model: input tokens, output tokens, and cache-write tokens each carry their own rate, and that rate differs by model, per GitHub’s own models-and-pricing documentation.

That’s the same shift this site already covered for GPT, Claude, and Gemini in the 2026 LLM Token & Pricing Reset hub: real per-token, per-model economics replacing a flatter, coarser unit. Copilot’s version just arrived wearing GitHub’s own billing vocabulary, and it means a long, context-heavy prompt against a frontier model now costs visibly more credits than a short one against a lighter model, a distinction PRU’s flat multiplier never captured.

Why Agent Mode changes the math

A single-turn chat question in Copilot burns one round of tokens. Agent Mode’s read-file, edit, run-tests, re-read loop burns tokens on every step of that loop, not once per user message. GitHub’s own research, as relayed by third-party coverage, puts the difference at roughly 1,000 times more tokens consumed than a single-turn chat query for a comparable task, a figure worth treating as reported rather than a direct GitHub quote.

That multiple shows up in real reported bills: $29 jumping to $750 in a month, $50 jumping to $3,000. A per-message mental model of Copilot cost doesn’t predict that jump, because Agent Mode isn’t spending per message, it’s spending per step. Choosing a lighter model for routine steps, and reserving a frontier model for the step that actually needs it, is a real lever now that credits price by model instead of by flat multiplier. This site’s own prompting guide for AI coding assistants covers the habits, working in checkpoints, specific constraints, that keep an agent loop from running longer than the task needs.

Annual plans are on a different, quieter clock

Not every Copilot subscriber faces the September 1 cliff. Anyone on an annual-billed plan wasn’t migrated to AI Credits on June 1; annual plans stayed on the legacy PRU and model-multiplier system GitHub has run since premium requests first launched. GitHub revised that multiplier table itself on the same June 1 date, and third-party analysis of the table’s extremes describes some models’ multipliers rising as much as 27x, a characterization worth reading directly rather than secondhand, since it’s paraphrased from that analysis, not GitHub’s own phrasing.

Annual subscribers don’t hit a credit cliff on September 1. They already absorbed a different, quieter one back in June, and it doesn’t resolve until the plan comes up for renewal onto the Credits system.

Budgets, and what actually happens at zero

GitHub gives admins a real lever before September 1 makes the decision for them, but it’s worth stating the default plainly first, because it runs backward from what most admins assume. GitHub’s own docs on usage-based billing for organizations and enterprises say it directly: additional usage is enabled by default for organizations and enterprises. An org that has never touched its AI Controls settings, never set a budget, and never disabled anything keeps billing metered AI credit usage the moment its shared pool empties, for as long as usage continues. There’s no default $0 budget protecting anyone; GitHub retired that for enterprise and team accounts on 2025-12-02, and the Credits system that replaced Premium Request Units on June 1, 2026 doesn’t carry it forward.

Budgets can be scoped to an organization, a cost center, or an individual user, per GitHub’s own budgets documentation. Org- and cost-center-level budgets carry a single toggle, “Stop usage when budget limit is reached”: switch it on and metered usage is blocked outright once the limit hits, leave it off (its own default) and admins get a notification while charges keep accruing past the limit instead. A universal user-level budget doesn’t get that choice; it always enforces a hard stop, no toggle, no notify-only option.

GitHub Community discussions #197557, #197605, and #197089 capture real admins working this out the hard way, including one enterprise admin describing a setting that used to read “$0 budget” and block overage automatically now showing “No Usage Limit” instead. The full exhaustion-behavior breakdown in this series covers the request-evaluation order and every configuration state in detail.

The 10 pieces of this guide

This hub is the starting point for a 10-part series on GitHub Copilot’s AI Credits system and the September 1 cliff.

1. Check Your Copilot AI Credits Usage Before Sept 1: how to view real usage via the new dashboards and API before the cliff hits.
2. How GitHub Copilot AI Credits Are Actually Priced: the 1 credit = $0.01 per-token, per-model mechanics.
3. GitHub Copilot’s PRU to AI Credits Migration, Explained: what the June 1 cutover actually changed.
4. Annual Copilot Plans: Model Multipliers Just Spiked: the separate legacy-multiplier mechanism for annual subscribers.
5. Setting Copilot Budget Controls Before the Sept Cliff: org, cost-center, and per-user budget configuration.
6. What Happens When GitHub Copilot Credits Run Out: default exhaustion behavior, in detail.
7. Why Copilot Agent Mode Burns Through Credits So Fast: Agent Mode’s outsized token consumption.
8. GitHub Copilot Plans Compared by AI Credits, Not Price: tier-by-tier allotment comparison, not just sticker price.
9. Pick Cheaper Copilot Models to Stretch Your Credits: model-selection as a real cost strategy.
10. What to Do Before GitHub Copilot’s Sept 1 Credit Cliff: the closing synthesis and checklist.

What to do before September 1

Three real levers exist right now, not hypothetical advice for later. Check actual usage first: GitHub shipped a per-cycle AI credits view (2026-07-20), a per-user usage-metrics API field (2026-06-19), and an org-level usage metrics impact dashboard (2026-07-22). None of the three existed before this year, so an org running Copilot since the PRU era may genuinely be checking real per-user numbers for the first time.

Set a budget with intent, not as an afterthought. Turn on “Stop usage when budget limit is reached” for a scope that must never lapse, and leave it off for one that should notify instead of blocking a shipping deadline. Apply it at whichever level, org, cost-center, or per-user, matches how the org actually assigns cost accountability. Then route routine agent steps to a cheaper model before September 1 makes the same credit pool feel smaller than it did in July. Credits price by model instead of by flat multiplier, so model choice is a real cost lever PRU never gave you.

None of this requires panic before September 1, but it does require one real decision: whether your org’s current usage pattern fits inside the standard allotment, or whether it’s been quietly leaning on the promotional cushion without anyone noticing. Check the actual per-user numbers before that date, not after next month’s invoice tells you the hard way, since the default here bills uncapped rather than stopping on its own.

Browse more coverage like this in the AI Productivity archive.

Quick Answer

GitHub Copilot’s AI Credits price real token counts, not flat per-request units. Each model charges separately for input tokens, cached input tokens, and (on some models) cache-write tokens, plus output tokens, then the dollar total converts to credits at a fixed 1 credit = $0.01. Model choice and context size now change your cost, not just your request count.

Why “per request” was never the same as “per token”

Before June 1, 2026, a Copilot interaction was billed as a Premium Request Unit. Under that system, GitHub assigned every supported model a fixed multiplier tied to how heavy that model was to run, then subtracted that many units from your monthly allowance whenever you used it. A single chat call to Claude Opus 4.7 cost 27 premium requests. A call to GPT-5.5 cost 57. Neither number moved whether the prompt was one line or a whole file’s worth of context, because the multiplier attaches to the request, not to anything measured inside it.

AI Credits replaced that system for every monthly-billed Pro, Pro+, Business, and Enterprise plan. The unit is no longer the request. It’s the token, priced per model, then converted to a dollar figure at a fixed rate: 1 AI credit equals $0.01 USD, confirmed directly on GitHub’s own models-and-pricing documentation. That single conversion rate is the same across every plan; what a request actually costs depends entirely on the model and the tokens it consumes.

Structural Comparison Matrix

The 10% cached-input figure and the 1.25x cache-write figure aren’t stated as round numbers anywhere in GitHub’s docs. They’re a pattern this post found by checking every row of the live pricing table that includes both prices, and it held consistently across every one checked, from GPT-5 mini up through Claude Opus 4.8. The next two sections show the arithmetic.

The real pricing table, and how to read it

GitHub organizes its per-model pricing into separate tables by provider, OpenAI, Anthropic, Google, Microsoft, xAI, Moonshot AI, and GitHub’s own fine-tuned models, each with the same shape: a model name, a release status, a category (Lightweight, Versatile, or Powerful), and up to four price columns covering input, cached input, cache write, and output. A handful of models also carry a Tier column, splitting Default pricing from a higher Long context rate past a stated token threshold.

Here’s a representative snapshot, quoted directly from GitHub’s live pricing table on 2026-08-19:

Model	Category	Input	Cached input	Cache write	Output
GPT-5 mini	Lightweight	$0.25	$0.025	Not applicable	$2.00
GPT-5.4 (default tier)	Versatile	$2.50	$0.25	Not applicable	$15.00
GPT-5.6 Sol (default tier)	Powerful	$5.00	$0.50	$6.25	$30.00
Claude Haiku 4.5	Versatile	$1.00	$0.10	$1.25	$5.00
Claude Opus 4.8	Powerful	$5.00	$0.50	$6.25	$25.00
Gemini 3.6 Flash	Versatile	$0.75	$0.075	n/a	$3.75

All rates above are per 1 million tokens. Gemini 3.6 Flash’s row is promotional pricing in effect through December 31, 2026, per GitHub’s own table, not a permanent rate. This is a snapshot, not a live feed either way. GitHub’s table changes as models and rates change, so treat the columns and the pattern as the durable part and check the live table for the current numbers before budgeting against them.

A worked example: the same prompt, two different models

Take a Copilot Chat request that sends 100,000 input tokens (a decent chunk of repo context) and gets back 20,000 output tokens, with nothing served from cache. Here’s what that costs on two models from the table above.

GPT-5 mini (Lightweight, $0.25 input / $2.00 output per 1M tokens):

1. Input: 100,000 tokens x $0.25 / 1,000,000 = $0.025
2. Output: 20,000 tokens x $2.00 / 1,000,000 = $0.04
3. Total: $0.025 + $0.04 = $0.065
4. Credits: $0.065 / $0.01 = 6.5 credits

Claude Opus 4.8 (Powerful, $5.00 input / $25.00 output per 1M tokens):

1. Input: 100,000 tokens x $5.00 / 1,000,000 = $0.50
2. Output: 20,000 tokens x $25.00 / 1,000,000 = $0.50
3. Total: $0.50 + $0.50 = $1.00
4. Credits: $1.00 / $0.01 = 100 credits

Same prompt, same token counts, roughly 15 times more credits on the more capable model. That gap is the whole point of moving to per-token pricing: a flat PRU multiplier could only tell you a model costs “more,” never how much more a specific request actually spent.

Cached tokens cost less, cache writes cost more

The Structural Comparison Matrix above flags a pattern worth showing directly. Take Claude Opus 4.8 again, this time for the same 100,000 tokens handled three different ways.

A fresh, uncached input call: 100,000 tokens x $5.00 / 1,000,000 = $0.50, or 50 credits.

Writing that same context to cache for the first time: 100,000 tokens x $6.25 / 1,000,000 = $0.625, or 62.5 credits, a 25% premium over the plain input rate.

Reading that context back from cache on a later call: 100,000 tokens x $0.50 / 1,000,000 = $0.05, or 5 credits, one tenth of the fresh-input cost.

The first cache write costs more than just sending the tokens fresh would have. Every reuse after that costs a tenth as much. A workflow that repeats the same large context across several calls, an agent looping over the same file, a chat session that keeps referencing the same repo, comes out well ahead by writing to cache once and reading from it repeatedly, instead of resending the same tokens as plain input every time.

Crossing the long-context threshold changes the rate too

Some models in the table carry a second lever: a Tier column that splits Default pricing from a higher Long context rate once your input crosses a stated threshold. GPT-5.4 is a clean example. Its Default tier applies at or below 272,000 input tokens, at $2.50 input and $15.00 output per million tokens. Its Long context tier applies above 272,000 input tokens, at $5.00 input and $22.50 output, exactly double the input rate and 1.5x the output rate.

GitHub’s table presents Default and Long context as two separate rows with two separate rates, not a blended formula, so a request appears to be billed against whichever tier its input falls into rather than only the tokens past the line. That reading isn’t spelled out explicitly in GitHub’s own pricing docs, so treat it as the most reasonable interpretation of how the table is structured, not a directly confirmed billing mechanic. Either way, the practical takeaway holds: a prompt that quietly grows past a model’s context threshold can jump to a meaningfully higher per-token rate, on top of simply containing more tokens to price.

Model choice, not request count, is now the lever

The mental model that mattered under Premium Request Units, count how many requests you’re sending, doesn’t transfer to AI Credits. What matters now is which model answers the request and how many tokens that answer actually took, input, cached, written to cache, and generated. The worked example above shows a 15x swing between two models on the exact same prompt, computed directly from GitHub’s published rates, not estimated.

That’s the same structural shift this site already covered for GPT, Claude, and Gemini’s own pricing in Same Prompt, Different Bill and The 2026 LLM Token & Pricing Reset: flat, coarse units giving way to real per-token, per-model economics that a reader actually has to compute rather than just look up. Copilot’s version arrived a few months later, wearing GitHub’s own credit vocabulary, but the underlying math is the same industry pattern. Before the standard credit allowance becomes the only allowance your org has to work with, check which models your default routing actually sends requests to, since that choice now moves your bill more than your request count ever did.

Browse more coverage like this in the AI Productivity archive, or start from GitHub Copilot’s AI Credits Cliff hub for the full reversion story.

Quick Answer

GitHub Copilot budgets have one real lever: a toggle named “Stop usage when budget limit is reached,” available on organization-, cost-center-, and enterprise-scoped budgets. Turn it on to hard-block metered usage at the limit; leave it off and usage keeps running up charges past the limit with only a notification sent. Universal and individual per-user budgets skip the toggle entirely and always hard-stop.

Knowing your usage, covered in the previous post in this series, tells you where you stand. It doesn’t stop anything. A budget is the piece that actually enforces a limit, and GitHub gives admins real configuration steps to take before the September 1, 2026 promotional-allowance cliff drops Business seats from 3,000 to 1,900 credits and Enterprise seats from 7,000 to 3,900.

The toggle has one name, and it isn’t optional twice

An earlier pass at this topic assumed budget enforcement came in two named modes, something like “stop” and “limit,” as if an admin picked between two enforcement strategies. That’s not what GitHub’s live documentation shows. There is one toggle, named exactly “Stop usage when budget limit is reached,” and it’s a binary on/off, not a choice between two named modes.

GitHub’s budgets concepts page states the toggle’s effect plainly: switch it on and the user is blocked once the limit hits; leave it off and spending keeps running past the limit uncapped, with only a notification to show for it. That’s the entire mechanism. No separate “limit” mode sits alongside it for Copilot AI credits.

Universal and individual per-user budgets don’t get a choice at all:

User-level budgets always enforce a hard stop and do not have this setting.

That line is GitHub’s own, from the same budgets concepts page. The getting-started tutorial describes the same rule from the setup side: a per-user budget skips the toggle step entirely, because it hard-stops automatically no matter what. A per-user budget is the one scope where GitHub removes the choice, rather than defaulting it one way.

Structural Comparison Matrix

Every cell above comes from GitHub’s budgets concepts documentation and GitHub’s Budgets REST API reference, not a secondary summary of either.

Step 1: set the universal user-level budget first

GitHub’s own getting-started tutorial calls the universal user-level budget (ULB) “the single most important control.” That one setting puts a ceiling on what any individual can spend in a cycle, and it kicks in automatically for every licensed user the moment it’s saved, no per-user setup required.

Set it above the per-license value, not below. GitHub’s optimizing-budget-configuration guidance is specific about why: Copilot Business seats run $19/user/month and Enterprise seats run $39/user/month, and the ULB needs headroom above that figure for credit pooling to work at all. Set it at or below the per-license value and a light user’s unused credits can’t cover a heavier user’s overage, which is the whole point of pooling AI credits across a seat pool instead of hard-capping each person individually.

This is the one budget scope with no toggle to think about. Set the amount, and it hard-stops that user’s metered usage the moment they hit it.

Step 2: override for real power users

A single flat ULB doesn’t fit every user pattern. Someone running Agent Mode loops all day burns credits at a different rate than someone using single-turn chat occasionally, and a ULB sized for the average user blocks the heavy user constantly.

GitHub’s tutorial calls this out as its own step: pull the usage dashboard covered in the previous post in this series, identify the heaviest consumers, and set an individual user-level budget override for each. An override takes precedence over the universal default for that one user, letting an admin raise the ceiling for a known power user without loosening it for everyone.

Step 3: set org, cost-center, or enterprise budgets, and flip the toggle deliberately

This is the scope where the real decision lives. GitHub’s Budget scope options in the billing UI are Enterprise, Organization, Cost center, and Users, per GitHub’s own setup instructions. Any of the first three, enterprise, organization, or cost center, carries a “Stop usage when budget limit is reached” checkbox you can switch on or off.

The configuration path, per GitHub’s own steps: from Billing & licensing in the enterprise or organization settings, open Budgets and alerts, click New budget, choose a Budget Type of Bundled AI credits budget to cover Copilot’s credits specifically, set the Budget scope, enter the Budget amount, and decide the toggle before saving. Set alert thresholds too, GitHub fires notifications at 75%, 90%, and 100% of the configured amount regardless of the toggle state.

Turning the toggle on isn’t automatically the right call everywhere. A cost center running a shipping-critical team’s Copilot access might reasonably leave it off and eat the notification, if a mid-sprint hard block costs more than the overage would. A cost center with a fixed departmental budget that genuinely can’t flex probably wants it on. GitHub’s own optimizing guidance frames this as a deliberate choice tied to how the org actually assigns cost accountability, not a default to leave untouched.

Configuring the same budget through the API

Everything in the UI maps to GitHub’s Budgets REST API, which reached general availability on 2026-06-04 per GitHub’s own changelog. For a repeatable rollout across many cost centers, that’s the faster path than clicking through the UI once per team.

A per-user AI credits budget, hard-stop required, looks like this against POST /enterprises/{enterprise}/settings/billing/budgets:

{
  "budget_amount": 30,
  "prevent_further_usage": true,
  "budget_scope": "user",
  "budget_entity_name": "",
  "budget_type": "BundlePricing",
  "budget_product_sku": "ai_credits",
  "budget_alerting": {
    "will_alert": false,
    "alert_recipients": []
  },
  "user": "<github-username>"
}

An organization-scoped budget with the toggle deliberately left off, notify-only, looks nearly identical, minus the user field and with prevent_further_usage set to false:

{
  "budget_amount": 5000,
  "prevent_further_usage": false,
  "budget_scope": "organization",
  "budget_entity_name": "<org-login>",
  "budget_type": "BundlePricing",
  "budget_product_sku": "ai_credits",
  "budget_alerting": {
    "will_alert": true,
    "alert_recipients": ["<admin-username>"]
  }
}

budget_type: "BundlePricing" paired with budget_product_sku: "ai_credits" is what scopes either payload to Copilot’s AI credits specifically, covering the pooled credit spend rather than a single product SKU like Actions minutes. Every field name and requirement above is verified against GitHub’s Budgets REST API reference, current as of this writing; budget_entity_name for a cost-center-scoped budget follows the same pattern as the organization example, the cost center’s own name, though GitHub’s reference doesn’t spell out an exact ID format for that scope the way it does for user.

Step 4: monitor, don’t set and forget

GitHub’s own tutorial ends its walkthrough with monitoring, not configuration, as the last step: check the usage dashboard monthly for blocked users, unexpected metered charges beyond what a budget was sized for, and whether the pool is actually distributing the way it was designed to. A budget sized correctly in July against the promotional 3,000-credit Business ceiling is sized wrong in September against the standard 1,900-credit one, without anyone changing a single setting.

That’s the real reason this step exists as its own item and not a footnote. The September 1 revert doesn’t touch the budget configuration itself. It shrinks the pool the configuration is measured against, so a ULB or cost-center limit that looked generous in August can start blocking real work in September if nobody revisits it.

Set the budget before the pool shrinks under it

The universal user-level budget is the one non-negotiable step, set it above the per-license value or pooling doesn’t function. Everything past that is a real judgment call: raise it for identified power users, decide deliberately whether each org or cost-center budget should hard-block or just notify, and revisit the numbers once the September 1 reversion changes what “generous” actually means.

Skip this step and the default behavior still applies, premium features halt once the shared pool runs dry, assuming usage-based billing was never turned on in the first place. For what actually happens at that point, and what changes if usage-based billing is already on, see what happens when GitHub Copilot credits run out.

Browse more coverage like this in the AI Productivity archive, or start from GitHub Copilot’s AI Credits Cliff hub for the full picture.

Quick Answer

GitHub Copilot’s six plans don’t scale credits proportionally with price. Pro, Pro+, and Max each deliver more credits per dollar moving up the ladder, 150, about 180, and 200. Business and Enterprise, after the September 1 revert, both settle at 100, near half of what a same-priced Pro+ seat gets. Compare the ratio, not the sticker price.

Why upgrading a tier doesn’t mean proportionally more credits

Every Copilot plan sets its own price and its own monthly AI credit allotment, both published on GitHub’s own plans page. Nothing forces those two numbers to move together. A buyer comparing Pro against Business, or Pro+ against Enterprise, is really comparing two independent variables that GitHub priced separately for each tier, not one number scaled up.

That matters more than it sounds like it should. The instinct is to assume a $39/month plan buys roughly four times what a $10/month plan buys, since the price is four times higher. Run the actual figures from GitHub’s individual-plans billing documentation and its organization and enterprise billing documentation, and that instinct breaks in both directions.

Structural Comparison Matrix

Here’s every monthly-billed Copilot plan: its price, its published AI credit allotment, and what that allotment is worth at GitHub’s fixed 1 credit = $0.01 conversion rate, the same mechanism covered in more depth here. Business and Enterprise are shown at their standard, permanent allotment, the number that applies from September 1, 2026, onward, since that’s the figure that persists once the promotional cushion runs out.

Every figure above was checked directly against GitHub’s own plan and billing documentation on 2026-08-19, not carried over from an earlier summary. Business and Enterprise’s promotional allowances, 3,000 and 7,000 credits/user/month, in effect until September 1, 2026, are covered in their own section below rather than folded into this table, since they’re temporary.

GitHub’s individual-plans documentation doesn’t publish a specific figure for Free’s credits the way it does for the three paid tiers. Quoted directly from that page:

Copilot Free and Copilot Student both have an allowance of AI credits and access to models through auto model selection only.

The only quantified number attached to Free in that same documentation is 2,000 code completions a month, not a base-plus-flex credit breakdown. Free was never part of the paid credit system the September cliff touches, and there’s no published free-tier number to run the same per-dollar math against.

The same $39 buys two different credit pools

Pick the two plans that share an identical price and the gap stops being abstract. Copilot Pro+ costs $39 a month and includes 7,000 AI credits. Copilot Enterprise costs $39 per seat per month too, and once the promotional period ends on September 1, 2026, it includes 3,900.

Same price, same $0.01-per-credit conversion, two very different pools. An Enterprise seat’s standard allotment works out to 55.7% of what an individual Pro+ subscriber gets for the identical monthly price. That’s not a rounding difference. It’s most of a credit pool disappearing at the same price point.

It wasn’t always that far apart. Before September 1, 2026, GitHub’s promotional Enterprise allowance is also 7,000 credits/user/month, the exact same number Pro+ gets. Right now, an Enterprise seat and a Pro+ subscription buy identical credit pools at an identical price. The September 1 revert is what breaks that parity, not a price change on either side.

Individual plans get more credit-dense as you go up

The three individual plans move the opposite direction from Business and Enterprise. Pro, at $10/month, delivers 1,500 credits, exactly 150 per dollar spent. Pro+ raises that to 179.5 per dollar. Max, the newest and most expensive individual tier at $100/month with 20,000 credits, hits exactly 200 credits per dollar, the highest rate on the entire lineup.

Put another way: Max costs 10 times what Pro costs, but its credit pool is 13.3 times larger, 20,000 against 1,500. Upgrading from Pro to Max isn’t proportional. It’s a better deal per dollar, not a worse one, which is the opposite of what happens crossing from Pro+ into a same-priced Enterprise seat.

That gap didn’t come from June 1, 2026’s shift away from flat Premium Request Unit multipliers either. It’s simply how GitHub priced the three individual tiers against each other once real per-token, per-model billing replaced the old flat-multiplier system.

Team plans, before and after the September 1 revert

Business and Enterprise don’t scale against each other the way Pro, Pro+, and Max do, but they scale consistently against themselves. Both sit at exactly 100 credits per dollar on their standard, post-reversion allotment: Business at 1,900 credits for $19, Enterprise at 3,900 for $39. Double the price gets you double the credits, precisely.

The promotional numbers, in effect through September 1, 2026, tell a different story. Business’s promotional 3,000 credits/user/month works out to 157.9 credits per dollar. Enterprise’s promotional 7,000 works out to 179.5, identical to Pro+‘s rate, for the reason covered above. Both team tiers are, for now, priced closer to the individual plans than they will be once September arrives.

GitHub’s own organization and enterprise billing documentation describes the change as a scheduled reversion: once the promotional window closes, included usage drops back to the standard allotment on that date. It’s not a gradual taper and not something triggered by usage crossing a threshold.

A concrete example: four developers, two ways to buy them

Run the numbers against an actual team size instead of a single seat. A four-person team can go two ways: four individual Copilot Pro+ subscriptions, or one Copilot Business team of four seats.

Four Pro+ subscriptions cost $156/month combined (4 x $39) and provide 28,000 credits total (4 x 7,000), but each person’s 7,000 is siloed to that person. Nobody can borrow from a teammate’s unused balance. A four-seat Business team costs $76/month (4 x $19), about half as much, and pools 7,600 credits (4 x 1,900) across all four seats once September 1 arrives, letting a light user’s slack cover a heavy user’s overage.

Business’s pooled total is 27.1% of what four separate Pro+ subscriptions provide, for 48.7% of the cost. Whether that trade is worth it depends on how lumpy the team’s actual usage is. One or two people running long Agent Mode loops while others use Copilot lightly benefits from pooling in a way these raw percentages don’t show on their own. A team with evenly spread usage is closer to just paying less for less.

What the per-dollar number doesn’t capture

None of the math above prices in what Business and Enterprise sell beyond the credit pool itself. Both add centralized billing, org-wide policy controls, SSO, and audit logging, plus the budget tooling this series’ budget-controls guide walks through step by step. Enterprise layers on governance controls Business doesn’t include at all. None of that shows up in a credits-per-dollar ratio, and for a team that genuinely needs those controls, the ratio isn’t the deciding factor.

Credit pooling itself is a real advantage separate from the raw ratio too. A four-seat Business team with wildly uneven usage can outlast a same-cost group of individual subscriptions that each hit a hard per-person ceiling, even with a smaller combined pool, simply because nobody on the pooled plan gets blocked while a teammate’s credits sit unused.

Which plan actually fits your usage pattern

Use Pro or Pro+ when you’re buying for yourself and want the highest credits-per-dollar rate on the lineup. Reach for Max only if a single heavy user’s real usage genuinely exceeds Pro+‘s 7,000-credit pool, and paying $100 beats juggling two separate accounts. Use Business or Enterprise when what you actually need is pooling across an uneven team, or the governance controls that come bundled with a team seat, not the raw credit count. Dollar for dollar, both team tiers buy fewer credits than any individual plan once September 1 arrives.

Check your team’s actual usage pattern, covered earlier in this series, before assuming the plan you’re already on is sized right. A team paying Enterprise prices for what’s really an evenly loaded, per-person workload is paying for pooling it never uses.

Browse more coverage like this in the AI Productivity archive, or start from GitHub Copilot’s AI Credits Cliff hub for the full reversion story.

Quick Answer

On June 1, 2026, GitHub retired Premium Request Units, a flat per-model multiplier, in favor of AI Credits, which price real input, output, and cached tokens per model. Every monthly-billed Pro, Pro+, Business, and Enterprise plan moved automatically. Annual Pro and Pro+ subscribers didn’t move at all; they stayed on the old multiplier system.

Why GitHub metered “premium” models in the first place

GitHub didn’t invent request-based metering on June 1, 2026. It retired one it had already run for exactly a year. Starting June 18, 2025, GitHub began enforcing a monthly cap on premium requests for every seat on Pro, Pro+, Business, and Enterprise, with each plan’s spending limit for anything past that cap defaulting to $0 unless an admin raised it, per GitHub’s own 2025 changelog entry.

A premium request wasn’t every interaction with Copilot. Per GitHub’s legacy billing documentation, it metered the model-backed layer on top of the base subscription: chat sessions against a named premium model, extra-large context windows, advanced reasoning models, cloud agent runs, and generating a Spark app. Some of those models cost more to run than others, so GitHub attached a multiplier to each one: a request against a lightweight model like GPT-4o counted as 0.33 of a premium request, while an advanced reasoning model could burn through 5x or 20x the standard rate for a single call. That multiplier was the entire pricing mechanism. It didn’t care how long the prompt was or how much the model wrote back, only which model answered.

Structural Comparison Matrix

Every figure in that table traces to GitHub’s own changelog or living documentation, cited by section below. Nothing here is a third-party estimate.

What actually changed under the hood

GitHub’s own docs page written specifically for subscribers affected by this change draws the line cleanly. Quoted directly from GitHub’s “What changed with Copilot billing” page, describing the system before June 1:

Each model interaction cost one premium request unit (PRU), and a multiplier was applied based on which model you used.

And describing the system after:

The cost of an interaction depends on two things: the model and the number of tokens consumed.

That’s a structural change, not a rename. Under PRU, a five-word prompt and a five-thousand-token prompt against the same model cost identically, because the multiplier attached to the request as a whole, never to anything measured inside it. Under Credits, GitHub’s own models-and-pricing documentation prices input tokens, output tokens, and cached tokens separately for each model, then converts the dollar total to credits at a fixed 1 credit equals $0.01. The multiplier itself, the thing that used to do all the work, is gone for every plan this migration touched. What replaced it counts tokens instead of guessing at request weight.

The same changelog entry that announced this also folded Copilot code review into Actions-minutes billing and rolled out general availability for user-level budget controls, separate changes bundled into the same June 1 release. Worth knowing so you don’t mistake either one for part of the credits migration itself.

A single request, priced two different ways

Here’s what that structural difference looks like on one real model. Claude Haiku 4.5 prices at $1.00 per million input tokens and $5.00 per million output tokens under Credits, per GitHub’s live pricing table. Send it 8,000 tokens of context and get back a 1,200-token response, nothing served from cache, and the math runs like this:

1. Input: 8,000 tokens x $1.00 / 1,000,000 = $0.008
2. Output: 1,200 tokens x $5.00 / 1,000,000 = $0.006
3. Total: $0.014, or 1.4 credits at the fixed $0.01-per-credit rate

Today, on the legacy multiplier table that annual Pro and Pro+ subscribers still use, Claude Haiku 4.5 carries a 0.33x multiplier. That exchange, on that system, counts as 0.33 of a single premium request against the monthly allowance, full stop. Send it 500 tokens or 50,000, the multiplier doesn’t move. It’s the same contrast as the Structural Comparison Matrix above, just run through one specific model instead of stated abstractly.

What didn’t change

Two things survived the migration intact. Plan prices held: Pro is still $10/month, Pro+ still $39/month, Business still $19 per seat/month, and Enterprise still $39 per seat/month, confirmed directly on GitHub’s plans page. Whatever changed on June 1, it wasn’t what a subscription costs to buy.

And per-model cost variance never went away, it just changed units. A heavier reasoning model still costs more to run than a lightweight one; PRU expressed that with a multiplier, Credits express it with a higher per-token rate. That’s the same industry-wide shift this site already covered for OpenAI, Anthropic, and Google’s own pricing in The 2026 LLM Token & Pricing Reset: flat, coarse units giving way to real per-token economics. Copilot’s version just arrived wearing GitHub’s own billing vocabulary. The exact mechanics of how a token count turns into a credit figure, cached input, cache writes, long-context tiers, are covered in more depth in How GitHub Copilot AI Credits Are Actually Priced.

If you’re on an annual Pro or Pro+ plan, none of this happened yet

Everything above describes monthly billing. Individual subscribers who bought an annual Copilot Pro or Pro+ plan weren’t migrated on June 1 at all; they’re still metered by the PRU multiplier system this post just described, unchanged in mechanism. GitHub’s documentation lays out three explicit options for that group: stay on the annual plan under premium request-based billing, cancel for a prorated refund, or upgrade to a monthly plan and receive prorated credit for the plan’s remaining value.

Annual subscribers aren’t skipping the credits system, they’re on a delayed track toward it, and the default outcome if they don’t act is a downgrade, not an upgrade. Annual Copilot Plans: Model Multipliers Just Spiked covers what changed for that group instead, a revised multiplier table on the very same date, a distinct event from the credits migration that’s easy to conflate with it.

Check which billing system your own plan is actually on before assuming this migration already happened to you. Monthly subscribers got a new pricing mechanism automatically. Annual Pro and Pro+ subscribers got three choices and a deadline, and reading a changelog post won’t tell you which one applies to your seat, your own billing settings will.

Browse more coverage like this in the AI Productivity archive, or start from GitHub Copilot’s AI Credits Cliff hub for the full reversion story.

Quick Answer

Before September 1, 2026, work through four things in order: check real per-user usage, decide whether GitHub’s “AI credits paid usage” policy should stay on or off for your org, set a universal user-level budget above the per-license cost, and confirm every budget you’ve set is sized against the smaller 1,900/3,900 pool landing that day, not the promotional one.

Four posts, one decision sequence

This is the last post in ByteTech247’s ten-part series on GitHub Copilot’s September 1 credit cliff, and it doesn’t introduce a single new fact. Everything here was already verified somewhere else in this series: how to check usage, what the budget toggle actually does, what happens when a pool hits zero, and what each tier’s allotment looks like. What’s been missing, until now, is the order to do them in.

That’s the same role this site’s Same Prompt, Different Bill post played for the LLM token-and-pricing-reset pillar: four separate provider-specific findings, folded into one comparison a reader could act on without reading all four source posts first. This post does the same job for Copilot’s AI Credits cliff, four mechanics posts reduced to one sequence.

The four pieces this synthesizes: checking your actual usage across the three surfaces GitHub shipped in mid-2026, setting budget controls with the real toggle mechanism, what actually happens at zero credits, and the tier allotments the pillar hub itself covers. Read any one of them, and you get a correct answer to a narrow question. Read them in this order, and you get a checklist.

Structural Comparison Matrix

Every cell above restates a fact already verified, cited, and dated in one of the four linked posts, not a new claim introduced here.

Step 1: See where you actually stand

Before anything else, check the actual numbers. Checking usage covers three separate views GitHub shipped inside a five-week window in mid-2026: an individual “Usage this cycle” screen under Copilot settings that needs no admin role (shipped 2026-07-20), a per-user ai_credits_used field in the usage metrics API for org owners and enterprise admins (shipped 2026-06-19), and an org- or enterprise-level dashboard that groups usage by adoption phase (shipped 2026-07-22).

None of the three set a limit. They only show a number. A budget sized without that number first is a guess, not a control, and guessing at a budget is exactly the mistake this whole series exists to prevent.

Step 2: Decide what “credits run out” means for your org

This step is the one most likely to go wrong by default. An earlier framing on this pillar’s own hub post, and one that shows up constantly across GitHub Community threads, treats credit exhaustion as something that halts safely on its own. What actually happens when Copilot credits run out found that’s backward for Business and Enterprise orgs, quoting GitHub’s own usage-based billing documentation directly:

Additional usage is enabled by default for organizations and enterprises. If you want to prevent any spending beyond your included AI credits, an administrator must explicitly disable the AI credits paid usage policy in your enterprise’s or organization’s AI Controls settings.

An org that has never touched its AI Controls settings, never set a budget, and never disabled anything keeps billing metered AI credit usage at $0.01/credit the moment its shared pool empties, for as long as usage continues. That leaves a real decision, not a passive default to accept. Disable “AI credits paid usage” and accept a hard stop once the pool empties, matching what plenty of admins assume already happens. Or leave it on and back it with real budgets instead, the subject of the next step.

Step 3: Set the budget that actually enforces your decision

Whichever way step 2 goes, budget controls are the mechanism that makes it real instead of aspirational. Set the universal user-level budget first, above the per-license value, $19/user/month for Business, $39/user/month for Enterprise, or credit pooling across the org breaks before it can do its job. GitHub’s own getting-started tutorial calls this one setting “the single most important control,” and it’s the one budget scope with no toggle to configure. It always hard-stops the moment a user hits it.

Everything past that is a real judgment call, not a fixed rule. Override the universal budget for identified power users running heavy Agent Mode sessions. Decide, scope by scope, whether an org or cost-center budget’s “Stop usage when budget limit is reached” toggle should be on, a hard block once the limit hits, or off, a notification while charges keep accruing, per GitHub’s own budgets documentation. That toggle starts off by default on every newly created org- or cost-center-scoped budget, so leaving it untouched is itself a choice, whether anyone meant it to be.

Step 4: Know the number you’re budgeting against

Every budget from step 3 is only as good as the pool it’s measured against, and that pool is about to shrink. Business drops from a promotional 3,000 credits/user/month to a standard 1,900 on September 1, 2026. Enterprise drops from 7,000 to 3,900, per the pillar hub covering the reversion itself. A budget sized generously against the July pool can start blocking real work in September if nobody revisits the number.

Individual plans sit outside this specific cliff. Copilot Pro includes 1,500 credits a month, Pro+ includes 7,000, and Max includes 20,000, figures the exhaustion-behavior post verified against GitHub’s own individual-plans billing documentation, and none of those allotments revert on September 1 the way the pooled Business and Enterprise numbers do. A full plan-by-plan credit comparison, weighing whether an upgrade actually buys proportionally more headroom, is planned as its own post in this series and isn’t published as of this writing. Until then, the tier figures above are the numbers to plan against.

The five-minute version

If there’s time for exactly one pass before September 1, work through this order:

1. Open Copilot settings and check “Usage this cycle,” or pull the org dashboard if you manage more than your own seat.
2. Decide “AI credits paid usage” on purpose: disabled for a hard stop, or left on with a plan to back it.
3. Set the universal user-level budget above $19 (Business) or $39 (Enterprise) per user.
4. Re-check any existing budget against 1,900 (Business) or 3,900 (Enterprise), not the promotional number it might still be sized against.

Do this before the pool shrinks under it

None of this requires a rebuild. It requires one afternoon: pull the real usage numbers, make the paid-usage-policy decision on purpose instead of by default, set the universal budget above the per-license floor, and re-size every existing budget against the pool that lands September 1, not the one that’s about to disappear.

Skip it, and the default still applies whether anyone chose it or not. Metered billing runs uncapped past an empty pool unless something explicit stops it first. That’s not a hypothetical, it’s the documented default for every Business and Enterprise org that hasn’t touched its AI Controls settings yet. Check the number today. September 1 doesn’t wait for a slow afternoon.

Browse the rest of this series starting from the AI Credits cliff hub, or more coverage in the AI Productivity archive.

Quick Answer

Route routine Copilot requests, boilerplate, quick edits, single-function reviews, to a Lightweight or Versatile model like GPT-5 mini. Reserve a Powerful model like Claude Opus 4.8 for multi-file refactors, architecture decisions, and long agent loops. The price gap runs about 15x per token, a real credit-saving lever the old flat-multiplier system never gave you.

Per-token pricing makes model choice a real cost decision

GitHub Copilot’s AI Credits price real token counts, not a flat per-request charge. How GitHub Copilot AI Credits Are Actually Priced covers the full mechanics: 1 credit equals $0.01, and every model bills its own rate for input, cached input, cache-write, and output tokens. That post’s worked example lands on a specific number worth carrying forward: the same 100,000-token prompt costs about 15 times more credits on Claude Opus 4.8 than on GPT-5 mini.

Premium Request Units never let anyone act on that gap. A flat multiplier attached to the request, not to the model actually doing the work, so switching models didn’t change what you paid. Credits attach the cost to the model itself. That turns model choice into a repeatable lever for making a fixed credit pool last longer, not just a quality preference.

GitHub’s own task guidance, not just a price label

GitHub publishes two separate classification systems for its models, and conflating them is the easiest way to pick badly. The pricing table sorts every model into a cost tier: Lightweight, Versatile, or Powerful, based on what it costs per token. A completely different page, GitHub’s AI model comparison guide, sorts models into task areas instead: General-purpose coding and writing, Fast help with simple or repetitive tasks, Deep reasoning and debugging, and Working with visuals.

Those two systems don’t line up as neatly as the names suggest. GPT-5.6 Luna prices as Lightweight and GitHub recommends it for the simple-tasks category, a clean match. Claude Haiku 4.5 prices as Versatile, a mid-tier label, yet GitHub recommends it for the same simple-tasks category, alongside GPT-5.6 Luna. And GPT-5 mini, priced Lightweight, the cheapest tier on the whole table, shows up in GitHub’s own recommendations for three different task areas at once: general-purpose coding, deep reasoning and debugging, and visual work. GitHub’s guide credits it with reasoning and debugging quality close to full-size GPT-5, just at noticeably faster response times and lower resource cost.

Structural Comparison Matrix

Every price and task-area pairing above comes from cross-referencing GitHub’s live models-and-pricing table against its model comparison guide, both checked directly on 2026-08-19. Neither page cross-links the other’s classification, so this table is this post’s own cross-check, not something GitHub publishes as a single reference.

What “good enough” actually costs

Take a routine Copilot Chat exchange: a quick function review or a small edit, something like 2,000 input tokens and 500 output tokens. That’s a realistic size for the kind of request GitHub’s own guidance points at Lightweight and Versatile models.

GPT-5 mini ($0.25 input / $2.00 output per 1M tokens):

1. Input: 2,000 tokens x $0.25 / 1,000,000 = $0.0005
2. Output: 500 tokens x $2.00 / 1,000,000 = $0.001
3. Total: $0.0015, or 0.15 credits

Claude Opus 4.8 ($5.00 input / $25.00 output per 1M tokens):

1. Input: 2,000 tokens x $5.00 / 1,000,000 = $0.01
2. Output: 500 tokens x $25.00 / 1,000,000 = $0.0125
3. Total: $0.0225, or 2.25 credits

Same 15x gap the pricing post found at a much bigger token count, holding steady at a small one. The difference only starts to matter at volume, so scale it up: a developer sending something like 30 of these routine requests a day, every one of them on Claude Opus 4.8, spends about 67.5 credits a day. Over a 30-day month that’s 2,025 credits, more than the entire 1,900-credit standard Business allowance this site’s AI Credits cliff hub covers, on routine requests alone, with nothing left for anything harder. The same 30 requests a day on GPT-5 mini cost about 135 credits for the month, leaving roughly 1,765 credits of that same pool for the work that actually needs a Powerful model.

When the extra credits are worth spending

GitHub’s own guide is specific about what actually calls for a Powerful model, not just a rough “harder problems” gesture. Under Deep reasoning and debugging, it recommends reaching for one of those models when you want to:

Debug complex issues with context across multiple files. Refactor large or interconnected codebases. Plan features or architecture across layers. Weigh trade-offs between libraries, patterns, or workflows. Analyze logs, performance data, or system behavior.

GPT-5.6 Sol carries the strongest language of any model in that section. GitHub positions it as the top of the GPT-5.6 lineup for reasoning depth, the pick for large-codebase problems and agent sessions that run long without a break. Claude Opus 4.7 gets billed as Anthropic’s flagship, its most capable model at the time this was checked. Gemini 3.1 Pro is aimed squarely at long-context, technical analysis work, exactly the kind of task where losing context partway through actually costs you something.

None of that is about raw token count. A 5,000-token prompt asking a Powerful model to plan a cross-service refactor is a legitimate use of the extra credits. A 5,000-token prompt asking the same model to fix a missing semicolon isn’t, and GitHub’s own general-purpose and fast-help categories exist precisely to catch that second case before it reaches a Powerful model at all.

Let Auto route it, or do it yourself, just don’t switch mid-session

GitHub built an alternative to picking a model by hand: Auto with task optimization. GitHub says it’s now generally available in Copilot Chat’s web interface, VS Code, Copilot CLI, and the GitHub Copilot app, not a preview feature. Per GitHub’s own Auto model selection documentation, it combines two systems, one tracking real-time model availability, the other evaluating task complexity, and routes each request to whichever model fits. GitHub’s own framing of the goal is worth quoting directly, not paraphrasing:

Reserving higher-cost reasoning models for problems that truly need it, while routing straightforward tasks to faster, lower-cost models that still deliver great results.

Paid plans get something concrete out of trusting that routing, too: a 10% discount on model costs specifically while using Auto, applied in Copilot Chat, Copilot CLI, the GitHub Copilot app, or Copilot cloud agent.

That’s not the only Auto running across Copilot’s clients, and the distinction matters. JetBrains IDEs, Eclipse, Xcode, and Visual Studio’s preview run an older flavor, “optimized for reliability and availability,” that picks purely on real-time system health to cut rate limiting. It doesn’t evaluate task complexity or claim a cost benefit the way the task-optimized version does. Check which Auto your client is actually running before assuming it’s doing the routing this post describes.

One more real constraint before any of this applies: on Business and Enterprise plans, changing the chat model isn’t available by default. An organization or enterprise has to explicitly grant members the ability to switch models at all. If that policy isn’t on, every request runs on whatever model an admin configured, regardless of which one would actually be cheaper for the task in front of you.

Model choice matters most once Agent Mode is looping

A single chat exchange burns tokens once. Agent Mode’s read-file, edit, run-tests, re-read loop burns tokens on every step of that loop, which means a model choice made at the start compounds across every iteration, not just one request. That outsized consumption pattern, and the specific levers for controlling it, gets its own full treatment in Why Copilot Agent Mode Burns Through Credits So Fast, the next post in this series. The short version worth carrying over here: the routing decisions this post covers matter more, not less, once the requests stop being one-off chat questions and start being agent steps that repeat the same model choice dozens of times in a row.

Route by default, escalate on purpose

Default to a Lightweight or Versatile model for the requests that make up most of a working day, boilerplate, quick edits, single-function reviews, and let GitHub’s own task guidance, not the price tier’s name, tell you when a request actually needs a Powerful model. GPT-5 mini earning a spot in GitHub’s deep-reasoning recommendations is the proof that “cheap” and “only for simple work” aren’t the same claim. Escalate when a task genuinely needs multi-file context or architectural judgment, not by habit, and pick that model before the session starts rather than switching partway through.

Browse more coverage like this in the AI Productivity archive, or start from GitHub Copilot’s AI Credits Cliff hub for the full picture.

Quick Answer

On Business and Enterprise plans, running out of pooled AI credits with no budget configured doesn’t stop anything: GitHub’s “AI credits paid usage” policy is enabled by default, so metered billing continues automatically and uncapped. Individual Pro, Pro+, and Max users don’t get billed the same way; they’re prompted to upgrade, wait, or manually set a budget.

Why this keeps showing up in GitHub’s own community forum

Search “Copilot credits run out” and you land in the middle of a real, ongoing argument among GitHub admins about what actually happens. GitHub’s own community-run FAQ thread, discussion #197089, “All GitHub Copilot plans are now on usage-based billing”, has drawn hundreds of comments since the June 2026 rollout, many of them asking the exact question this post answers.

Two other threads narrow the confusion to specific scenarios. In discussion #197557, a student reports their entire monthly Student-plan allowance gone after roughly 10 to 20 Agent Mode requests on the first day of a new cycle, a number the poster gives as 200 credits for that plan; that figure comes from the reporting user, not from GitHub’s own published plan table, which doesn’t list an exact Student allowance. In discussion #197605, an enterprise admin describes a setting that used to read “$0 budget” and block overage automatically now showing “No Usage Limit” instead, and asks how to stop unexpected charges. That admin’s confusion is the same one this post exists to resolve.

What happens on an individual plan: Pro, Pro+, and Max

Copilot Pro includes 1,500 AI credits a month (1,000 base plus a 500 flex allotment), Pro+ includes 7,000 (3,900 base plus 3,100 flex), and Max includes 20,000 (10,000 base plus 10,000 flex), each priced at 1 AI credit = $0.01, per GitHub’s individual-plans billing documentation. Once that allowance is gone mid-cycle, GitHub’s docs describe three options, not one automatic outcome:

• Upgrade to the next plan. You’re only charged the price difference, and credit already used in the cycle carries over into the larger allowance.
• Stay on your current plan and pay for more. GitHub frames this as an action you take, not a default that’s already active: you have to set a budget for that additional usage before any of it is served.
• Wait it out. Your allowance resets at 00:00 UTC on the 1st of the next calendar month, the same fixed reset time every plan uses.

Nothing in that page says additional usage is already switched on the way it is for organizations. A Pro or Pro+ subscriber who never touches their billing settings and runs out mid-cycle doesn’t get a silent bill; they get prompted to act.

What happens on Business and Enterprise with no budget configured

This is where the brief that GitHub-admin folklore repeats gets it backward, and it’s worth quoting GitHub’s own docs directly rather than paraphrasing. GitHub’s usage-based billing documentation for organizations and enterprises answers this directly, in the section explaining what happens once a pooled allowance runs out:

Additional usage is enabled by default for organizations and enterprises. If you want to prevent any spending beyond your included AI credits, an administrator must explicitly disable the AI credits paid usage policy in your enterprise’s or organization’s AI Controls settings.

Read that twice. It’s not describing a safety net. An org that has never touched its AI Controls settings, never set a budget, and never disabled anything, keeps billing metered AI credit usage at published per-credit rates the moment its shared pool empties, for as long as usage continues. GitHub’s companion budgets documentation confirms the same default applies to any budget an admin does set:

By default, reaching a spending limit sends a notification but does not stop usage. Charges continue to accrue without a cap until you manually intervene.

The only configuration that produces a genuine, automatic halt at zero credits is disabling the “AI credits paid usage” policy itself. Do that, and the result is a real stop: nothing more gets served once the pool is empty, and it stays that way until the following month’s allowance lands, regardless of any budget you have or don’t have configured.

Structural Comparison Matrix

Every row above is quoted or closely paraphrased from GitHub’s own budgets-for-usage-based-billing and usage-based-billing-for-organizations-and-enterprises documentation, live-checked while drafting this post rather than carried over from an earlier summary.

How the check actually runs, step by step

GitHub’s docs describe the order a single Copilot request gets evaluated in, which is the fastest way to reason about your own org’s real exposure:

1. A user-level budget check runs first. Whichever ULB is most specific to that user, individual, then cost-center, then universal, gets checked before anything else happens. Already past that number, and the request never even reaches the shared pool.
2. The shared pool absorbs whatever it can. Room left in the pool means this particular call costs nothing extra. The instant that pool hits zero, every subsequent call becomes metered, billed usage instead.
3. Metered usage looks for a matching budget. GitHub checks a cost center’s budget first, then an organization’s, then the enterprise-wide spending limit, whichever one actually applies to that user. None of those can block anything unless its own “Stop usage when budget limit is reached” switch has been flipped on.

Skip step 3 entirely, no cost center budget, no org budget, no enterprise limit, and there’s simply nothing left to check. The request goes through as paid overage. That’s the whole mechanism behind the default this post opened with: not a special case, just what happens when the chain above runs out of budgets to consult.

What to do with this before September 1

If your org is running on whatever GitHub set up by default, you are already exposed to uncapped metered billing the moment your pool empties, promotional allowance or not. Checking your org’s “AI credits paid usage” setting takes minutes; discovering it the hard way, in next month’s invoice, doesn’t. The budget-controls setup guide in this series walks through configuring a universal user-level budget, sizing a spending limit, and turning on “Stop usage when budget limit is reached” so the default above stops being the thing protecting or exposing your org by accident.

Decide deliberately: either disable “AI credits paid usage” and accept a hard stop at the pool’s edge, or leave it on and set real budgets with the stop toggle enabled. Doing neither isn’t neutral. It’s the org quietly choosing uncapped, automatic billing, whether anyone meant to or not. For the fuller picture of what’s reverting and when, see the AI Credits cliff hub this post is part of, and browse more coverage in the AI Productivity archive.

Quick Answer

actions/checkout v7 refuses to check out a fork pull request’s head or merge ref inside pull_request_target and PR-flavored workflow_run workflows, closing the classic “pwn request” hole where a workflow runs with the base repo’s secrets but executes an attacker’s code. Floating tags (@v4) picked up the fix automatically once it was backported on 2026-07-20; pinned versions and SHAs need an explicit bump.

Why this was a real vulnerability, not a theoretical one

pull_request_target exists so that a workflow can run with the base repository’s full secrets and write permissions even when triggered by a fork’s pull request, useful for things like commenting on the PR or triggering a deploy preview. The catch: many workflows using that trigger also checked out the fork’s own head commit, because that’s the code the PR is actually proposing to merge.

Put those two facts together, and you get the “pwn request” pattern: a workflow with real secrets, running arbitrary code from someone who doesn’t have write access to your repo. An attacker opens a PR from a fork, and any workflow step that executes something from the checked-out fork code (a build script, a test runner, a linter with a plugin system) runs with the base repo’s permissions.

actions/checkout v7.0.0 (released 2026-06-18) closes this by refusing to fetch the fork’s code in that specific context. The action now fails on patterns like these when it detects a pull_request_target or PR-flavored workflow_run event:

# actions/checkout v7 blocks all three of these inside
# pull_request_target and PR-flavored workflow_run:
ref: refs/pull/${{ github.event.pull_request.number }}/merge
ref: ${{ github.event.pull_request.head.sha }}
repository: ${{ github.event.pull_request.head.repo.full_name }}

The fix landed as a major release first, then GitHub backported it to every older supported major version on 2026-07-20: the v6 line got v6.1.0, v5 got v5.1.0, v4 got v4.4.0, v3 got v3.7.0, and v2 got v2.8.0, each shipping the same enforcement that same day. Workflows pinned to a floating major tag like @v4 picked up the change automatically the next time that job ran.

Structural Comparison Matrix

Fixing a workflow that hits this

If a pull_request_target or workflow_run job in your repo starts failing at the checkout step after 2026-07-20, work through this in order.

1. Check what version you’re actually pinned to. Open the workflow file and look at the uses: line for every checkout step in a pull_request_target or workflow_run job.

   .github/workflows/preview.ymlCopy

   - uses: actions/checkout@v4.2.0 # exact pin, below the 4.4.0 fix
     with:
       ref: ${{ github.event.pull_request.head.sha }}

2. Bump the pin to the fixed release for your major version: v7.0.0 if you’re on the v7 line, or the matching backport otherwise (v6 got 6.1.0, v5 got 5.1.0, v4 got 4.4.0, v3 got 3.7.0, v2 got 2.8.0).

   .github/workflows/preview.ymlCopy

   - uses: actions/checkout@v4.4.0 # fixed
     with:
       ref: ${{ github.event.pull_request.head.sha }}

3. Confirm the job still fails after the bump. If it does, that’s the intended behavior: your workflow genuinely was checking out fork code under pull_request_target, and the failure is GitHub asking you to look at it again, not a bug.

4. Redesign around the safer pattern if you can. Most pull_request_target use cases (posting a comment, labeling a PR, triggering a status check) don’t need the fork’s code at all. Split the job: run the untrusted build/test steps under plain pull_request (no secrets, no write access), and use a separate pull_request_target job only for the trusted, secrets-requiring step that reads the PR’s metadata rather than its code.

5. Only if you’ve reviewed it and it’s genuinely necessary, opt back in explicitly:

   .github/workflows/preview.ymlCopy

   - uses: actions/checkout@v4.4.0
     with:
       ref: ${{ github.event.pull_request.head.sha }}
       allow-unsafe-pr-checkout: true

Does this affect this site’s own deploy workflow?

This site’s CI, .github/workflows/ci.yml, pins actions/checkout@v7 already and only triggers on push to main and same-repo pull_request events, never pull_request_target or a fork-originated workflow_run. That specific attack surface doesn’t exist here. Worth saying plainly rather than implying a dogfooding story that isn’t real: this repo has nothing to fix for this particular change, because it was never exposed to the pattern it blocks.

Restricting which triggers and which people can even fire a workflow in the first place is a related, complementary control: see Set Up GitHub Actions Workflow Execution Protections for the allow-list layer that sits in front of the checkout step covered here.

If you’re deploying this exact kind of static site through GitHub Actions rather than Cloudflare’s built-in Git integration, Cloudflare Workers Deploys: Built-In Git vs. GitHub Actions covers that pipeline choice, including the actions/checkout step in a from-scratch deploy workflow.

Source

GitHub’s own changelog entry announcing this checkout change (2026-06-18, enforcement backported 2026-07-20), corroborated against the checkout action’s release history on GitHub (major release plus five backported patch versions, all published 2026-07-20). Browse more posts like this in the Dev Tools archive.

Quick Answer

Pull requests opened by github-actions[bot] (typically from a scheduled workflow that commits changes and opens a PR) can now trigger CI/CD workflows, as of 2026-06-11. But the run doesn’t start automatically: a repository collaborator with write access has to approve it first, the same gate already used for Copilot-authored PRs.

What was broken before this

A common automation pattern: a scheduled workflow runs, makes some change (dependency bumps, generated docs, a lockfile refresh), commits it, and opens a pull request using github-actions[bot] as the author. Before this change, that bot-authored PR could not trigger the repo’s own CI workflows at all, no lint, no test, no build check.

That’s a real gap. It meant bot-generated PRs either sat unchecked until someone manually re-ran the workflow, or worse, got merged without the same test/lint/build gate a human-authored PR would have gone through automatically. GitHub’s own framing of the fix is direct about why the fix isn’t “just let it run automatically” either:

“Requiring approval is a security measure to ensure generated code does not automatically run workflows which may have access to sensitive information.”

So the fix isn’t unrestricted trust, it’s a middle ground: bot PRs can now run workflows, but a human has to say so first, every time.

How the approval gate works in practice

This builds on a setting that already existed: repository Settings → Actions → General → Workflow permissions, specifically the checkbox controlling whether GitHub Actions can create and approve pull requests. That checkbox is what lets a scheduled workflow open the PR in the first place. What’s new as of 2026-06-11 is what happens after the PR exists.

Once github-actions[bot] opens a PR against a workflow-triggering event (pull_request, for instance), the workflow run doesn’t start immediately the way it would for a normal contributor with write access. It sits pending, waiting for approval, visible the same way a first-time contributor’s workflow run already waited for maintainer approval before this change. A collaborator with write access reviews the PR’s diff and clicks approve on the workflow run, and only then does CI actually execute.

GitHub notes this matches an existing pattern rather than inventing a new one:

“This matches the behavior of Copilot-generated pull requests.”

If your team already reviews Copilot PRs’ workflow runs this way, bot-authored PRs from your own scheduled automation now follow the identical flow.

Structural Comparison Matrix

Reviewing and approving a pending run

If your repo runs a scheduled workflow that opens PRs (a dependency-bump job, a generated-content refresh, anything committing via GITHUB_TOKEN), check for pending runs after this change ships rather than assuming CI already ran:

1. Open the pull request from github-actions[bot] in the GitHub UI.
2. Look for the workflow run status. A pending approval shows as a banner on the PR, distinct from a normal “in progress” or “queued” state.
3. As a collaborator with write access, review the PR’s actual diff first, this is the security check the changelog describes, not a rubber stamp.
4. Click Approve and run on the workflow run to let it execute.

If you want bot PRs to keep working exactly as before this change, and you’re comfortable with the tradeoff, there’s no toggle to bypass the approval step entirely; it’s the intended behavior, not an opt-in feature.

Source

GitHub’s changelog entry on the bot-PR approval requirement (2026-06-11). Browse more posts like this in the Dev Tools archive.

Quick Answer

Zapier auto-migrates any Zap using the Conversation With Assistant (Legacy) action to the new Conversation action, built on OpenAI’s Responses API, but the migrated Zap stays switched off. Before August 26, 2026, open it, confirm the new action’s configuration, remap any downstream step reading the old output shape, and manually re-enable it.

Why this is worth checking even if nothing looks broken

OpenAI is deprecating its Assistants API, and Zapier’s own ChatGPT deprecation notice states the deadline plainly:

“On August 26, 2026, Zaps using these actions will stop working.”

A short honesty note before going further: ByteTech247 doesn’t run Zapier. This site’s own automation is Cloudflare Workers and GitHub Actions, covered in our Cloudflare API deprecation pillar. Everything below is drawn directly from Zapier’s own Help Center documentation, not from running these exact Zaps ourselves.

For the Conversation With Assistant (Legacy) action specifically, Zapier already did the migration work. Any Zap using it gets automatically switched to the new Conversation action. The part that catches people off guard is what happens next: Zapier’s notice states that

“Migrated Zaps are left turned off so you can review them first.”

That’s a deliberate design choice, not a bug. But it means a Zap that “already migrated” weeks ago can still be sitting disabled today, with the only visible sign being a toggle set to off somewhere in a list of dozens of Zaps. There’s no separate ongoing alert once the initial migration notice scrolls past your inbox.

Structural Comparison Matrix

Fix it: find, review, and re-enable

Start by finding every Zap that’s been silently switched off:

1. Open your Zaps list and filter by status: Off. Any Zap that used to run on Conversation With Assistant (Legacy) and now shows as off, without you having turned it off yourself, is a migration candidate.
2. Open the Zap’s editor and check the action step. If it now reads Conversation instead of Conversation With Assistant (Legacy), this is one of the auto-migrated ones.
3. Review the Conversation action’s configuration. The legacy action ran against a specific assistant and thread; the new one is prompt- and memory-based, so confirm the model, prompt, and any file/web search options are actually set the way the old Zap intended, not left at defaults.
4. Check every downstream step (a Formatter step, a filter, a Slack or email notification) that reads a field off the ChatGPT step’s output. The legacy action’s output shape was built around assistant/thread objects; the Conversation action’s output is not guaranteed to match field-for-field, so a step reading output.message or similar needs to be checked against what the new action actually returns in a live test run.
5. Run a test, confirm the output looks right end to end, then flip the Zap back on.

If the legacy Zap only ever needed a single one-shot response with no ongoing memory, it’s worth comparing against Send Prompt instead of sticking with the default Conversation migration, since Send Prompt is Zapier’s stated action for exactly that simpler case.

Confirmed version

Sourced from Zapier’s official Help Center advisory on the OpenAI Assistants API deprecation for ChatGPT, updated 2026-07-20, deadline confirmed as 2026-08-26. Browse more posts like this in the Data Automation archive.

Quick Answer

Even after reconnecting a Greenhouse Zap to OAuth 2.0, every trigger, action, and search built on Harvest v1 or v2 needs its fields checked against Harvest v3’s schema. Zapier names six triggers, five actions, and two searches as affected, plus any raw API Request or custom action calling the Harvest API directly, with no single marker to flag which of your Zaps’ steps need attention.

A schema problem, not an auth problem

A quick honesty note before the specifics: ByteTech247 doesn’t run Zapier. Its own automation runs on Cloudflare Workers and GitHub Actions, covered separately in our Cloudflare API deprecation pillar. What’s below is sourced from Zapier’s own Help Center advisory on the Greenhouse deprecation, not from operating these Zaps first-hand.

The same Zapier notice that covers the OAuth 2.0 reconnect also lists exactly which steps are built against the old Harvest v1/v2 API and need checking under v3. Unlike Zapier’s Pipedrive deprecation notice, which prepends a literal [DEPRECATING JULY 31 2026] label to every affected step name inside the Zap editor, this one gives no in-product marker. The list exists only in the Help Center article itself, so finding affected steps means manually comparing that list against every Greenhouse step across every live Zap.

Zapier’s affected-steps list, quoted directly:

Triggers: New Candidate Application, New Job Post, Candidate Hired, New Scheduled Interview, Job Updated, New Scorecard Due

Actions: API Request (Beta), Create Candidate Note, Create Candidate, Create Prospect, Update Candidate

Searches: Find Candidate, Find Due Scorecard

For anything built with a raw API call rather than one of Zapier’s built-in steps, the notice is direct:

“If you use the API Request action or custom action, you must migrate your request to the Harvest v3 API”

That migration covers updating URLs, headers, body fields, and authentication parameters to match Greenhouse’s current Harvest v3 documentation, according to the same notice. Zapier doesn’t publish a field-by-field diff between v2 and v3 for each of these steps, so the practical path is checking each one’s current output against what the Zap’s downstream steps expect, then consulting Greenhouse’s own Harvest v3 API reference for anything that looks off.

Structural Comparison Matrix

Fix it: cross-reference every Greenhouse step

1. List every Zap using a Greenhouse step. For each one, note the exact trigger, action, or search name in use.
2. Check each step name against Zapier’s list above. If it matches one of the six triggers, five actions, or two searches, treat it as needing a field-level review, not just an auth reconnect.
3. For built-in steps, re-test with real data after reconnecting. Run the Zap manually against a real record and compare the fields it returns or writes against what the downstream steps in the Zap actually expect. A field silently missing or renamed under v3 won’t throw an error the way a broken auth call does; it just produces blank or unexpected values further down the Zap.
4. For API Request or custom action steps, migrate manually. Per Zapier’s notice, that means updating the request URL, headers, body fields, and auth parameters to match Harvest v3, referencing Greenhouse’s own current API documentation rather than the v1/v2 shape the request was originally built against.
5. Don’t assume a Zap is clear just because it ran successfully once. Since there’s no per-step marker, the only reliable check is the manual cross-reference in step 2, done for every Zap, not a spot check on the ones that come to mind first.

Confirmed version

Sourced from Zapier’s official Help Center advisory on the Greenhouse Harvest API deprecation, published 2026-07-27, with the full affected-steps list and API Request migration instruction confirmed directly against that source. Browse more posts like this in the Data Automation archive.

Quick Answer

HubSpot retired its v1 Lists API on April 30, 2026. Zapier’s Add Contact to List and Remove Contact from List actions, built against that API, stopped working on that date. There’s no dedicated Zapier Help Center advisory for this one, only a single line in a May 2026 community digest post, so the practical fix is testing the action directly against a real contact and list rather than waiting for a Zap error to surface it.

Why this one is sourced differently than the rest of this series

One honesty note first: ByteTech247 doesn’t run Zapier. This site’s own automation is Cloudflare Workers and GitHub Actions, covered in a separate Cloudflare API deprecation pillar. What follows is sourced from Zapier’s own community documentation, not from running this integration ourselves.

This post also needs a second, more specific honesty note, because its sourcing is genuinely weaker than the Pipedrive, Greenhouse, and ChatGPT posts in this series. Those three each have a dedicated Zapier Help Center “action required” article with a clear publish date and an explicit deadline. This one doesn’t. The only corroborating source is a single bullet inside Zapier Community’s monthly integrations digest, published May 28, 2026, buried among dozens of unrelated feature updates:

“Add Contact to List / Remove Contact from List: Actions using deprecated v1 Lists API sunset April 30 2026”

Both dates here sit slightly earlier than the freshness window the rest of this series targets. This is the same shape of caveat we’ve stated on two other posts on this site, Cloudflare’s AMP/SXG API end-of-life and Cloudflare’s Gateway Audit SSH rules deprecation, both of which document changes that had already happened before the corroborating post went up. The justification is the same here: this break is old enough to have already occurred, but recent enough, and undocumented enough by any dedicated advisory, that people are plausibly still finding silently broken list-management Zaps months later with nothing authoritative to search for and find.

Structural Comparison Matrix

Fix it: test directly, since there’s nothing else to check against

1. Find every Zap using Add Contact to List or Remove Contact from List. These are the two actions the digest names directly.
2. Run each one manually against a real contact and a real list, rather than trusting that a Zap showing “success” in its history actually moved the contact. Since the digest gives no description of how the failure presents (an error, a silent no-op, or something else), don’t assume a clean Zap history means the action actually worked.
3. Check list membership in HubSpot directly after the test run. If the contact wasn’t added or removed despite the Zap reporting success, that’s consistent with the v1 API sunset described in the digest.
4. Look for a current, non-deprecated list-management action in the Zapier HubSpot app as the fix, rather than assuming there’s a drop-in v2 equivalent to swap into the same action slot. Since no dedicated migration guide exists for this one, confirming the current action’s exact behavior against a live HubSpot list is the most reliable check available.
5. Re-check periodically. Because this deprecation has no dedicated advisory to bookmark, there’s no single page to watch for updates. A recheck every so often is a reasonable substitute for the update notifications the other Zaps in this series get from their own Help Center articles.

Confirmed version

Sourced from Zapier Community’s monthly integrations digest for May 2026, published 2026-05-28, the only corroborating source found for this deprecation; no dedicated Zapier Help Center advisory exists for it as of this writing. Browse more posts like this in the Data Automation archive.

Quick Answer

Vitest 5 removes bench as a top-level export from vitest. Code still written as import { bench } from 'vitest' stops working, because bench now only exists as a fixture destructured from a regular test() context. Fix it by rewriting each benchmark as test('name', async ({ bench }) => { await bench(fn).run() }), and by replacing any removed benchmark.* config options with their documented equivalents.

Why the top-level bench import stops working

Vitest’s own migration guide states this plainly under “Benchmarking API Rewrite”:

bench is no longer a top-level import from vitest; it is a test-context fixture accessed from inside a regular test().

That’s a structural change, not a rename. The old form:

import { bench } from "vitest";

bench("sort", () => {
  [3, 1, 2].sort();
});

no longer resolves to a working benchmark call in Vitest 5, because vitest stops exporting a bench symbol at the module level at all. Exactly how that surfaces depends on your bundler and TypeScript setup: some configs throw at import time, others fail type-checking first, and a few just silently run nothing because bench resolves to undefined. Vitest’s guide doesn’t publish one canonical error string for this case, so treat the exact wording you see as environment-specific rather than a fixed message to search for. The mechanical cause is the same either way: bench isn’t there to import anymore.

The guide also confirms bench.skip, bench.only, and bench.todo are removed in the same rewrite. Any suite using those modifiers needs the same migration as a plain bench call.

What happens to benchmark.reporters, outputFile, compare, and outputJson

This is the part of the change that breaks a CI pipeline quietly instead of loudly. A benchmark suite that imports bench correctly can still fail to produce the output a workflow expects, because four benchmark.* config options are removed entirely in the same rewrite, not renamed:

• benchmark.reporters and benchmark.outputFile are gone. The migration guide says that output now ships through the standard reporter pipeline instead of a dedicated benchmark reporter, so there’s no separate config to point at a custom output stream anymore.
• benchmark.compare and the matching --compare CLI flag are removed, with no direct 1:1 replacement documented.
• benchmark.outputJson and the --outputJson CLI flag are removed. The guide’s replacement is --reporter=json --outputFile=<path>, run through Vitest’s general reporter system instead of a benchmark-specific option.

None of these throw an import error the way the bench removal does. A vitest.config.ts that still sets benchmark.compare just has that setting silently ignored, so the first sign of trouble is usually a CI step that expects a comparison artifact or a JSON file and doesn’t get one.

Fix it: move bench into the test context fixture

Rewrite each benchmark to destructure bench from the test() callback’s context object, call it, then call .run() on the result:

import { bench } from "vitest"; // BROKEN: no longer exported at module scope

bench("sort", () => {
  [3, 1, 2].sort();
});

import { test } from "vitest";

test("sort", async ({ bench }) => {
  // FIXED: bench is a fixture on the test context now, and .run() is required
  await bench("sort", () => {
    [3, 1, 2].sort();
  }).run();
});

The .run() call is not optional decoration. Without it, bench(...) just constructs the benchmark and returns without ever executing it, so a half-migrated call site can look correct while producing no timing data at all.

Confirmed version range

This is documented in Vitest’s own current migration guide, under “Benchmarking API Rewrite,” as an intentional Vitest 5 change, corroborated as in-window against the beta release available at research time (v5.0.0-beta.7). This repo’s own vitest.config.ts is pinned to vitest@^3.0.0 and doesn’t use the benchmarking API, so this specific removal wasn’t independently reproducible against this repo’s own build. Treat the mechanics above as documented behavior from Vitest’s primary source, not a first-party reproduction. Browse more posts like this in the Guides & Fixes archive.

Quick Answer

Vitest 5 removes eight subpath entry points outright, including vitest/reporters and vitest/coverage. Vitest’s own migration guide states plainly: use vitest/node instead for both. A custom reporter or coverage config still importing the old path fails to resolve on upgrade. Update the import path to vitest/node; there’s no compatibility shim to fall back on.

Why the import breaks: eight entry points are gone

Vitest 4 exposed a wide set of subpath imports, letting a custom reporter, coverage provider, or internal tooling script reach directly into Vitest’s own internals. Vitest’s migration guide documents that Vitest 5 removes several of those paths outright, under a section titled Removed Deprecated Entrypoints. There’s no deprecation warning period for these specific paths and no runtime shim; the import simply stops resolving the moment a project upgrades to Vitest 5.

That’s a structural cleanup, not a one-off removal. The guide maps every removed path to a specific, named replacement:

Six of the eight collapse onto two consolidated entry points, vitest/node and vitest/runtime. The other two, vitest/mocker and vitest/internal/module-runner, don’t map onto either: one moves to its own standalone package, the other is gone with nothing named in its place. A project can’t safely assume “swap in vitest/node” is the universal fix; each removed path needs checking against its own row above.

The exact wording of the resolution failure itself varies by bundler and by whether the import is a type-only import, a runtime require, or a dynamic import(), so this post doesn’t quote one specific error string as if every toolchain produced it. What’s consistent across all of them is the underlying cause: the module simply isn’t there anymore at that path, so resolution fails.

Fix it: point custom reporters and coverage config at the new paths

A custom reporter importing from vitest/reporters

import type { Reporter } from "vitest/reporters"; // BROKEN: path removed in Vitest 5

export default class CustomReporter implements Reporter {
  onFinished(files) {
    console.log(`Ran ${files.length} test files`);
  }
}

import type { Reporter } from "vitest/node"; // FIXED: vitest/reporters -> vitest/node

export default class CustomReporter implements Reporter {
  onFinished(files) {
    console.log(`Ran ${files.length} test files`);
  }
}

A coverage provider importing from vitest/coverage

import type { CoverageProvider } from "vitest/coverage"; // BROKEN: path removed in Vitest 5

import type { CoverageProvider } from "vitest/node"; // FIXED: vitest/coverage -> vitest/node

The change is mechanical once you know the target: swap the specifier, leave the rest of the file untouched. The type and value exports themselves didn’t change shape in these two cases, only where they live.

Deprecated, not yet removed: three more packages to watch

Not every change in this area is an outright removal. The migration guide separately flags @vitest/runner and @vitest/ws-client as deprecated, not removed:

“The @vitest/runner and @vitest/ws-client packages are deprecated as of this release.” They “will no longer receive feature updates, but security fixes will continue to be backported.”

Deprecated still means installed and working today. Treat a dependency on either package as something to plan away from over time, not something that breaks on the next upgrade.

@vitest/browser-webdriverio changes ownership rather than disappearing. The guide documents that this provider now lives under the community-maintained vitest-community/vitest-webdriverio organization instead of Vitest’s own core packages. Anyone pinning the old package path should point at that fork going forward.

@vitest/expect is the subtlest of the three. Vitest 5 stops depending on it internally:

“vitest also no longer depends on @vitest/expect: the assertion code is bundled into vitest itself.”

Code that previously relied on @vitest/expect sharing runtime state with the rest of Vitest, rather than just using its type exports, should switch to importing assertions through the vitest entry point directly instead.

Confirmed version range

This site’s own vitest.config.ts is pinned to vitest@^3.0.0, so this exact resolution failure wasn’t reproducible against this repo’s own build; Vitest 5 isn’t installed here. Every claim above is attributed to Vitest’s own migration guide, current as of Vitest 5.0.0-beta.7 (2026-07-24). If you’re on an earlier 5.0 beta, re-check the guide directly, since a beta’s own documented removals can still shift before a stable release. Browse more posts like this in the Guides & Fixes archive, or follow the rest of this Vitest 5 migration series under the vitest tag.

Quick Answer

Vitest 5 flips clearMocks to default true: it now calls vi.clearAllMocks() before every test, clearing each mock’s call history while keeping its implementation. A suite expecting call counts to persist across tests starts failing with no code change. Set clearMocks: false to restore Vitest 4’s behavior, or stop relying on cross-test mock state.

Why mock call counts reset with no code change

This one doesn’t throw an error. There’s no stack trace to search for, which is exactly why it’s confusing to debug: a suite that passed yesterday starts failing today, and nothing in the diff explains why.

Vitest’s own migration guide states the change directly, in the section covering clearMocks’s new default:

clearMocks now defaults to true: Vitest calls vi.clearAllMocks() before every test, clearing the recorded history of every mock while leaving implementations intact.

That last clause matters. vi.clearAllMocks() clears each mock’s recorded calls, results, and instances, but it doesn’t touch the mock’s implementation the way vi.resetAllMocks() or vi.restoreAllMocks() would. A mock still returns whatever it was told to return. It just forgets that it was ever called.

The guide also flags where this bites hardest:

Tests that record calls outside of the test body (for example in a setup file, at the top level of a module, or in a beforeAll hook) are the most affected, because that history is cleared before the test that asserts on it runs.

A call made once in beforeAll and asserted on later, or a suite that deliberately counts calls cumulatively across a describe block, gets wiped before the assertion that expects to see it.

Fix it: restore the old default, or stop depending on it

Option 1: set clearMocks back to false

The fastest fix, and the right one if you have a lot of suites written against the old default and no time to audit every one of them right now:

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    // clearMocks not set - Vitest 4 default (false) let call history
    // BROKEN under Vitest 5: clearMocks now defaults to true instead
  },
});

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    clearMocks: false, // FIXED: restores the old default, call history persists across tests
  },
});

Option 2: rewrite the test to not depend on cross-test mock state

Vitest’s migration guide shows exactly what a test that relied on the old default looked like, and how it reads once the assumption is made explicit:

import { expect, test, vi } from "vitest";

const fn = vi.fn();

test("first", () => {
  fn();
  expect(fn).toHaveBeenCalledTimes(1);
});

test("second", () => {
  fn();
  // v4: the call from "first" was kept, so this was 2
  // v5: history is cleared before each test, so only this test's call counts
  expect(fn).toHaveBeenCalledTimes(1); // FIXED: asserts only this test's own call
});

A test that depends on another test’s mock history to pass is depending on execution order, which is fragile even outside of this specific default change. If you’re touching the suite anyway, this is the fix that actually removes the risk instead of papering over it with a config flag.

Confirmed version range

Documented in Vitest’s own current migration guide as an intentional Vitest 5.0 default-behavior change, in the section covering clearMocks’s new default. The current clearMocks config reference reflects the new default. This repository’s own vitest.config.ts is pinned to vitest@^3.0.0, so this default flip wasn’t independently reproduced against this project’s build; every claim above traces back to Vitest’s migration guide, not a local repro.

This pairs with Fix Vitest 5 vi.mock Top-Level Scope Error, another Vitest 5 mocking change that breaks suites with zero code changes. More fixes like this one are in the Guides & Fixes archive, and every Vitest post is tagged under vitest.

Quick Answer

Vitest 5 stops searching parent directories for a config file. Running vitest from a subdirectory that only inherited config from a parent folder in Vitest 4 now fails to find or apply it. Pass the config explicitly with vitest --config ../vitest.config.ts instead of relying on the old upward search, and use --dir to scope which files it discovers.

Why running vitest from a subdirectory stops finding config

Vitest 4 walked up the directory tree looking for a config file if the current working directory didn’t have one. That made a certain style of monorepo or CI script “just work”: cd packages/api && vitest would pick up a vitest.config.ts sitting at the repo root, even though nothing in that subdirectory pointed at it.

Vitest’s own migration guide states the change plainly, in the section covering config file lookup:

Vitest no longer searches parent directories for config files. If you previously relied on running vitest from a subdirectory while using a config file from a parent directory, pass the config explicitly and scope test discovery with --dir.

The guide’s own example shows exactly what changes:

$ cd subdir && vitest

$ cd subdir && vitest --config ../vitest.config.ts

The command that used to resolve config by walking upward now just doesn’t find one, because that walk no longer happens. Whatever Vitest does when no config file is found (fall back to defaults, or fail outright) depends on the rest of your setup, but either way it isn’t running with the config you meant it to use.

Fix it: pass the config path (and scope) explicitly

Option 1: pass —config directly

The direct fix, matching the guide’s own example. Point the command at the config file explicitly instead of hoping it gets found:

{
  "scripts": {
    "test": "cd packages/api && vitest"
  }
}

{
  "scripts": {
    "test": "cd packages/api && vitest --config ../../vitest.config.ts --dir ."
  }
}

--dir scopes which directory Vitest treats as the root for discovering test files, which matters once you’re pointing --config somewhere outside the current directory. Confirm the exact --dir semantics against Vitest’s own CLI reference for your version before copying this into a script wholesale, since flag behavior can shift between beta releases faster than stable config surface does.

Option 2: give the subdirectory its own config file

If the subdirectory’s tests don’t genuinely need to share every setting from the parent config, moving (or adding) a vitest.config.ts directly in that directory sidesteps the whole issue. Vitest still checks the current working directory by default; only the upward search into parent directories is gone. A config file sitting right next to the code it tests never depended on that search in the first place.

Confirmed version range

Documented in Vitest’s own current migration guide as an intentional Vitest 5.0 change, in the section covering config file lookup. This repository’s own vitest.config.ts is pinned to vitest@^3.0.0, so this behavior wasn’t independently reproduced against this project’s build; every claim above traces back to Vitest’s migration guide, not a local repro.

More fixes like this one are in the Guides & Fixes archive, and every Vitest post is tagged under vitest. If your upgrade is also hitting removed test options, see Fix Vitest 5 test.sequential Removed Error.

Quick Answer

Vitest 5’s expect.poll() throws expect.poll() function didn't resolve in time. when the polled callback or its assertion doesn’t settle within the configured timeout. Vitest 4 let a late-resolving poll still succeed if it eventually settled after the deadline passed. Fix it by using the callback’s new signal parameter to cancel in-flight work on timeout, or by raising timeout only if the condition genuinely needs more time.

Why a poll that used to pass now throws

Vitest’s migration guide documents this under “expect.poll Fails When It Times Out”:

expect.poll now rejects when its callback, or the polled assertion, does not settle within timeout.

The guide gives the exact error text a reader will see, depending on which part times out:

expect.poll() function didn’t resolve in time.

expect.poll() assertion didn’t resolve in time.

The first form fires when the polled callback itself never settles; the second fires when the callback settles but the assertion chained onto it (.toBe(200), for example) never does.

expect.poll() exists to retry a callback repeatedly until an assertion against its return value passes, which is the standard pattern for waiting on a condition that becomes true asynchronously, like an HTTP status flipping to 200 once a service finishes starting. In Vitest 4, the poll loop itself didn’t treat the timeout as a hard stop. If a slow callback or a slow assertion was still in flight when the deadline passed, it could keep going and still report success once it eventually settled, deadline or not.

Vitest 5 changes that to an active rejection. The moment timeout elapses without a settled, passing result, the poll stops and throws the error above instead of letting a late result count.

The new AbortSignal parameter

The same change adds a way to react to that timeout instead of just discovering it after the fact. Vitest’s guide shows the callback now receiving a signal:

await expect
  .poll(
    async ({ signal }) => {
      const response = await fetch("/api/status", { signal });
      return response.status;
    },
    { timeout: 1000 },
  )
  .toBe(200);

That signal is a standard AbortSignal that aborts the moment the poll’s timeout elapses. Passing it into fetch (or any API that accepts an AbortSignal) means the in-flight request actually stops instead of continuing to run in the background after Vitest has already decided the poll failed. Without it, a timed-out poll still leaves that last request hanging until it resolves or errors on its own, which wastes time and can leave dangling handles between tests.

Fix it: don’t just chase the timeout number

// BROKEN: no signal, so a timed-out request keeps running in the background
await expect
  .poll(async () => {
    const response = await fetch("/api/status");
    return response.status;
  })
  .toBe(200);

// FIXED: signal cancels the in-flight fetch the moment the poll times out
await expect
  .poll(
    async ({ signal }) => {
      const response = await fetch("/api/status", { signal });
      return response.status;
    },
    { timeout: 5000 }, // raised only because this endpoint genuinely takes longer to come up
  )
  .toBe(200);

Confirmed version range

This error string and behavior change are documented in Vitest’s own current migration guide, under “expect.poll Fails When It Times Out,” as an intentional Vitest 5 change, corroborated as in-window against the beta release available at research time (v5.0.0-beta.7). This repo’s own vitest.config.ts is pinned to vitest@^3.0.0 and doesn’t use expect.poll(), so this exact error wasn’t independently reproducible against this repo’s own test suite. Treat the error text above as quoted directly from Vitest’s primary source, not a first-party reproduction. If you’re also seeing tests fail on a forgotten await, see Fix Vitest 5 Unawaited Async Assertion Error — the other Vitest 5 change to how async assertion timing is enforced. Browse more posts like this in the Guides & Fixes archive.

Quick Answer

Vitest 5 changes test.projects inheritance: the extends option now defaults to true, so every inline project automatically picks up the root’s Vite plugins and resolve.alias. Arrays merge instead of override, so root setupFiles get appended, not replaced. A project relying on the old isolated-by-default behavior now needs extends: false explicitly.

Why inline projects suddenly inherit everything

test.projects lets a single Vitest run cover multiple logically separate test configurations, unit tests with one setup, integration tests with another, inside one vitest.config.ts. In Vitest 4, an inline project entry in that array didn’t automatically pick up the root configuration. If you wanted a project to share the root’s Vite plugins or setupFiles, you had to wire that up yourself.

Vitest’s migration guide documents that Vitest 5 flips the default:

“The extends option now defaults to true: every project defined as an inline configuration in test.projects inherits all options from the root configuration, including Vite options like plugins or resolve.alias.”

An inline project that previously ran in isolation from the root now automatically picks up its Vite plugins, its alias resolution, and more, without any config change on the project’s side.

That’s the actual break. Nothing about the project’s own config object changed. What changed is what Vitest does with it by default, so a project written under the old assumption can start behaving differently the moment the vitest dependency bumps to 5, with no diff to point at in the project’s own definition.

What “inherits” means here: merged arrays, not a full copy

Inheritance isn’t a blunt overwrite. The guide is specific about how array-valued options combine:

“Arrays are merged, not overridden: if the root config defines setupFiles, the project’s own setupFiles are appended to the inherited ones.”

A project that defines its own setupFiles doesn’t lose them and doesn’t silently swap to only the root’s; both lists run, root first, then the project’s own.

That matters for diagnosing the symptom in practice. If a root-level setup file registers something global, a test double, a database connection, an environment variable, that global effect now shows up inside every inline project too, even one that never referenced that setup file itself. The project’s tests aren’t broken by a bug in their own code; they’re picking up state from a setup file they never opted into, because the project object itself never said otherwise.

Fix it: opt back into isolation explicitly

export default defineConfig({
  plugins: [tsconfigPaths()],
  test: {
    setupFiles: ["./setup.global.ts"],
    projects: [
      {
        test: {
          name: "unit",
          // BROKEN under Vitest 5: this project now also runs
          // setup.global.ts automatically, which it was never meant to.
          setupFiles: ["./setup.unit.ts"],
        },
      },
    ],
  },
});

export default defineConfig({
  plugins: [tsconfigPaths()],
  test: {
    setupFiles: ["./setup.global.ts"],
    projects: [
      {
        extends: false, // FIXED: opts out of the new default inheritance
        test: {
          name: "unit",
          setupFiles: ["./setup.unit.ts"], // runs alone again, as intended
        },
      },
    ],
  },
});

The fix adds exactly one key. extends: false is the exact opt-out the migration guide names, and it applies per project, so a config with several inline projects can mix defaults: leave the ones that genuinely want the root’s plugins and aliases alone, and set extends: false only on the one meant to stay isolated.

A related change: one shared Vite server, not one per project

The same rework carries a second effect worth knowing about even though it isn’t usually breaking on its own:

“Inline projects that don’t modify the Vite config now reuse the Vite server of the config that declares them instead of resolving a new Vite config and creating a new server per project.”

That’s a performance change, not a correctness one, fewer redundant dev servers spun up for projects that share an identical Vite setup, but it’s the same underlying rework that produced the inheritance default above, so it’s worth knowing both changes shipped together.

Confirmed version range

This site’s own vitest.config.ts pins vitest@^3.0.0 and doesn’t define any test.projects entries, so this exact inheritance change wasn’t independently reproducible against this repo’s own config; Vitest 5 isn’t installed here. The behavior described above is attributed directly to Vitest’s migration guide, under the guide’s section covering this exact default-inheritance change for inline projects, current as of Vitest 5.0.0-beta.7 (2026-07-24). Audit every inline project in your own config for an implicit isolation assumption before upgrading, rather than discovering the overlap through a failing test. Browse more posts like this in the Guides & Fixes archive, or follow the rest of this Vitest 5 migration series under the vitest tag.

Quick Answer

Vitest 5 removes test.sequential, describe.sequential, and the sequential boolean option outright, not deprecated-with-warning. Vitest’s migration guide doesn’t document a specific runtime error for calling them; expect a type error or a plain “is not a function” failure, since it’s no longer a recognized API surface. Replace test.sequential('name', fn) with test('name', { concurrent: false }, fn).

Why this got removed instead of deprecated

concurrent and sequential described the same thing from two directions. A test was either allowed to run concurrently with its siblings or it wasn’t, and sequential only ever meant “not concurrent.” Vitest’s own migration guide states the removal directly, in the section covering these removed options:

Vitest 5.0 removes the deprecated test.sequential, describe.sequential, and sequential test options. Use concurrent: false when you need a test or suite to opt out of inherited or globally configured concurrency.

The redundancy is what made this a removal candidate rather than a permanent pair of options. The GitHub issue that proposed this change lists out the full set of ways Vitest let you express test concurrency, including combinations like { sequential: false }, and points out that having two independent flags that can contradict each other (is { concurrent: false, sequential: false } concurrent or not?) creates internal churn and reader confusion for no real benefit. Collapsing to one flag, concurrent, removes the ambiguity entirely.

Fix it: switch to concurrent: false

Vitest’s migration guide documents the exact replacement pattern for all three removed forms. Each is a mechanical rename, not a behavior change.

test.sequential("example", async () => {
  /* ... */
}); // BROKEN: test.sequential no longer exists in Vitest 5

test("example", { concurrent: false }, async () => {
  /* ... */
}); // FIXED: same effect, using the surviving option

describe.sequential follows the identical pattern:

describe.sequential("suite", () => {
  /* ... */
}); // BROKEN: describe.sequential no longer exists in Vitest 5

describe("suite", { concurrent: false }, () => {
  /* ... */
}); // FIXED: same effect, using the surviving option

If your code used the sequential option-object key instead of the chained method, the same replacement applies directly to that key:

test("example", { sequential: true }, async () => {
  /* ... */
}); // BROKEN: sequential key no longer recognized

test("example", { concurrent: false }, async () => {
  /* ... */
}); // FIXED: negate the surviving flag instead

Search your suite for .sequential( and sequential: before you upgrade, not after. Every match needs this exact rename, and there’s no runtime compatibility shim carrying the old name forward.

Confirmed version range

Documented in Vitest’s own current migration guide as an intentional Vitest 5.0 removal, in the section covering the removed sequential options. Corroborated by vitest-dev/vitest#10180, the issue that proposed consolidating concurrency into the single concurrent flag. This repository’s own vitest.config.ts is pinned to vitest@^3.0.0, so this removal wasn’t independently reproduced against this project’s build; every claim above traces back to Vitest’s migration guide and the linked issue, not a local repro.

More fixes like this one are in the Guides & Fixes archive, and every Vitest post is tagged under vitest. If your suite is also hitting the hoisted-mocking change in the same upgrade, see Fix Vitest 5 vi.mock Top-Level Scope Error. Running vitest from a subdirectory in the same upgrade? See Fix Vitest 5 Config Not Found in Parent Directory.

Quick Answer

Vitest 4 special-cased toThrow('') to match only an empty error message. Vitest 5 removes that special case: an empty string now behaves like any substring, and it’s “contained in every message.” So toThrow('') silently matches any thrown error. Fix it with toThrow(/^$/) for an exact match, or toThrow() if you meant “did it throw.”

Why an empty string used to be a special case

toThrow() (and its alias toThrowError()) accepts a string argument and checks whether the thrown error’s message contains it as a substring. That’s normal, expected matcher behavior for every non-empty string you’d pass it. An empty string was always the edge case, because an empty substring is trivially present inside any string at all, including one that’s completely unrelated to what the test author meant to check.

Vitest’s migration guide confirms Vitest 4 carved out an explicit exception for exactly this reason:

“In Vitest 4 an empty string was special-cased to the /^$/ pattern, so it matched only an error whose message was empty.”

That special case made toThrow('') behave the way most people reading it would assume: it asserted the error had no message at all, not “the error had any message whatsoever.”

Vitest 5 removes that special case. The guide states the new behavior plainly:

“toThrow now behaves like any other substring, and an empty string is contained in every message.”

Nothing distinguishes an empty-string argument from any other string argument anymore, and an empty string is a substring of every possible string, including one with no message and one with a hundred-character message.

Why this is the dangerous kind of breaking change

Most breaking changes throw something: a removed API throws a resolution error, a stricter check throws a new failure. This one doesn’t. A test written as expect(fn).toThrow('') compiles, runs, and reports green under Vitest 5, exactly like it did under Vitest 4. The difference is what that green result actually means.

Under Vitest 4, that assertion meant “this function throws, and the error message is empty.” Under Vitest 5, the same line means “this function throws,” full stop, regardless of what the message says or whether there even is one. A test suite can upgrade to Vitest 5, pass every test, and quietly lose the specificity of every toThrow('') assertion it contains, with no failing test, no console warning, and no diff in the test file itself to flag it.

Fix it: assert what you actually meant

Case 1: you meant “the error has no message”

test("throws with no message on empty input", () => {
  expect(() => parseConfig("")).toThrow(""); // BROKEN: now matches any message, not just an empty one
});

test("throws with no message on empty input", () => {
  expect(() => parseConfig("")).toThrow(/^$/); // FIXED: explicit regex, matches only an empty message
});

Case 2: you meant “it throws, I don’t care what the message says”

test("throws on malformed config", () => {
  expect(() => parseConfig("{{{")).toThrow(""); // BROKEN: reads like a message check, isn't one
});

test("throws on malformed config", () => {
  expect(() => parseConfig("{{{")).toThrow(); // FIXED: no argument, says exactly what it checks
});

The second case is the more common one in practice. A lot of toThrow('') call sites were never trying to assert an empty message at all; they were written by someone who wanted “does it throw” and reached for an empty string as a stand-in for “any message,” which happened to work under the old special case by coincidence rather than by design. Dropping the argument entirely says what the test actually checks.

Confirmed version range

This site’s own vitest.config.ts pins vitest@^3.0.0, so this behavior change wasn’t independently reproducible against this repo’s own test run; Vitest 5 isn’t installed here. The matcher behavior described above is attributed directly to Vitest’s migration guide, under its section titled toThrow("") Matches Any Error Message, current as of Vitest 5.0.0-beta.7 (2026-07-24). Grep your own suite for toThrow('') and toThrowError('') before upgrading rather than waiting to notice a coverage gap after the fact. Browse more posts like this in the Guides & Fixes archive, or follow the rest of this Vitest 5 migration series under the vitest tag.

Quick Answer

Vitest 5 fails a test outright when an async assertion like expect(promise).resolves.toBe(1) is called without await in front of it. Vitest 4 auto-awaited that same call at the end of the test and only printed a warning, so the test still passed. Fix it by adding the missing await in front of every resolves, rejects, or toMatchFileSnapshot assertion.

Why a passing test suddenly fails after upgrading

This isn’t a new bug Vitest 5 introduces. It’s an old bug Vitest 4 was quietly hiding. Vitest’s migration guide states it directly, under “Unawaited Asynchronous Assertions Fail the Test”:

Asynchronous assertions, like resolves, rejects and toMatchFileSnapshot, now fail the test if they are not awaited.

The guide’s own example makes the before-and-after explicit:

test("unawaited assertion", async () => {
  // v4: prints a warning, the test passes
  // v5: the test fails
  expect(promise).resolves.toBe(1);
  await expect(promise).resolves.toBe(1);
});

The mechanical reason this matters: resolves and rejects don’t run the comparison synchronously. Calling expect(promise).resolves.toBe(1) returns a Promise that has to settle before the assertion inside it actually runs. Skip the await, and the test function can finish and report success before that inner promise has resolved at all, which means the comparison it’s supposed to make might never happen before Vitest moves on.

Vitest 4 papered over that gap. It tracked pending assertion promises and auto-awaited them after the test body returned, so the check still ran, just late, with a console warning as the only sign anything was off. Vitest 5 removes that safety net and fails the test the moment it detects an assertion that was never awaited.

Why this is a real bug, not just stricter enforcement

A forgotten await on an async matcher is a latent bug regardless of which Vitest version is running it. If the promise the assertion checks actually rejects, or resolves to something other than what toBe expects, an unawaited assertion in Vitest 4 could still report a green test, because the warning goes to the console, not to the test’s pass/fail result, and nothing forces a developer to read console output on a passing CI run. Vitest 5 turns that same situation into a hard failure, which is the more honest outcome: a test that doesn’t actually verify what it claims to verify shouldn’t be counted as passing.

Fix it: add the missing await

The fix is almost always a single keyword. Find the assertion, add await:

test("resolves to the expected value", async () => {
  expect(fetchUser(1)).resolves.toEqual({ id: 1 }); // BROKEN: promise never awaited
});

test("resolves to the expected value", async () => {
  await expect(fetchUser(1)).resolves.toEqual({ id: 1 }); // FIXED: assertion runs before the test ends
});

Confirmed version range

This behavior change is documented in Vitest’s own current migration guide, under “Unawaited Asynchronous Assertions Fail the Test,” as an intentional Vitest 5 change, corroborated as in-window against the beta release available at research time (v5.0.0-beta.7). This repo’s own vitest.config.ts is pinned to vitest@^3.0.0, so this exact failure mode wasn’t independently reproducible against this repo’s own test suite. Treat the mechanics above as documented behavior from Vitest’s primary source, not a first-party reproduction. If you’re also hitting timing changes around expect.poll(), see Fix Vitest 5 expect.poll Timeout Error — a related but distinct Vitest 5 change to how long-running assertions are handled. Browse more posts like this in the Guides & Fixes archive.

Quick Answer

Vitest 5 throws this error when vi.mock(), vi.unmock(), or vi.hoisted() runs inside a function, describe, or test callback instead of at the top of the file:

1 call in “file.test.ts” was defined outside of the module’s top level scope

Move the call to module top level, or switch to vi.doMock()/vi.doUnmock(), which are not hoisted and can run anywhere.

Why the call throws instead of just warning

vi.mock(), vi.unmock(), and vi.hoisted() don’t run where they’re written. Vitest’s compiler transform lifts them to the very top of the file at parse time, before any other module-level code, regardless of how deeply they’re nested in the source. That’s what makes them useful for mocking a module before your own imports even resolve.

The problem is when the code around a hoisted call implies an order that isn’t the order it actually runs in. Vitest’s own migration guide states the change plainly, in its “Hoisted Mocking Calls” section:

vi.mock, vi.unmock, and vi.hoisted are hoisted to the top of the file and run before any surrounding code. Calling them inside a function, block, or describe/test callback previously only logged a warning. Vitest 5.0 now throws, because the call does not execute where it is written.

Vitest 4 tolerated the mismatch and just printed a warning. Vitest 5.0 stops tolerating it. The reported error names the exact offending call and its location, quoted here from the guide’s own example:

1 call in "calculator.test.ts" was defined outside of the module's top level scope:

- vi.mock("./calculator") at calculator.test.ts:2:3

Although it appears nested, it will be hoisted and executed before anything
in this file. Move it to the top level to reflect its actual execution order.

Fix it: move the call to module top level

The guide’s own example shows the pattern directly. A vi.mock() call sitting inside a describe block gets hoisted anyway, so writing it there is misleading even before Vitest 5 makes it an error.

import { describe, expect, it, vi } from "vitest";

describe("calculator", () => {
  vi.mock("./calculator"); // BROKEN: nested, throws in Vitest 5
  // ...tests
});

import { describe, expect, it, vi } from "vitest";

vi.mock("./calculator"); // FIXED: written at module top level, matches hoisted order

describe("calculator", () => {
  // ...tests
});

The fix is mechanical: pull every vi.mock(), vi.unmock(), and vi.hoisted() call out to the top of the file, outside any describe or test callback. Nothing about the mock’s behavior changes. Only its written position moves to match where it already ran.

When you actually need a mock set up at runtime

Sometimes the whole point is deciding what to mock inside a test, based on something you only know at runtime, not at parse time. Hoisting a call there doesn’t just look wrong, it’s the wrong tool. Vitest’s migration guide is explicit that the hoisted variants have a non-hoisted counterpart built for exactly this:

The dynamic variants vi.doMock and vi.doUnmock are not hoisted and may still be called anywhere.

import { describe, expect, it, vi } from "vitest";

describe("calculator", () => {
  it("uses a mocked add() only for this test", async () => {
    vi.doMock("./calculator", () => ({ add: () => 42 })); // OK: not hoisted, runs in place
    const { add } = await import("./calculator");
    expect(add(1, 2)).toBe(42);
  });
});

vi.doMock() and vi.doUnmock() take effect only for imports that happen after they run, so pair them with a dynamic import() inside the test rather than a static top-of-file import. That’s a real difference from vi.mock(), not a cosmetic one. If your suite genuinely needs per-test mock variation, this is the supported path, not a workaround.

Confirmed version range

This is documented in Vitest’s own current migration guide as an intentional Vitest 5.0 change, in the section covering hoisted mocking calls. This repository’s own vitest.config.ts is pinned to vitest@^3.0.0, so this behavior wasn’t independently reproduced against this project’s build; every claim above is sourced directly from Vitest’s migration guide, not a local repro. Check the vi.hoisted API reference if you’re touching hoisted setup logic beyond vi.mock/vi.unmock, since the same top-level rule applies there too.

If your suite also leans on clearMocks, see Fix Vitest 5 clearMocks Breaking Mock State for the other Vitest 5 mocking default that changes silently on upgrade. More fixes like this one are in the Guides & Fixes archive, and the full list of Vitest posts is tagged under vitest.

Quick Answer

Use GitHub Agentic Workflows when you want a reasoning-based repo task, issue triage, CI failure analysis, documentation updates, automated from a natural-language Markdown file instead of hand-written YAML plus your own LLM glue code and security boundary. Skip it for simple deterministic automation; plain Actions YAML is simpler and doesn’t need an AI engine, its secrets, or a sandboxed execution layer.

What this replaces

Automating a reasoning-based repo task, deciding whether an issue is a duplicate, summarizing why a CI run failed, drafting a documentation update, used to mean hand-writing bespoke Actions YAML and whatever custom code called an LLM API, with no standard security boundary around what that code could read, write, or execute inside CI. Every team building this kind of automation solved the sandboxing and output-validation problem themselves, if they solved it at all.

GitHub’s changelog, published 2026-06-11:

“GitHub Agentic Workflows is now in public preview. With agentic workflows, you can automate reasoning-based tasks like issue triage, CI failure analysis, and documentation updates by leveraging coding agents inside GitHub Actions.”

Workflows are authored as plain-language Markdown, not YAML directly:

“You define your automation using natural language Markdown files, and GitHub Agentic Workflows compiles them into standard Actions YAML.”

Structural Comparison Matrix

Install the CLI extension and scaffold a workflow

GitHub Agentic Workflows ships as a gh CLI extension, not a built-in gh subcommand:

gh extension install github/gh-aw

Running gh aw compile produces a .lock.yml file containing the standard Actions YAML the Markdown source compiled into, which is the file Actions actually runs, not the Markdown itself. From a repo’s root, the wizard scaffolds a first workflow interactively:

gh aw add-wizard githubnext/agentics/daily-repo-status

The wizard’s reference argument uses an OWNER/REPO/WORKFLOW-NAME format, pulling a starter template, in this case a daily repo status check, from GitHub’s own githubnext/agentics collection of prebuilt workflows. It walks through checking repository prerequisites, choosing an AI engine (Copilot by default, or Claude Code, OpenAI Codex, Google Gemini, or Pi instead), and setting up whichever secret that engine needs.

Where the workflow actually lives

The scaffolded workflow is a Markdown file at .github/workflows/<workflow-name>.md, for example .github/workflows/daily-repo-status.md. After editing that file’s frontmatter or body, recompile it so the change actually takes effect:

gh aw compile

That command regenerates the matching .lock.yml file, the version Actions actually executes. Both files belong in the repo: the Markdown source, because it’s what a human edits, and the compiled .lock.yml, because Actions never compiles Markdown on its own at run time.

Would this help this site’s own workflows?

Not yet, in any concrete way worth claiming. This site’s .github/workflows/ci.yml runs deterministic build, lint, and test steps, not the kind of reasoning-based task, issue triage, CI failure summarization, this feature targets. A plausible future use here would be automating triage on reader-submitted issues or summarizing why a Lighthouse CI budget failed, but nothing in this repo uses agentic workflows today, and this preview’s public-preview status is reason enough to wait before wiring it into a pipeline that gates a real deploy.

Confirmed version

Sourced from GitHub’s changelog entry announcing the public preview, published 2026-06-11, and corroborated against GitHub’s Agentic Workflows quickstart for the install and scaffolding commands above. Browse more posts like this in the Dev Tools archive.

Quick Answer

As of 2026-06-26, any default-branch cache scope only gets a read-only token when the triggering event doesn’t require write access to the repo, pull_request_target, issue_comment, and fork-originated workflow_run cascades among them. push, schedule, workflow_dispatch, and repository_dispatch keep read-write access. If a workflow used to save cache from one of the now-restricted triggers, split cache-saving into a separate trusted-trigger workflow.

The attack this closes

The Actions cache was read-write for every triggering event before this change, including events anyone can cause without holding write access to the repo. pull_request_target is the clearest example: it runs with the base repo’s permissions, but the event itself can be caused by opening a pull request from a fork, something an outside contributor can always do.

That combination let an external contributor poison a default-branch cache entry, a dependency artifact, a build output, anything a later job would restore and trust. GitHub’s own changelog names the consequence directly:

“a trusted workflow such as push or schedule would later restore” the poisoned entry, closing “a path to run arbitrary code and exfiltrate production secrets.”

The fix, effective 2026-06-26, scopes cache-token write access to trust level of the triggering event rather than treating every event the same.

Which events still get read-write, and which don’t

The line GitHub draws is straightforward:

“…can be triggered without write permissions to the repository.”

Anything an outside contributor can cause on their own, no maintainer action required, loses write access to the default branch’s cache scope. Anything that requires a maintainer or a scheduled job to fire keeps it.

Structural Comparison Matrix

Restructuring a workflow that saved cache from an untrusted trigger

If a pull_request_target (or issue_comment, or fork-triggered workflow_run) job in your repo relies on actions/cache’s save action or a post-job automatic save, it now silently stops writing rather than erroring loudly, check for stale cache hits as the symptom, not a clear failure message.

The fix is to split cache population from cache use across two workflows:

# Trusted trigger: read-write cache access
name: Populate build cache
on:
  push:
    branches: [main]
  schedule:
    - cron: "0 6 * * *"

jobs:
  populate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/cache@v4
        with:
          path: node_modules
          key: deps-${{ hashFiles('package-lock.json') }}
      - run: npm ci

# Untrusted trigger: read-only cache access, restore only
name: PR check
on:
  pull_request_target:

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/cache/restore@v4
        with:
          path: node_modules
          key: deps-${{ hashFiles('package-lock.json') }}
      - run: npm ci # falls back to a real install on a cache miss

The pull_request_target workflow now only restores, using actions/cache/restore instead of the combined actions/cache action, since it never has permission to write back. The trusted push/schedule workflow owns keeping the cache current.

Source

github.blog/changelog: Read-only Actions cache for untrusted triggers (2026-06-26). Browse more posts like this in the Dev Tools archive.

Quick Answer

Layer a custom runner image when a shared base image (common tooling, base OS config) needs team-specific dependencies added on top, instead of every team maintaining its own flat, duplicated image. Add a conditional if: to the snapshot keyword when you only want a new image version generated on some builds, like main-branch merges, not every tag build or pull request.

What was flat and duplicated before

Building a custom runner image for GitHub-hosted larger runners used to mean building it flat, independently, every single time. Picture a platform team maintaining one image with the org’s baseline toolchain, and three product teams each needing their own extra packages on top of it. Before this release, those three teams had exactly two bad options: each one duplicates the platform team’s build from scratch and maintains its own separate copy, or everyone shares a single image that grows more bloated with every team’s unrelated dependencies added to it.

GitHub’s changelog, published 2026-06-18:

“Build custom images on top of other custom images”

The docs describe how the layering itself is configured:

“You can start from an existing custom image as the base, enabling layered image workflows.”

That base-image selection happens in the GitHub UI, not in a workflow file, specifically in the Image dropdown when you configure the image-generation larger runner that will build the new, derived image.

GitHub’s docs are specific about how a derived image’s age clock works:

“the derived image inherits the expiration timeline of its base image. The maximum version age is calculated from when the base custom image was built, not when the derived image was created.”

Structural Comparison Matrix

Generate an image version with snapshot

The snapshot keyword, added to a workflow job, is what actually triggers image generation. In its simplest form, it’s a string naming the image:

snapshot: my-custom-image

The mapping form adds an explicit version pattern and, with if:, a condition that decides whether this run generates a new image version at all:

snapshot:
  if: ${{ ! startsWith(github.ref, 'refs/tags/') }}
  image-name: my-custom-image
  version: 2.*

That if: condition skips image creation for tag builds specifically, per GitHub’s own documentation, useful when a repo tags releases far more often than it actually needs a fresh runner image. version: 2.* tells GitHub to auto-increment the minor version under major version 2 (2.0.0, 2.1.0, and so on) each time a new image is generated, rather than requiring a hand-picked version string on every run.

Layer a team-specific image on a shared base

1. Build the shared base image first, on its own image-generation runner, with snapshot: targeting a name like org-base-image. This is the image every sub-team’s own image will start from.
2. Create a second image-generation larger runner for the team-specific build, and in that runner’s Settings, pick org-base-image in the Image dropdown as its starting point instead of a stock OS image.
3. Run a workflow job with its own snapshot: block on that runner, installing only the team’s extra dependencies on top of what the base image already has, and generating a new, derived image version.

jobs:
  build-team-image:
    runs-on:
      group: image-generation-runners
      labels: team-checkout-image-gen
    snapshot:
      if: ${{ ! startsWith(github.ref, 'refs/tags/') }}
      image-name: team-checkout-image
      version: 2.*
    steps:
      - name: Install team-specific dependencies
        run: ./scripts/install-team-deps.sh

The base-image selection itself, step 2 above, isn’t a YAML setting; it’s configured once when the image-generation runner is set up, which is why this walkthrough separates it from the snapshot: block that runs on every build.

Pair this with restricting who can use these runners

Layered images control what’s already installed on a runner before a job even starts. A separate June 2026 release, restricting GitHub-hosted runners to named runner groups, controls who can request a runner at all. The two changes solve different problems, but they show up on the same roadmap often: a team that’s already built a shared base image with per-team layers is a strong candidate for also routing those runners through named groups, so a team’s custom image is only reachable by the repos that actually need it.

Confirmed version

Sourced from GitHub’s changelog entry on layered custom runner images, published 2026-06-18, and corroborated against GitHub’s custom images how-to guide, which documents the base-image dropdown, the inherited expiration timeline, and the exact snapshot: syntax used above. Browse more posts like this in the Dev Tools archive.

Quick Answer

Use background: true plus wait, wait-all, or cancel when you need fine control, starting a service early and doing other work before waiting on it. Use the parallel keyword when you just want a group of independent steps to run together and have the job wait for all of them automatically. Both shipped 2026-06-25 and only apply within a single job.

What used to force artificial serialization

Every step in a GitHub Actions job has always run strictly in order, one finishing before the next starts. That’s fine when steps genuinely depend on each other, but it forces unnecessary waiting when they don’t: three independent build tasks that don’t share state, or a background service (a test database, a mock API) that a later step needs running but doesn’t need to wait on immediately.

GitHub’s changelog, published 2026-06-25, adds four new step-level keywords to fix that:

“background: true… runs a step asynchronously and immediately continues to the next step.”

“wait/wait-all… pauses execution until one or more named background steps complete. wait can target one or more specific background steps, while wait-all pauses until all prior background steps have completed.”

“cancel… gracefully terminates a background step when you no longer need it, enabling you to start long-running services with a background step.”

“parallel… takes a group of steps and converts them to background steps with a wait after, enabling you to easily run multiple steps in parallel.”

None of these change how a job is triggered or how jobs relate to each other. They’re new keys inside an existing steps: block, not a new job or workflow structure.

Structural Comparison Matrix

Add background steps to a job

A common case: a test suite needs a real database running, but starting it doesn’t need to block installing dependencies. Give the background step an id, mark it background: true, and reference that id later:

jobs:
  integration-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - name: Start test database
        id: test-db
        background: true
        run: docker run -d --name test-db -p 5432:5432 postgres:16

      - name: Install dependencies
        run: npm ci

      - name: Wait for test database
        wait: test-db

      - name: Run integration tests
        run: npm run test:integration

      - name: Stop test database
        cancel: test-db

npm ci starts running the moment docker run is dispatched, not after it finishes, since the database step already handed control back. The wait: test-db step is where the job actually pauses until the container is up, right before the tests that need it.

Group independent steps with parallel

For steps that have no order dependency on each other at all, wrapping them in parallel avoids hand-managing ids and wait steps:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - parallel:
          - name: Build frontend bundle
            run: npm run build:frontend
          - name: Build backend bundle
            run: npm run build:backend
          - name: Build docs site
            run: npm run build:docs

      - name: Package release
        run: npm run package

Would this help this site’s own CI?

This site’s .github/workflows/ci.yml runs its build job’s steps in strict sequence: install, lint, format check, Astro check, unit tests, build, then Playwright install and end-to-end tests. Lint, the format check, and the Astro check don’t depend on each other, only on npm ci finishing first, which makes them a real candidate for a parallel block once this repo adopts a runner fleet new enough to support it. The unit tests and the build step still need to stay sequential, since the end-to-end tests run against the built output.

Confirmed version

Sourced from GitHub’s changelog entry announcing the new step keywords, published 2026-06-25. Browse more posts like this in the Dev Tools archive.

Quick Answer

Use $/ when a workflow step, composite action, or reusable workflow call references an action defined in the same repository. It resolves to your workflow’s own repository at the exact commit currently running, so you skip the checkout step ./ needs and avoid the version drift a hardcoded ref causes. Requires GitHub Actions runner 2.336.0 or newer.

What $/ actually resolves to

Calling an action that lives in the same repo as the workflow used to force a choice between two imperfect options. A workspace-relative path like ./.github/actions/build-tool worked, but only after an explicit actions/checkout step ran first, since ./ resolves against files already sitting in the runner’s workspace. Or you hardcoded a version or tag on the reference, which then had to be bumped by hand every time the calling workflow’s own ref moved, and quietly drifted out of sync the moment someone forgot.

GitHub shipped a third option on 2026-07-30. From the changelog:

“A uses: value that starts with $/ resolves to your workflow’s own repository at the exact commit that is running, with no checkout required.”

The same entry explains why this matters for teams enforcing commit-SHA pinning on every action reference:

“Sibling actions and workflows automatically match the ref you are already running, so your internal references stay consistent even when callers pin to a full-length commit SHA.”

That second sentence is the real payoff. A shop that enforces SHA-only pinning on every action reference has historically found its own internal actions awkward to comply with, since someone had to hand-update that SHA every time the internal action changed. $/ sidesteps the whole problem because the resolution tracks the running commit automatically, with no separate SHA to keep current.

Structural Comparison Matrix

Add it to a workflow

Say a repo defines a composite action at .github/actions/setup-project/action.yml that other workflows in the same repo call to install dependencies and warm a cache. Before $/, calling it from another workflow meant checking out the repo first, then referencing the path:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: ./.github/actions/setup-project
      - run: npm run build

With $/, the checkout step is no longer required just to resolve the action reference:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: $/.github/actions/setup-project
      - run: npm run build

If the job also needs the repo’s files for the build itself, actions/checkout still belongs in the workflow, but it’s no longer there solely to make the internal action reference resolvable. The same substitution applies to a reusable workflow call:

jobs:
  call-shared-build:
    uses: $/.github/workflows/shared-build.yml
    with:
      target: production

This repo’s own workflows

This site’s own .github/workflows/ci.yml doesn’t define any custom composite actions or reusable workflows today, only calls to third-party actions like actions/checkout and actions/setup-node, so there’s nothing here to convert to $/ yet. The moment this repo’s CI grows a shared composite action, an internal cache-warming step or a build-and-test action reused across the build and deploy jobs, $/ is the version to reach for over a ./-plus-checkout pattern.

Confirmed version

Sourced from GitHub’s own changelog entry on the $/ syntax, published 2026-07-30, and corroborated against GitHub’s metadata syntax reference, which documents the same ./-equivalent behavior $/ extends. Browse more posts like this in the Dev Tools archive.

Quick Answer

Between 2026-06-11 and 2026-07-30, GitHub shipped 10 distinct changes to Actions: one real breaking default (actions/checkout v7 blocking fork PR checkouts under pull_request_target), a self-hosted runner version cutoff with an active brownout schedule, three new security controls (workflow execution allow-lists, bot-PR approval gating, read-only cache tokens on untrusted triggers), and five new capabilities (same-repo $/ action syntax, parallel step execution, restricted runner groups, layered custom runner images, and GitHub Agentic Workflows). If you run GitHub Actions at all, check the table below against your own .github/workflows/*.yml files before assuming nothing here applies to you.

GitHub Actions is the CI/CD platform behind this site’s own deploy pipeline (.github/workflows/ci.yml: lint, test, build, then deploy to Cloudflare Workers on every push to main). That gives real first-person standing to discuss at least the checkout-default and workflow-trigger changes directly — though, as every linked post below says plainly, several of these changes target infrastructure (self-hosted runners, Team/Enterprise runner groups) this site doesn’t actually run, and the honest answer there is “doesn’t apply here,” not a forced dogfooding story.

Structural Comparison Matrix

Every row is confirmed against GitHub’s own changelog entry for that change, not summarized from memory. Full mechanism, exact quoted text, and the fix live in each linked post below.

The 10 changes, in detail

1. actions/checkout v7 Blocks pull_request_target PRs: closes the classic “pwn request” hole where a workflow with real secrets checks out an attacker-controlled fork commit.
2. GitHub Actions: Upgrade Self-Hosted Runners by Jul 31: a minimum runner version (2.329.0+) and a rolling 30-day update window, enforced through escalating brownout windows.
3. Set Up GitHub Actions Workflow Execution Protections: a rulesets-based allow-list controlling who can trigger workflows and which events are permitted at all.
4. Approve Workflow Runs From github-actions[bot] PRs: bot-authored PRs can now trigger CI, but only after a collaborator explicitly approves the run.
5. GitHub Actions Cache Goes Read-Only on Untrusted Triggers: closes a cache-poisoning path where an external contributor could write to a default-branch cache scope.
6. Reference Same-Repo Actions With $/ Syntax: resolves a same-repo action to the exact running commit, no checkout step required.
7. Run GitHub Actions Steps in Parallel With background: background: true, wait, wait-all, cancel, and parallel bring real concurrency inside a single job’s step list.
8. Restrict GitHub-Hosted Runners to Named Runner Groups: Team/Enterprise admins can disable standard labels like ubuntu-latest org-wide and force named runner groups instead.
9. Build Custom GitHub Actions Runner Images in Layers: compose custom runner images on top of other custom images instead of duplicating a shared base.
10. Set Up GitHub Agentic Workflows in Actions: compiles natural-language Markdown into standard Actions YAML, sandboxed behind an Agent Workflow Firewall with read-only defaults.

Why this happened in one summer

GitHub ships Actions changes on a rolling basis, but June and July 2026 concentrated an unusual amount of security-hardening into a seven-week window: a real breaking default aimed squarely at the “pwn request” pattern, two more security controls closing adjacent gaps (cache poisoning, unapproved bot-triggered runs), and a version-enforcement push for self-hosted infrastructure — alongside a separate cluster of new capability (parallel steps, same-repo action syntax, agentic workflows) that reads more like a normal feature cadence. None of the dates or quoted text above are estimated; every one traces to GitHub’s own changelog, cross-checked per cluster against the individual changelog post and, where one exists, GitHub’s own docs page for that feature.

Browse the rest of the Dev Tools archive for more CI/CD and Cloudflare Workers coverage.

Quick Answer

GitHub now enforces a minimum version for self-hosted Actions runners, and every runner has to pick up each new release inside a rolling 30-day window to stay compliant. Full enforcement starts 2026-07-31 for GitHub Enterprise Cloud with Data Residency and 2026-09-25 for standard GitHub Enterprise Cloud, preceded by four weeks of escalating brownout windows. Below the minimum, your runner won’t register or run jobs. Check your version now.

What’s actually enforced, and when

GitHub’s changelog states the version floor directly:

“The runner must be on version 2.329.0 or later.”

A second, separate requirement rides alongside it:

“The runner must stay up to date by installing each new runner release within 30 days of its publication.”

That second rule is a rolling window, not a one-time bump. A runner that’s on 2.329.0 today but skips the next few releases can drift back out of compliance a few months from now.

Runners with auto-update enabled satisfy the 30-day rule without anyone touching them, since GitHub’s own guidance confirms auto-update installs each release well inside that window. Manually managed runners are the ones actually at risk here.

Enforcement isn’t a single flip-the-switch date. It rolls out as four weeks of brownout windows, each one a four-hour block scheduled for late morning through early afternoon Eastern time, progressively expanding in scope: early windows only block new runner registrations during that slot, later windows also start blocking job execution on outdated runners during the window. Full, permanent enforcement follows the brownout schedule: 2026-07-31 for GitHub Enterprise Cloud with Data Residency, 2026-09-25 for standard GitHub Enterprise Cloud.

Structural Comparison Matrix

Checking and upgrading your runner version

Run this on the machine hosting the self-hosted runner to see what it’s currently on:

# From the runner's install directory
cat .runner_version 2>/dev/null || ./config.sh --version

If it reports anything below 2.329.0, or you don’t know when it last updated, upgrade it. GitHub Actions runners support auto-update by default unless it was explicitly disabled; check the runner service configuration first:

# Check whether auto-update is disabled for this runner
cat .runner | grep -i "disableupdate"

If auto-update is off, or you manage runners at a scale where you don’t want to rely on it, download and install the current release directly from the runner releases page, then restart the runner service so it picks up the new binary:

# Example for a Linux x64 runner - use the current release asset URL
curl -o actions-runner-linux-x64.tar.gz -L \
  https://github.com/actions/runner/releases/download/v2.329.0/actions-runner-linux-x64-2.329.0.tar.gz
tar xzf ./actions-runner-linux-x64.tar.gz
sudo ./svc.sh stop
sudo ./svc.sh start

At fleet scale, script the version check across every self-hosted runner group before the brownout windows start rather than finding out one at a time when a job silently stops queuing.

Does this affect this site’s own workflows?

No, and it’s worth saying so plainly rather than forcing a first-person angle that isn’t real. This site’s .github/workflows/ci.yml runs entirely on GitHub-hosted ubuntu-latest runners for both the build and deploy jobs, never a self-hosted runner. The enforcement covered here is scoped specifically to self-hosted runner registration and job execution; GitHub-hosted runners are versioned and managed by GitHub itself and sit outside this change entirely.

This cluster is still worth knowing if you run Actions at scale with your own infrastructure, self-hosted runners are common wherever a team needs specific hardware, network access, or licensing that GitHub-hosted runners can’t provide. If that’s your setup, the brownout schedule is the part most teams miss: it’s already running in the weeks before full enforcement, not a future date you can safely ignore until it arrives.

A separate but related change lets you reference same-repository actions with a new $/ syntax, which requires Actions runner 2.336.0 or later, a different, higher version floor than the 2.329.0 registration minimum covered here. Don’t conflate the two version requirements if you’re checking both.

Source

GitHub’s changelog entry on the self-hosted runner version cutoff (2026-06-12). Browse more posts like this in the Dev Tools archive.

Quick Answer

Workflow execution protections (public preview, 2026-06-18) add an allow-list layer in front of every GitHub Actions workflow: actor rules control who can trigger a run, event rules control which trigger types are permitted at all. Configure it under Settings → Actions → Policies at the repository, organization, or enterprise level. Use evaluate mode first to see what a rule would block before enforcing it.

The gap this closes

Before this feature, anyone with write access to a repository could modify a workflow file to run arbitrary code with that repo’s secrets, and any event GitHub Actions supports (push, pull_request_target, workflow_dispatch, and the rest) could trigger a workflow with nothing standing in front of it. There was no repo-level or org-level control over who was allowed to cause a workflow to run, or which event types were even legitimate for a given repo’s actual usage pattern.

GitHub’s changelog describes the fix plainly:

“Workflow execution protections are now in public preview for GitHub Enterprise, organizations, and repositories” and let you “define an allow list that controls who can trigger GitHub Actions workflows and which events are permitted to run them.”

The feature is “built on the GitHub rulesets framework,” which means it inherits rulesets’ existing concepts, including an evaluate mode that reports exactly what a rule would have blocked without actually stopping any runs, so you can roll a new policy out and check its real-world impact before switching it to active enforcement, rather than introducing a parallel permissions system to learn from scratch.

Actor rules vs. event rules

The two rule types are independently configurable, and most real policies use both together.

Actor rules control who can trigger a workflow at all. Straight from GitHub’s own description:

“Individual users, repository roles (e.g., Read, Maintain, and Admin), GitHub Apps, Copilot, and Dependabot.”

That’s the piece that separates “who can push code” from “who can cause a workflow to execute,” a distinction that didn’t exist as an enforceable setting before.

Event rules control which trigger types are permitted, regardless of who fires them. pull_request_target is the one worth allow-listing carefully; ordinary triggers like push and workflow_dispatch are lower risk, and pull_request sits somewhere between the two depending on what the workflow actually does. A repo that has no legitimate reason to ever run a workflow off pull_request_target can block that event type outright, independent of who’s involved.

Structural Comparison Matrix

Setting up a policy

This lives in a new “Policies” section under Actions settings, layered on rulesets:

1. Navigate to the right level. For a single repository: Settings → Actions → Policies. For an organization-wide rule: the organization’s own Settings → Actions → Policies, which can apply across every repo in the org.

2. Create a new ruleset scoped to workflow execution. Give it a name and decide whether it targets specific repositories (via repository custom properties, at the org/enterprise level) or the whole scope you’re configuring it at.

3. Add actor rules. Start narrow: allow specific repository roles (Write, Maintain, Admin) or specific GitHub Apps, rather than defaulting to “everyone with write access.”

4. Add event rules. List only the trigger events your workflows actually use. If nothing in the repo legitimately needs pull_request_target, don’t allow-list it, even if no current workflow uses it; this closes the door on someone adding one later without review.

5. Set the ruleset to evaluate mode first, rather than jumping straight to enforcement. Let it run for a normal work cycle (a week is reasonable) and review what it would have blocked.

6. Switch to active enforcement once evaluate mode shows no unexpected blocks against real usage.

Does this apply to a repo like this site’s?

Yes, and this is one of the changes in this series where a single repository genuinely doesn’t need an Enterprise plan or an organization admin to benefit. Per GitHub’s own docs, workflow execution protections are configurable “at the enterprise, organization, and repository level,” so a solo-maintained repo can opt in through its own Settings → Actions → Policies the same way an org-wide policy would be configured, just scoped to one repository instead of many.

Source

GitHub’s changelog entry introducing this allow-list feature (2026-06-18), corroborated by GitHub’s own docs page on the feature. Browse more posts like this in the Dev Tools archive.

Quick Answer

Zapier Functions shuts down entirely on 2026-09-01. Its replacement, Code by Zapier, runs on a different runtime with no requests library, so plain HTTP calls need to be rewritten using fetch. The one exception: Zapier’s own migration guide says not to use fetch for authenticated calls, those have to go through an API by Zapier connection instead.

Why this isn’t a find-and-replace

Zapier Functions let you write Python code with the requests library available for outbound HTTP calls, inside Zapier’s own hosted runtime, with a five-minute max execution time. Zapier’s Help Center confirms the shutdown date plainly, in its migration guide updated 2026-07-13:

“Zapier Functions is being deprecated on September 1, 2026”

Code by Zapier is positioned as the direct replacement, but it runs JavaScript or Python on a different execution environment, one that doesn’t ship the requests library old Functions code relied on. A script built around requests.get() or requests.post() has no equivalent library to fall back to; it has to be rewritten against whatever HTTP mechanism the new runtime actually provides.

For JavaScript-based Code by Zapier steps, that mechanism is the standard fetch API:

import requests

response = requests.get("https://api.example.com/items")
data = response.json()
print(data)

const response = await fetch("https://api.example.com/items");
const data = await response.json();
console.log(data);

requests.post(url, json=data) follows the same pattern, rewritten as a fetch call with an explicit method, JSON body, and content-type header:

const response = await fetch(url, {
  method: "POST",
  body: JSON.stringify(data),
  headers: { "Content-Type": "application/json" },
});

The exception that breaks a naive find-and-replace

Zapier’s guide is explicit about where this pattern stops working: authenticated HTTP calls. Its warning reads:

“Do not use fetch for these calls.”

The reasoning is that Code by Zapier’s execution model doesn’t let code hold onto secrets the way Functions could. A fetch call with an API key baked into a header or query string would mean putting that credential directly in the Code step’s source, exactly the pattern the runtime is designed not to support. Instead, authenticated requests have to go through API by Zapier with the Zapier SDK, which handles the credential through a stored connection rather than inline code. The last post in this series covers that connection setup and its exact binding syntax in full.

Structural Comparison Matrix

Fix it: audit before you convert

Before rewriting anything, list every outbound HTTP call in the existing Functions code and mark whether it carries a credential (an API key header, a bearer token, a signed query string) or not. Unauthenticated calls convert straight to fetch. Authenticated ones need the API by Zapier connection instead, not a fetch call with the header simply carried over.

// Old Functions code:
// requests.get(url, headers={"Authorization": f"Bearer {api_key}"})
//
// This is an authenticated call. Per Zapier's own migration guide,
// route it through an API by Zapier connection, not fetch().