Using dynamic workflows

This article explains how to create, use, and share dynamic workflows in GitHub Copilot CLI and the GitHub Copilot app.

For an overview of what dynamic workflows are and how they work, see Dynamic workflows.

Prerequisite

To use dynamic workflows in Copilot CLI, you must enable experimental features by running the CLI with the --experimental command-line option, or by using /experimental on in an interactive session.

Finding out about available dynamic workflows

You may already have access to one or more dynamic workflows in your session—for example, through a personal extension or an extension in the repository you are working in. If so, you can use one by mentioning it by name in a prompt.

To find out whether any dynamic workflows are available, just ask Copilot. For example:

What dynamic workflows are available?

What dynamic workflows are available?

If dynamic workflows are available, you can ask Copilot to describe one. For example:

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

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

If you don't have any dynamic workflows yet, you can create one. See Creating a dynamic workflow.

Running a dynamic workflow

1. In a Copilot session, enter a natural language prompt to ask Copilot to run a dynamic workflow.

   Use the workflow's registered name, and supply any required inputs. For example, a dynamic workflow that performs a security review will typically require you to specify the files it should be run against. In this case you might enter a prompt such as:

   Copilot prompt

   Run the java-security-checks dynamic workflow on the java files in the current directory, with an AI credit limit of 500.
   

   Importante

   Setting limits on a dynamic workflow is optional but recommended, as it helps control resource usage and prevent excessive consumption of AI credits. For more information about the limits you can set, see Dynamic workflows.

2. Depending on your current permission approval settings, Copilot asks you to approve the dynamic workflow run before it starts. Choose Yes.

If the extension provides another way to start its workflow, such as a slash command or a canvas control in the Copilot app, follow that extension's instructions.

Running a dynamic workflow from the command line

1. In a terminal, use the Copilot CLI command copilot workflow run WORKFLOW-NAME [OPTIONS] to run an existing dynamic workflow.

   The workflow must be available through a personal extension, a project extension, or an installed plugin. If you created the workflow in a chat session, first make its extension available outside that session. See Reusing and sharing dynamic workflows.

   Use --args to supply inputs for the workflow as JSON.

   Importante

   This command does not display permission approval prompts, even when you run it in a terminal. 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. For more information, see Referencia programática de la CLI de GitHub Copilot.

   For example, suppose you have a workflow named java-security-checks that accepts a directory input and needs permission to read files:

   Shell

   copilot workflow run java-security-checks \
      --args '{"directories":["java/src","java/tests"]}' \
      --allow-tool=read
   

   Replace the workflow name, input fields, and permissions to match your workflow. If the workflow needs no inputs, omit --args.

   Alternatively, put the JSON inputs in a file and prefix its path with @:

   Shell

   copilot workflow run java-security-checks \
      --args @workflow-input.json \
      --allow-tool=read
   

2. Watch the phases and progress messages reported by the workflow. When it completes, the command prints its result, if it returns one, and exits. If it pauses or stops without completing, the command reports the run's status and run ID. To interrupt a run, press Ctrl+C.

The workflow's configured limits and your personal default limits still apply. See Dynamic workflows.

Saving the result to a file

Add --result-file to write the workflow's returned value to a JSON file instead of printing it in the terminal. Progress messages are still displayed.

copilot workflow run java-security-checks \
   --args @workflow-input.json \
   --result-file security-results.json \
   --allow-tool=read

copilot workflow run java-security-checks \
   --args @workflow-input.json \
   --result-file security-results.json \
   --allow-tool=read

The file contains only the returned value, not the progress messages or run details. Relative paths are resolved from the directory where you started the command.

The file is written only when the workflow completes successfully and returns a result. An existing file is replaced only after the new result has been written successfully. A paused, failed, or interrupted run leaves any existing file unchanged.

Running a workflow in a script

For scripts and CI/CD pipelines, configure authentication and permissions before running the command. You can use an authentication environment variable such as COPILOT_GITHUB_TOKEN. See Referencia de comandos de la CLI de GitHub Copilot.

To load a project extension when the working directory has not already been trusted, set GITHUB_COPILOT_PROMPT_MODE_EXTENSIONS=true for that invocation. This allows repository extension code to run. Only use it for code you trust. You must still grant the tool permissions the workflow's agents need.

Use --silent to suppress progress output. Add --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 java-security-checks \
   --args @workflow-input.json \
   --silent --output-format json

copilot --allow-tool=read workflow run java-security-checks \
   --args @workflow-input.json \
   --silent --output-format json

Creating a dynamic workflow

By default, Copilot creates a workflow in an extension for your current session. You can instead ask it to create the workflow in a personal or project extension.

1. Describe what you want the workflow to accomplish, any required order of steps, which parts should use an agent, and any limits. For example:

   Copilot prompt

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

   Nota:

   If you don't supply a name for the workflow, Copilot chooses one during authoring.

2. Depending on your current permission approval settings, you will be asked to allow Copilot to author a new dynamic workflow. Choose Yes.

   Copilot may ask for other approvals as it works on creating and registering the dynamic workflow.

