First find the GitHub Actions step that was active when the run stopped. Then use its logs and reg-suit’s verbose output to identify whether the delay is in the build, snapshot comparison, snapshot fetch or publication, notification, or runner/network access. Increase timeout-minutes only if that work is expected to finish and the timeout stays within the runner’s execution limit; a longer limit will not fix a process that is stuck.
Find the step that actually timed out
- Open the failed workflow run on GitHub and identify the failed job and the step that was active when it was cancelled. Check the step and job logs for the last operation that completed.
- If the existing logs do not explain the failure, enable GitHub Actions debug logging. GitHub’s debug logging guidance describes how to add more detail to workflow logs.
- Check whether reg-suit actually started. If the cancellation happened during checkout, dependency installation, build, or tests, investigate that step rather than treating it as a reg-suit failure.
GitHub creates activity logs for workflow runs, and recommends additional debug logging when the logs are insufficient to diagnose a workflow, job, or step failure. See GitHub’s workflow troubleshooting guide.
As an Amazon Associate I earn from qualifying purchases.
Run reg-suit with verbose logging
reg-suit is a command-line visual regression testing tool: it compares current images with expected snapshots and creates an HTML report. Its run command can synchronize expected snapshots, compare images, publish results, and send optional notifications. Use verbose output to determine which operation is last active rather than assuming a particular stage is responsible.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →npx reg-suit --verbose runThe CLI also documents -v as a global option for debug logging. If your workflow uses a non-default configuration file, specify it with -c, for example:
#1 Best Overall
npx reg-suit --verbose -c ./path/to/regconfig.json runConfirm the actual command and configuration path used by your workflow before interpreting the output. The project’s README documents the command, options, and CI setup.
Choose a timeout that fits the work
GitHub Actions accepts timeout-minutes on a job or an individual step. A job timeout applies to the job as a whole; a step timeout lets you set a narrower limit for one operation. The current workflow syntax reference lists a 360-minute job default and a 360-minute maximum for a step, while noting that a runner’s own execution limit can end the job earlier. Check the applicable constraints in the workflow syntax reference.
Choose a limit from the duration you observe in successful runs and a reasonable buffer for normal variation. Do not copy an example number as a universal recommendation.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →jobs:
visual-regression:
runs-on: ubuntu-latest
timeout-minutes: 30 # Example only: choose from observed runtime and applicable runner limits.
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Run reg-suit with verbose output
run: npx reg-suit --verbose run
timeout-minutes: 20 # Optional narrower limit for this step.The checkout configuration follows reg-suit’s documented GitHub Actions example; the timeout values above are illustrative, not official recommended durations. Confirm the checkout action version, workflow behavior, and runner limits for your repository before adopting the snippet.
Use the last active operation to choose what to investigate
Timeout before reg-suit starts
If checkout, installation, the build, or tests are still running when the job ends, troubleshoot that step’s command, dependencies, and logs. Raising reg-suit’s timeout will not help if reg-suit has not begun.
Snapshot synchronization, fetch, or publication
reg-suit publisher plugins store snapshots and reports in external storage; the project lists plugins for S3 and Google Cloud Storage. If verbose output points to fetching or publishing, inspect the publisher configuration, credentials, and storage or network reachability. The stage alone does not establish which of those is failing.
Image comparison
If the log stops during comparison, check which actual and expected images are being processed and how much comparison work the run includes. The project documentation does not establish a universal optimization setting or a performance benchmark, so avoid assuming that one setting will solve every slow comparison.
Notification
If comparison and publication finish but the run stalls during an optional notification, inspect that notification’s configuration and the corresponding service’s availability and credentials. The reg-suit run includes optional notifications, but a timeout at this point does not by itself identify the cause.
Git history or detached HEAD
The reg-suit README’s GitHub Actions example checks out the repository with fetch-depth: 0. If the log points to Git metadata and the workflow uses the git-hash key generator, check whether the CI checkout’s detached-HEAD state is handled as described in the README. This is a targeted history/configuration check, not a general timeout fix.
Self-hosted runner or network access
For a self-hosted runner, check its status in the relevant repository or organization settings. GitHub also documents the runner configuration script’s --check option for testing connectivity to required GitHub network services. Investigate firewall or network access when the logs show connectivity problems; consult GitHub’s self-hosted runner troubleshooting guide.
Re-run and compare the trace
- After changing a timeout or fixing the operation identified in the logs, re-run the workflow.
- Compare the new run’s duration and last successful operation with the original trace.
- Keep a larger timeout only if the expected work now completes reliably and remains within the applicable runner limit. If it still stalls, return to the last active operation and investigate that stage rather than repeatedly raising the limit.
Or skip the browser setup:
If your visual regression workflow also needs website screenshots, ScreenshotNeo is a screenshot API and MCP server for developers. Its one-request API returns a PNG, JPEG, WebP, or PDF. For example, with cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. ScreenshotNeo accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses include X-Page-Verdict and X-Billed headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents and MCP clients.
The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
Does raising the timeout fix a reg-suit process that is stuck?
No. A higher limit only gives expected work more time; use the last active log operation to diagnose a stall.
Where can I set a GitHub Actions timeout?
Set timeout-minutes on the job or on an individual step, subject to the applicable runner execution limit.
Recommended Free Tools
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
