Pause a GitHub Actions Workflow with gh workflow disable

Stop a noisy or broken GitHub Actions workflow in its tracks with gh workflow disable, then bring it back when you are ready. You will disable one workflow, confirm it has vanished from the ordinary list, and re-enable it after the pause. The examples use GitHub CLI gh 2.45.0, installed here as Ubuntu package 2.45.0-1ubuntu0.3+esm3.

Allow about ten minutes. You need an authenticated gh session with permission to manage Actions in the target repository, plus the repository name in OWNER/REPO form.

1. Identify the repository and workflow

Set a shell variable for the repository you intend to change. This is an ordinary local shell assignment and does not contact GitHub:

REPO='OWNER/REPO'

List the workflows that are currently visible:

$ gh workflow list --repo "$REPO"
NAME                  STATE   ID
Build                 active  12345678
Nightly maintenance   active  23456789

The exact columns and values depend on the repository. Disabled workflows are hidden by default, so this is the right starting point for an active workflow, but it is not a complete inventory. To include workflows that are already disabled, add --all:

$ gh workflow list --all --repo "$REPO"

2. Check the target before changing state

Use the workflow view command if you need to tell two similarly named workflows apart. It is read-only:

$ gh workflow view 12345678 --repo "$REPO"
Build

This workflow has 1 job

on: push
jobs:
    build

Your output may show different jobs or triggers. What matters is that the displayed workflow is the one you intend to pause. The --repo option accepts [HOST/]OWNER/REPO, so add a host prefix when working with a GitHub Enterprise Server instance:

REPO='github.example.com/OWNER/REPO'

3. Disable the workflow

This is the state-changing step. It stops the workflow running and removes it from the default listing. It does not delete the workflow YAML file or touch your checkout, so treat it as an operational pause, not a code change:

$ gh workflow disable 12345678 --repo "$REPO"
✓ Disabled workflow Build

You can identify the workflow by name instead:

$ gh workflow disable 'Nightly maintenance' --repo "$REPO"
✓ Disabled workflow Nightly maintenance

Use one identifier per invocation. If a name matches more than one workflow or cannot be resolved, stop and pick the numeric ID from gh workflow list --all.

4. Verify the pause

Run the normal list again:

$ gh workflow list --repo "$REPO"
NAME                  STATE   ID
Nightly maintenance   active  23456789

The disabled workflow should no longer appear. That absence is the expected result, not proof that every existing job has stopped. A run already queued or in progress may need separate handling, and this command does not cancel it.

Use the complete list when you want an explicit state check:

$ gh workflow list --all --repo "$REPO"
NAME                  STATE      ID
Build                 disabled   12345678
Nightly maintenance   active     23456789

5. Restore the workflow

The matching enable command undoes the pause. Use the same ID or name once the pause is over:

$ gh workflow enable 12345678 --repo "$REPO"
✓ Enabled workflow Build
$ gh workflow list --repo "$REPO"
NAME                  STATE   ID
Build                 active  12345678
Nightly maintenance   active  23456789

Enabling lets the workflow run again and puts it back in the normal list. It does not start a run. If you want to test it straight away, treat starting a run as a separate decision, because its trigger, permissions and deployment effects belong to the workflow itself.

Common traps

• Wrong repository. An omitted --repo can target the repository inferred from your current directory. Use an explicit repository for an administrative action.
• Hidden does not mean deleted. Ordinary listing hides disabled workflows. Use --all before concluding that a workflow is absent.
• Pause is not cancellation. Disabling stops future workflow activity but says nothing about runs already queued or running.
• Names are not always unique. Use the numeric ID printed by the list command when a repository contains similar names.
• Authentication is separate from local privilege. Fix the gh auth session or repository permission the command reports. Do not use sudo as a workaround.