3. After the authoring process completes, check that the workflow was successfully created and registered. To do this, ask Copilot what dynamic workflows are available.

Creating and registering a workflow does not start a run. To use it, see Running a dynamic workflow.

You can also write the extension yourself, with guidance from Copilot. To read the built-in guidance, ask:

Show me the guidance for writing dynamic workflows.

Show me the guidance for writing dynamic workflows.

Reusing and sharing dynamic workflows

Dynamic workflows are implemented as Copilot extensions. By default, when you ask Copilot to create a workflow, its extension is only available in that session. A workflow can also already be stored in a personal or project extension.

To reuse or share a workflow that you created in the current session, copy its extension to either your personal extensions directory or your repository's extensions directory. This copies the definition, not its run history or saved progress.

1. Ask Copilot to tell you the path to the dynamic workflow you want to share. For example:

   Copilot prompt

   Tell me the path to the java-security-checks dynamic workflow.
   

   Copilot will respond with a path such as: /Users/yourname/.copilot/session-state/d58ba0bf-78fa-4172-b277-c18ba400e7c6/extensions/java-security-checks/extension.mjs

2. To make this dynamic workflow available in all your sessions, copy the directory containing the extension.mjs file into your ~/.copilot/extensions/ directory.

   You can ask Copilot to do this for you. For example:

   Copilot prompt

   Copy the java-security-checks workflow to my personal extensions directory.
   

3. Alternatively, to share the dynamic workflow with everyone working in a repository, copy the directory containing the extension.mjs file into the .github/extensions/ directory of your local copy of the repository.

   Again, you can ask Copilot to do this for you. For example, if you are currently working in the repository in which you want to make the dynamic workflow available:

   Copilot prompt

   Copy the java-security-checks workflow to the current repository's extensions directory.
   

   Once this change is merged into the repository, teammates can use the workflow after updating their local copy and loading the extension.

4. Start a new session, or restart an existing session. When the session finishes loading, ask Copilot to list the available dynamic workflows to verify that your workflow is now available.

Distributing dynamic workflows in a plugin

Plugins provide a way to distribute custom Copilot functionality. You can use a plugin to add dynamic workflows to Copilot CLI and the GitHub Copilot app.

For more information, see Creación de un complemento para GitHub Copilot CLI.

After creating a plugin containing your dynamic workflow, and publishing it on a plugin marketplace, people will be able to discover and install it. See Búsqueda e instalación de complementos para GitHub Copilot CLI.

Monitoring and managing dynamic workflow runs

You can monitor a run's progress and AI credits usage, along with any phases and subagents the workflow reports. You can also check completed runs, pause or cancel an active run, and resume a run that you paused or was stopped when a limit was reached.

In Copilot CLI:

1. In an interactive session, enter /workflows.

   The currently running and recently completed dynamic workflow runs are listed.

2. Use the arrow keys to move the selection, then press Enter to open a run's details.

   The details include the length of time a run has been active, any current phase reported by the workflow, the number of currently active subagents, the total number of subagents spawned, and the number of AI credits used so far.

3. In an active run, press P to pause, X to cancel the run.

In the Copilot app:

If you are running, or have run, a dynamic workflow in the current session, a Workflows button is displayed above the prompt box.

1. Click the Workflows button.

   A popup is displayed listing active runs, runs ready to resume, and recently finished runs.

2. Click a workflow run in the popup.

   A panel is displayed showing the details of the selected workflow run.

   The details include the length of time a run has been active, any current phase reported by the workflow, the number of currently active subagents, the total number of subagents spawned, and the number of AI credits used so far.

3. To stop an active run, click Cancel. To pause it, so that it can be resumed later, click Pause.

Monitoring dynamic workflows with OTel

If you have enabled OpenTelemetry (OTel), you can inspect workflow activity in your traces. A workflow creates an invoke_workflow span each time it runs or resumes, with its agents' activity linked to it.

For configuration in Copilot CLI, see Referencia de comandos de la CLI de GitHub Copilot.

Resuming a run

You can resume a paused run or one that stopped at a limit when it is listed as resumable. The workflow can reuse saved results from completed steps and subagents, rather than starting a new run. Work that was not saved may need to run again.

When resuming a run that reached a limit, set a higher total for that limit. Usage before the run stopped still counts toward the new total.

Canceled runs cannot be resumed.

In Copilot CLI:

1. In an interactive session, enter /workflows.
2. Use the arrow keys to move the selection to the paused or stopped run that you want to resume.
3. Press R to resume the run.
4. If prompted, increase the limit that was reached and confirm the new total.

In the Copilot app:

1. In a session that contains paused or stopped dynamic workflow runs, click the Workflows button, just above the prompt box.

   Any resumable runs are listed in a "Ready to resume" section.

2. Click the run you want to resume.

3. In the side panel, click Resume. If the run reached a limit, click Resume with limit… instead, then follow the prompts to set a higher total and resume.

Scheduling a dynamic workflow run

You can schedule a dynamic workflow run in your current Copilot CLI session, just like any other prompt, by using the /every or /after commands. For example:

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

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

For more information, see Programación de indicaciones en GitHub Copilot CLI.