Pause a GitHub Actions Workflow Safely with gh workflow disable

You will disable one GitHub Actions workflow in a repository, confirm that it is hidden from the ordinary workflow list, and re-enable it when the pause is over. 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. This is a remote state change: do not run the disable command against a production repository until you have agreed what the pause means and how it will be reversed.

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 command is the right starting point for an active workflow, but it is not a complete inventory. To include workflows that have already been disabled, add --all:

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

Checkpoint: copy either the exact workflow name or its numeric ID. Prefer the ID when names are similar. Do not use a file name guessed from memory. If the workflow is not in the list, inspect the repository, host and account before attempting a change.

2. Check the target before changing state

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

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

This workflow has 1 job

on: push
jobs:
    build

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

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

Do not add sudo. This command talks to GitHub using your user credentials; elevated local privileges do not grant repository access.

3. Disable the workflow

Disabling is the state-changing step. It prevents the workflow from running and removes it from the default workflow listing. It does not delete the workflow YAML file or rewrite the repository checkout. Treat it as an operational pause, not as a code change:

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

The command may 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 select the numeric ID from gh workflow list --all. Never respond to an ambiguity by disabling several workflows in a loop.

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 all existing jobs have stopped instantly. A run already queued or in progress may need separate handling, and this command does not cancel it.

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

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

If the workflow remains active, check that you used the same repository and identifier, then inspect the command's error and authentication context. Do not assume that a successful-looking local shell command changed the repository without this verification.

5. Restore the workflow

There is a matching enable command. Re-enable the workflow with the same ID or name when its pause is complete:

$ 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 permits the workflow to run again and makes it visible in the normal list. It does not manually start a run. If the workflow should be tested immediately, 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 prevents future workflow activity but does not describe the state of 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 reported by the command. Do not use sudo as a workaround.