Inspect a GitHub Actions Workflow with gh workflow view

You will use gh workflow view to find a workflow, inspect its run summary, or read the workflow YAML without editing repository files. Allow about ten minutes. You need GitHub CLI installed, access to the target repository, and authentication that permits reading its Actions data. The examples use GitHub CLI 2.87.3, installed on this machine in September 2026. Other releases can alter wording or interactive details.

This command is read-only from the repository's point of view. The --web option opens a browser page, but it does not change the workflow. No elevated privileges are needed: do not use sudo.

1. Check the installed command

Confirm the binary and read the local help before choosing an argument. These are ordinary, read-only commands:

$ command -v gh
/usr/bin/gh
$ gh --version
gh version 2.87.3 (2026-02-23)
https://github.com/cli/cli/releases/tag/v2.87.3
$ gh workflow view --help
View the summary of a workflow

USAGE
  gh workflow view [<workflow-id> | <workflow-name> | <filename>] [flags]

Checkpoint: the usage line shows three forms of workflow selector. An ID is normally the most stable choice for scripts; a name or YAML filename is easier to read at a terminal. If the installed version differs, use its displayed help as the final authority for wording and available flags.

2. Select a workflow interactively

With no selector, the command lets you choose a workflow interactively:

$ gh workflow view

Choose the workflow whose summary you need, then finish the prompt in the terminal. This is useful when you know the repository but not the workflow's ID or exact filename. It is less suitable for a script because it depends on a person making the selection. If the command says that a workflow argument is required, provide one explicitly rather than guessing what the prompt should contain.

For a repeatable command, use a real selector from the repository:

$ gh workflow view WORKFLOW_ID
$ gh workflow view WORKFLOW_NAME
$ gh workflow view .github/workflows/WORKFLOW_FILE.yml

Replace each all-capitals value with an actual ID, workflow name, or repository-relative workflow filename. Do not include the angle brackets shown in the usage text. A name containing shell metacharacters or spaces should be quoted:

$ gh workflow view 'Nightly checks'

3. Inspect the workflow YAML

Add --yaml when you need the workflow definition rather than its normal summary:

$ gh workflow view WORKFLOW_ID --yaml

This is a useful check when a run refers to a job or trigger you did not expect. Read the displayed document as evidence of the selected workflow version. The command does not edit the YAML. If the output is long, redirect it only to a new, clearly named file that you intend to keep:

$ gh workflow view WORKFLOW_ID --yaml > /tmp/workflow-review.yml
$ test -s /tmp/workflow-review.yml && echo 'YAML output captured'

The redirection is performed by your shell, not by GitHub CLI. The example writes under /tmp so it does not overwrite a repository file. If you replace that path with an existing file and use >, the shell truncates it first. There is no command-specific undo for that truncation; choose a new path or use >> only when appending is genuinely what you want.

4. Choose a branch or tag version

Use --ref when the workflow file should be read from a particular branch or tag:

$ gh workflow view WORKFLOW_ID --ref BRANCH_OR_TAG
$ gh workflow view WORKFLOW_ID --ref BRANCH_OR_TAG --yaml

Replace BRANCH_OR_TAG with the exact ref you want to examine, such as main or a release tag. This matters when the workflow changed between branches. Keep the selector and ref together in notes or scripts so a later reader can tell which version was inspected. A missing or misspelt ref is a repository lookup problem, not a reason to run the command as root.

Checkpoint: before acting on what you read, record the repository, workflow selector, and ref. A summary from the default ref can describe a different file from the one used by a release branch.

5. Target another repository

Use the inherited --repo option when the current directory is not the repository you want:

$ gh workflow view WORKFLOW_ID --repo OWNER/REPOSITORY
$ gh workflow view WORKFLOW_ID --repo OWNER/REPOSITORY --ref main --yaml

For a GitHub Enterprise host, the documented format is HOST/OWNER/REPOSITORY. Quote the value if your shell input contains characters that need protection. Check every component before running the command. A valid workflow ID in one repository can identify a different workflow, or no workflow at all, in another.

Authentication is separate from selecting a repository. If GitHub CLI reports that authentication is required, authenticate through your normal organisational process and retry. Do not paste a token into a command, shell history, article, or ticket. The installed manual lists exit status 4 for an authentication requirement, status 1 for an error, status 2 for cancellation, and status 0 for successful execution. Specific commands can add further statuses.

6. Open the workflow in a browser

Use --web when the web interface is more useful than terminal output:

$ gh workflow view WORKFLOW_ID --web
$ gh workflow view WORKFLOW_ID --ref BRANCH_OR_TAG --web

This asks GitHub CLI to open the selected workflow in the browser. It is still a read operation, but it can expose repository information on screen and may use your existing browser session. Check the repository and ref before confirming any browser actions. If no graphical browser is available, use the normal terminal view or --yaml instead.

7. Diagnose the usual failures

If no workflow argument is accepted in the context where you are running the command, use an explicit ID, name, or filename. If a selector is rejected, verify the spelling and repository first. A filename should be the workflow file path recognised by the repository, commonly under .github/workflows/; do not invent a filename from a job name.

If the result seems inconsistent, repeat the command with --ref and then with --yaml. These two checks distinguish a changed branch version from a misunderstanding of the displayed summary. If the command is cancelled, rerun it after checking the selector and terminal prompt. If authentication fails, stop at that point and repair the GitHub CLI login through approved account controls rather than trying random credentials.

A successful exit status confirms that GitHub CLI completed the request. It does not prove that a workflow run succeeded, that every job passed, or that a deployment is safe. Treat the workflow definition and its run summary as separate things, and verify any consequential change in the repository's normal review process.