How to Fix Reg-suit Timing Out in GitHub Actions

To fix reg-suit timing out in GitHub Actions, first identify which job step is being terminated and what reg-suit was doing at that moment. Use the Actions logs, enable GitHub debug logging if needed, and run reg-suit with --verbose. Then investigate the stage indicated by the last log output. Increase timeout-minutes only when the work is expected to finish and fits within the runner’s execution limit; a longer timeout does not fix a process that is stuck.

1. Find the timeout boundary

Open the failed workflow run and locate the job and step that was active when the run stopped. Check whether the timeout occurred before reg-suit started, while npx reg-suit run was running, or in a later step such as report upload or notification. GitHub generates activity logs for workflow runs. If they do not show why a workflow, job, or step failed, enable additional debug logging using GitHub’s documented troubleshooting process: Troubleshooting workflows.

Record the job name, step name, command, elapsed time, and last visible operation. This gives you a baseline to compare after a change. A job timeout and a step timeout are different boundaries, so note which one the run reached.

2. Turn on reg-suit verbose output

Reg-suit is a command-line visual regression testing tool. Its run command combines expected-snapshot synchronization, image comparison, report publication, and optional notifications. That means a timeout inside run can have several causes, and the final log lines should guide the next check rather than assuming a particular stage is at fault.

Run it with the global verbose option:

npx reg-suit --verbose run

The documented short form is -v. If your repository uses a non-default configuration file, provide it with the documented -c option:

npx reg-suit --verbose -c path/to/regconfig.json run

Confirm the actual command and configuration path used by Actions. A local invocation using a different config, working directory, credentials, or environment may not reproduce the CI behavior.

3. Set a timeout at the right level

GitHub Actions supports timeout-minutes on both jobs and individual steps. Use a job limit when the whole job needs more time; use a step limit to bound a single known long operation. The current workflow syntax reference documents a 360-minute job default and a 360-minute maximum for steps. A job may also be stopped earlier by the applicable runner execution limit. See GitHub Actions workflow syntax for current details.

jobs:
  visual-regression:
    runs-on: ubuntu-latest
    timeout-minutes: 30 # Example only: choose from observed runtime and runner limits.
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci

      - name: Run reg-suit with verbose output
        run: npx reg-suit --verbose run
        timeout-minutes: 20 # Optional narrower limit for this step.

The timeout values above illustrate where the setting goes; they are not universal recommendations. Choose a limit from observed duration and a reasonable buffer, then confirm it remains within the execution limit for the runner you use. The checkout configuration with fetch-depth: 0 follows the reg-suit project’s documented GitHub Actions example. Check the project’s current README for its workflow and configuration guidance: reg-viz/reg-suit.

4. Follow the log evidence to the stalled stage

Last active operation	What to inspect
Before reg-suit starts	Checkout, dependency installation, build, and test steps. Fix or time-bound the step that is actually consuming the job time.
Git history or hash-key work	Check checkout depth and branch history. The reg-suit README documents a detached-HEAD workaround for CI when using the git-hash key generator; treat this as a branch/history configuration check when logs point there.
Expected snapshot synchronization	Inspect the configured snapshot source, credentials, and storage/network reachability. Reg-suit publisher plugins store snapshots and reports in external cloud storage; the project lists S3 and Google Cloud Storage plugins.
Image comparison	Inspect the actual and expected image inputs and the amount of comparison work. The reviewed project documentation does not establish a universal optimization setting or performance benchmark.
Report publication	Check the publisher configuration, credentials, and whether the runner can reach the configured storage service.
Notification	Verify the notification configuration and any external service access indicated by the logs.

These are diagnostic branches, not claims that any one stage causes a particular timeout. The stage and surrounding log output should determine which branch applies.

5. Check runner health and network access when indicated

If the logs show connectivity problems, investigate network access and firewall rules for the services involved. For a self-hosted runner, check its status in repository or organization settings. GitHub also documents a --check option for the runner configuration script that checks access to required GitHub network services. Start with the runner documentation and use this check when runner-to-GitHub connectivity is relevant: Monitoring and troubleshooting self-hosted runners.

A network check to GitHub does not prove that the runner can reach a separately configured snapshot store or notification service. Use the failing operation in the logs to identify the destination to investigate.

6. Re-run and compare

Apply the targeted fix or timeout change.
Re-run the workflow and note the duration and last successful operation.
Compare the trace with the original run. Confirm the formerly stalled stage completes and the job remains within runner limits.
If the same operation still stalls, continue investigating that stage instead of repeatedly raising the timeout.

This is a log-based diagnostic sequence; it does not assume a particular repository, runner, or reg-suit configuration.

Common errors and fixes

Symptom	Likely area to check	Next action
The job says it exceeded its timeout	Job-level `timeout-minutes`, or an earlier runner execution limit	Find the active step and compare its runtime with the configured job and runner limits. Raise the job limit only if the work is expected to complete.
The reg-suit step is terminated while another step has time remaining	Step-level `timeout-minutes`	Inspect that step’s limit and logs. Adjust its limit if the operation is legitimately longer than expected and stays within applicable limits.
Verbose output stops around snapshot access or publication	Publisher setup, credentials, network, or remote storage	Verify the configured publisher and credentials, then check runner access to that destination.
Verbose output stops around comparison	Image inputs or comparison work	Confirm expected and actual snapshots are available and inspect the inputs and stage output. Do not assume a timeout increase will resolve a stuck comparison.
Git-related behavior differs in CI	Checkout history or detached HEAD	Check the project’s documented full-history checkout pattern and detached-HEAD guidance, particularly when using the git-hash key generator.
Logs do not identify the failing operation	Insufficient workflow or tool logging	Enable GitHub debug logging and run reg-suit with `--verbose`, then capture the next trace.

Performance, reliability, and cost notes

Performance: Do not infer a performance problem from the word “timeout” alone. First locate the operation and compare its duration across runs. The available source material provides no typical reg-suit runtime or benchmark for a particular setting.

Reliability: A longer timeout can accommodate legitimate work, but it also delays failure when a process is stuck. Keep the limit tied to observed runtime, investigate recurring stalls at their last active operation, and use a step-level limit when isolating one long command helps.

Cost: The reviewed sources do not establish a general cost or performance winner between hosted and self-hosted runners. Compare the runner service and configuration actually used by your repository; do not assume that switching runner types will fix a stage-specific stall.

Or skip the browser setup

If the visual regression workflow also needs website screenshots, ScreenshotNeo provides a screenshot API and MCP server. A GET request can return a PNG, JPEG, WebP, or PDF. This is separate from diagnosing reg-suit’s own synchronization, comparison, publication, and notification stages.

For example, request a WebP capture in cURL:

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo API documentation for request options and setup. Cookie banners are accepted and removed before capture, along with known newsletter popups and chat widgets; each step can be turned off. Bot checks, blank pages, and failed loads are not billed. An MCP server gives AI agents screenshot tools. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000.

FAQ

Should I always set a longer timeout for reg-suit?

No. Use a longer limit when logs show the operation is progressing and needs more time. If output stops at the same operation, investigate that stage.

Can I set a timeout on just the reg-suit step?

Yes. GitHub Actions supports timeout-minutes on individual steps as well as jobs.

Does `--verbose` fix a timeout?

No. It adds diagnostic detail to help identify where the command is spending time.

Is full Git history a universal timeout fix?

No. The project’s example uses fetch-depth: 0, and its detached-HEAD guidance applies to a specific Git hash-key configuration. Use those checks when the logs point to Git history or branch behavior.