GitHub Copilot Dynamic Workflows Tutorial: Define Repeatable Multi-Agent Processes in Code

Introduction

Most repeated engineering work fails in the same quiet way: the agent improvises a new plan on every run, so Monday’s careful review becomes Thursday’s skipped check. GitHub Copilot dynamic workflows fix the planning layer instead of the model. You define the process once in code, with fixed steps, parallel agents, structured handoffs, human checkpoints, and spending limits, and Copilot repeats that exact process every time. This tutorial builds your first workflow in Copilot CLI and the Copilot app, runs it from chat and from the terminal, and shows how to pause, resume, schedule, and share it.

Quick answer

Define the process once in a Copilot extension, then run it by name: deterministic steps, parallel agents, structured handoffs, checkpoints, and credit limits repeat identically on every run, in the CLI, app, or SDK.

Evidence

Dynamic workflows entered public preview on October 1, 2026, across Copilot CLI, the Copilot app, and the Copilot SDK, as recorded in GitHub’s changelog entry for the launch. GitHub’s own framing states the value plainly: “These let you define an orchestration in code to get the reliability and observability that complex, multi-agent work demands.” The same changelog lists six things a workflow can do: run commands, use tools, or call other services; divide a goal into tasks and run independent tasks in parallel; pass structured results from one stage to the next; have subagents verify each other’s findings; ask you for input, if your client supports it; and pause at a checkpoint so you can review results and resume when ready.

The concept documentation draws the line that matters most: “A dynamic workflow carries out a process defined in code,” while autopilot is a mode that keeps working without asking after each step, and /fleet lets Copilot decide how to split the work each time. Availability is broad but not universal: workflows are available on all Copilot plans except Pro and Pro+ subscribers on existing annual plans who remain on legacy premium request-based billing. The how-to documentation adds the scheduling shape, with an example that caps a daily run at 200 AI credits, which shows limits are meant to be set deliberately rather than discovered after a large bill.

Prerequisites

• A GitHub Copilot plan that is not on legacy premium request-based billing (see the availability exception in the Evidence section).
• The latest Copilot CLI if you plan to work in the terminal, or the GitHub Copilot app if you prefer no setup.
• A repository you can experiment in, ideally one where a read-only review workflow cannot damage anything.
• Basic comfort with the terminal and JSON, since command-line runs pass workflow inputs as JSON.

Step-by-step guide

Step 1: Enable experimental features in Copilot CLI

Dynamic workflows are always available in the Copilot app with no setup. In Copilot CLI, they sit behind experimental features. Start the CLI with the experimental flag:

copilot --experimental

Or, inside an interactive session, enable them with:

/experimental on

To update Copilot CLI itself, run /update from inside a session. If workflows still do not appear after enabling experimental features, updating is the first fix to try, because the feature shipped in the October 1, 2026 preview and older CLI builds predate it.

Step 2: See which workflows you already have

You may already have workflows in your session through a personal extension or an extension in the repository you are working in. Ask Copilot directly:

What dynamic workflows are available?

If any exist, ask Copilot to describe one before you run it:

Tell me more about the java-security-checks dynamic workflow.

Reading the description first is worth the ten seconds. A workflow is code, and its steps, permissions, and limits are its real behavior, not its name.

Step 3: Create your first workflow by asking Copilot

The fastest authoring route is to ask Copilot to build the workflow for you. By default, Copilot creates the workflow in an extension for your current session. You can instead ask it to create the workflow in a personal or project extension, which is the right choice when the team should share it. Describe what the workflow should accomplish, the required order of steps, which parts should use an agent, and any limits. For example:

Create a dynamic workflow named review-changed that lists changed files, asks an agent to review them, and summarizes the findings.

If you do not supply a name, Copilot chooses one during authoring. Depending on your permission approval settings, you will be asked to allow Copilot to author a new dynamic workflow; choose Yes, and expect further approval prompts as it creates and registers the workflow. Creating and registering a workflow does not start a run. After authoring finishes, verify it with the question from Step 2, then run it separately.

If you would rather write the extension yourself, ask Copilot for its built-in authoring guidance first:

Show me the guidance for writing dynamic workflows.

That guidance is the authoritative reference for the extension format, and it matters because the feature is still in preview: the guidance tracks the current format better than any third-party post.

Step 4: Design the process, not just the prompt

A good workflow separates what must stay fixed from what needs judgment. Put the fixed parts in code: the order of stages, which files or directories get scanned, the format each stage must return, and the rule that decides whether findings move forward. Let agents handle the judgment parts: reading code, spotting problems, and writing findings.

Three design patterns cover most real uses:

• Fan out, then verify. Run one agent per changed file or directory in parallel, then run a second pass in which agents check each other’s findings. Only findings that survive verification reach the final report. GitHub’s own example uses exactly this shape for unresolved review comments: the workflow reports a comment only when two models agree it still matters.
• Checkpoint before anything irreversible. End the review stage at a pause, let a human read the findings, and resume only after approval. Release checks, merges, and deletions all belong behind a checkpoint.
• Structured handoffs between stages. Require each stage to return results in a specified format so later stages can use them without re-reading everything. When a stage returns the wrong shape, Copilot can ask an agent to correct the format.

Decide the limits at design time, not after the first expensive run. The documentation’s scheduling example caps a daily workflow at 200 AI credits, and you should set your own cap the same way: small for the first runs, larger only after you have measured what a typical run costs.

Step 5: Run the workflow from chat

To run a workflow from a prompt, mention it by name and give it its inputs in plain language:

Run the review-changed dynamic workflow on the files changed in this branch.

