How Do I Restart a Workflow in GitHub?

Restarting a GitHub workflow is straightforward and can be done through the GitHub web interface, the GitHub CLI, or programmatically via the GitHub API, providing flexibility for various scenarios.

Methods to Restart a GitHub Workflow

Whether you need to re-run all jobs, specifically failed jobs, or automate the process, GitHub offers several convenient ways to restart a workflow run.

1. Using the GitHub Web Interface (UI)

The most common and user-friendly method for restarting a workflow involves a few clicks directly within your repository on GitHub.com.

Navigate to your Repository: Go to the main page of your GitHub repository.
Access Actions Tab: Click on the "Actions" tab located at the top of your repository page.
Select the Workflow: In the left sidebar, find and click on the specific workflow whose run you wish to restart.
Choose the Workflow Run: From the list of workflow runs, click on the particular run that you want to re-execute.
Re-run the Workflow: Look for the "Re-run jobs" dropdown button (or a similar "Re-run workflow" button) near the top-right of the workflow run details page.
- Re-run all jobs: This option will re-execute every job within that specific workflow run.
- Re-run failed jobs: This is particularly useful for recovering from intermittent errors, as it only retries the jobs that previously failed.

Tip: Ensure you are viewing the correct branch's workflow runs if your repository has multiple branches with different workflow configurations.

2. Using the GitHub CLI (Command Line Interface)

For those who prefer working in the terminal or need to script workflow restarts, the GitHub CLI (gh CLI) provides powerful commands.

To re-run a workflow, especially a failed one, you can use the gh run rerun subcommand. This command is efficient for targeting specific runs or interactively selecting from recent failures.

Install GitHub CLI: If you haven't already, install the GitHub CLI. You can find installation instructions on the official GitHub CLI documentation.
Authenticate: Ensure you are authenticated with gh auth login.
Re-run a specific workflow run:
To re-run a specific run, you need its run-id. You can find this ID in the URL of the workflow run in the GitHub UI (e.g., github.com/owner/repo/actions/runs/123456789) or by listing runs using gh run list.
```
gh run rerun <run-id>
```
Replace <run-id> with the actual ID of the workflow run you want to re-run.
Interactively select a failed run:
If you don't specify a run-id, GitHub CLI returns an interactive menu for you to choose a recent failed run, simplifying the process of retrying failures.
```
gh run rerun --failed
```
This command specifically targets failed runs and presents a list for selection.

3. Using the GitHub API

For advanced automation, integrating GitHub Actions into custom tools, or building sophisticated CI/CD pipelines, the GitHub API offers endpoints to programmatically restart workflows.

You can trigger a re-run of a workflow using the GitHub REST API endpoint for re-running a workflow run:

Endpoint: POST /repos/{owner}/{repo}/actions/runs/{run_id}/rerun
Authentication: Requires a personal access token (PAT) with repo scope or an OAuth token.

This method is ideal for custom scripts, internal tools, or integration with other services.

Important Considerations When Restarting Workflows

Permissions: You must have write access to the repository to re-run a workflow.
Workflow Definition: When you re-run a workflow, it always uses the latest workflow definition (the .yml file) from the default branch of your repository, not necessarily the definition that was present when the original run started. This is crucial for debugging and testing workflow changes.
Cost and Rate Limits: Each re-run consumes CI/CD minutes, which count towards your GitHub Actions billing, and API calls (if using CLI/API) count towards rate limits.
Trigger Context: Re-runs typically use the same event context (e.g., the same commit SHA) as the original run, but with the updated workflow definition.

Method	Ease of Use	Common Use Case	Automation Potential
GitHub Web UI	Very Easy	Ad-hoc re-runs, visual confirmation	Low
GitHub CLI	Moderate	Scripting, command-line preference, interactive selection of failed runs	Medium
GitHub API	Advanced	Custom integrations, robust automation	High

Understanding these methods empowers you to efficiently manage and restart your GitHub Actions workflows, ensuring smooth and reliable continuous integration and delivery processes.