When you start a workflow from a prompt, Copilot runs it in the background and reports back when it finishes, so you can keep working in your session meanwhile. Your chat agent only creates or runs a dynamic workflow when you explicitly ask it to, or when a skill or slash command instructs it to do so, so a workflow never starts by accident from a vague question.

Step 6: Run the workflow from the terminal

For scripts, scheduled jobs, and repeatable runs, use the terminal command. The shape is:

copilot workflow run review-changed --args '{"files":["src/api.ts","src/auth.ts"]}' --allow-tool=read

Replace the workflow name, the input fields, and the permissions with your own. If the workflow needs no inputs, omit --args. You can also put the JSON input in a file and reference it with @:

copilot workflow run review-changed --args @workflow-input.json --allow-tool=read

The command waits for the run to finish or stop before returning control to your shell. Add --result-file to write the returned value to a JSON file instead of printing it:

copilot workflow run review-changed --args @workflow-input.json --result-file review-results.json --allow-tool=read

For machine-readable output, add --silent to suppress progress output and --output-format json to receive a JSON record containing the workflow name, run ID, status, and any returned result:

copilot --allow-tool=read workflow run review-changed --args @workflow-input.json --silent --output-format json

The run ID in that output is what you need when a run pauses or stops: the command reports the run’s status and run ID in that case, and you use them to track and resume the run.

Step 7: Handle permissions before the run starts

Command-line workflow runs never show interactive permission prompts. Grant the permissions the workflow’s agents need before starting, for example with --allow-tool or --allow-url. Requests that cannot be approved automatically are denied, which is a common cause of a run that fails with no visible error.

Set up authentication before running in scripts. You can use an authentication environment variable such as COPILOT_GITHUB_TOKEN. If the working directory has not already been trusted, loading a project extension requires one more setting for that invocation:

GITHUB_COPILOT_PROMPT_MODE_EXTENSIONS=true copilot workflow run review-changed --allow-tool=read

That setting allows repository extension code to run, so use it only for code you trust. You must still grant the tool permissions the workflow’s agents need, since the setting alone does not grant them.

To stop a terminal run, press Ctrl+C. The run stops, and the command reports its status rather than a result.

Step 8: Schedule the workflow

For work that repeats on a schedule, such as a daily changed-files report, schedule the workflow from a prompt. The documentation’s example schedules a daily run with a credit cap:

/every 1d run the changed-files-report dynamic workflow on the 'main' branch, limiting it to 200 AI credits

Start with a read-only scheduled workflow and a tight credit limit. A scheduled workflow runs without you watching, so its permissions and its cap are its safety net, not your attention.

Step 9: Share the workflow with your team

A workflow travels with its extension. If you created it in a session extension, it stays local to that session. If you created it in a personal or project extension, anyone who loads that extension gets the workflow, and they can list it with the same “What dynamic workflows are available?” question. That is also why the extension deserves the same review as any other code in the repository: it can run commands and call tools, and subagents inherit the permission grants of the session that started them, so a broad grant spreads further than it first appears.

Troubleshooting

The CLI does not offer dynamic workflows

You are probably on an older CLI build, or experimental features are off. Run /update inside a session, then start the CLI with copilot --experimental or run /experimental on in an interactive session. In the Copilot app, no setup is needed, so if workflows are missing there, check the plan exception: Pro and Pro+ subscribers on existing annual plans with legacy premium request-based billing are excluded.

A terminal run fails or a tool request is denied

Command-line runs show no interactive permission prompts, and any request that cannot be approved automatically is denied. Re-run with the permissions granted up front, for example --allow-tool=read for a read-only review workflow, and add --allow-url if the workflow calls a service. Check that authentication is set, for example through COPILOT_GITHUB_TOKEN, before blaming the workflow itself.

A project extension does not load in an untrusted directory

Copilot refuses to load repository extension code from a directory it has not been told to trust. Set GITHUB_COPILOT_PROMPT_MODE_EXTENSIONS=true for that invocation, and only for code you trust, since that setting lets repository extension code execute. You must still grant the tool permissions separately.

A run pauses at a checkpoint and produces no result

That is the checkpoint working as designed, not a failure. The command reports the run’s status and run ID when a run pauses or stops without completing. Review the results so far, decide whether to continue, and resume when ready. If you expected a result file, remember that a paused run has not completed, so treat the pause as a review gate and not as a broken run.

A workflow behaves differently from the same prompt in chat

That difference is the point, and it usually means the workflow is doing its job: chat improvises a fresh plan each time, while the workflow repeats the coded steps. If the workflow’s behavior is wrong, fix the workflow definition, not the prompt. Check the stage order, the input fields, the required output format for each stage, and the verification rule before changing anything else.

FAQ

The FAQ entries in the front matter cover the questions readers ask most: how workflows differ from /fleet, whether the app needs setup, how to run from scripts or CI, what a checkpoint pause means, which plans are included, and whether the preview is stable enough for team processes.

Conclusion

Dynamic workflows are the smallest change that fixes the largest agent failure mode: a process that changes every time it runs. Start with one read-only workflow, a tight credit limit, and a checkpoint before anything irreversible, and let the same steps run identically from chat, from the terminal, or on a schedule. Once that first workflow is boring in the best sense, repeatable and uneventful, extend it to release checks and pull request reviews. For a contrasting approach to the same problem on another platform, read our Claude dynamic workflows tutorial, and for the permission model that keeps CLI agents contained, read our GitHub Copilot local sandboxing tutorial. If your agents are about to touch desktop apps rather than code, our GitHub Copilot computer use tutorial covers that newer preview.

Frequently asked questions