How to Fix Argos CI Builds That Stay Pending on a Pull Request

A pending Argos CI build does not point to one specific failure. First note the exact check name, displayed state, and commit SHA in the pull request, then open the check’s Details link. Next compare that SHA and check with the matching entry in Argos’s Builds list. Those two views tell you whether the build was created, whether GitHub is waiting for a status, and whether the required check applies to the commit GitHub is evaluating. GitHub distinguishes check states such as expected, pending, queued, in progress, and waiting.

Work through the steps below in order. The fix depends on the evidence: a missing run, a skipped workflow, a concurrency queue, an event mismatch, a stale SHA, or a branch rule that expects a different check source.

1. Identify what “pending” means

In the pull request’s Checks area or merge box, record the exact check name and state. Open Details if available and note the commit SHA shown there. GitHub’s states have different meanings:

State or symptom	What it indicates	First place to inspect
`expected` or “Waiting for status to be reported”	A required check is awaiting a report.	Workflow filters, skip instructions, event configuration, check name and source, and whether Argos created a build.
`pending` on a GitHub Actions check	The check is at the front of a queue but a group-based concurrency limit has been reached.	Workflow run details and the workflow’s `concurrency` configuration.
`queued`, `requested`, or `in_progress`	The check has not completed; it may be waiting to start or still running.	Its Details page and the related workflow run.
`waiting`	A deployment protection rule is holding the check.	The deployment protection requirement associated with the run.
Argos shows a completed build, but GitHub blocks merging	The result may refer to a different commit, required check name, or GitHub App source.	Compare the SHA and branch rule with the Argos build record.

Do not treat every pending-looking badge as an Argos failure. GitHub documents expected as waiting for a status report and pending as a GitHub Actions check held at the front of a concurrency-limited queue. The Details link and state are more useful than the badge color alone. See GitHub’s status-check reference.

2. Check whether Argos created a build for this commit

Open the project in Argos and select Builds.
Find the entry linked to the pull request. If the list is long, use its type, status, or build-name filters.
Compare the build’s pull request metadata, branch, and commit with the PR and the SHA recorded from GitHub.
Check the build status and type. A matching build record establishes that Argos received a build for that commit; it does not by itself prove that the required GitHub check name and source match the repository’s rule.

The Argos Builds list exposes build status, PR metadata when linked, branch, commit, timestamp, and filters for build type, status, and build name. Use these fields to distinguish a missing build from a GitHub reporting or branch-rule issue. Argos documentation: Builds list.

No matching build: inspect the CI workflow’s trigger, filters, job conditions, and the way the repository invokes Argos. Confirm the workflow actually ran for the PR commit.
Matching build on another commit: check whether the PR advanced after the build started, then compare against the latest relevant SHA.
Matching build and SHA: continue to workflow event and required-check configuration; a build record alone does not establish that GitHub accepts it as the required result.

3. Check workflow triggers, filters, and skipped runs

If no corresponding build exists, inspect the workflow YAML and run history. Verify that the workflow listens for an event that occurs for this pull request and that branch or path filters allow these changes through. Also inspect job-level if conditions and commit messages for skip instructions.

A workflow skipped by branch filtering, path filtering, or a commit message can leave its associated required check pending and block merging. GitHub advises avoiding required checks that can be skipped. Its troubleshooting guide includes a workflow filtered to scripts/**: a PR that changes only a root-level file does not trigger the workflow, so the required check remains waiting for a report. GitHub: Troubleshooting required status checks.

Review both workflow-level filters (on.pull_request.branches, paths, and their inverse forms) and job-level conditions. If the required check must always report, ensure the required workflow or a dedicated final check runs for every relevant PR. A conditionally skipped job reports success, but a workflow that never starts because its event was filtered out can leave the associated required check waiting.

Example: include the merge queue event

If the repository uses a merge queue, a workflow that only listens for pull_request and push may not report a required check for the merge-group commit. Add the separate merge_group trigger to the workflow that supplies the required check:

name: visual-checks
on:
  pull_request:
  merge_group:
jobs:
  visual-checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # Keep the repository's existing Argos setup and upload steps here.

This illustrates the event configuration only; retain the project’s current Argos integration steps and other required triggers. GitHub says merge queues require the separate merge_group event in addition to the relevant PR trigger. Do not copy the example’s checkout version blindly if the project uses a different supported version. See GitHub’s merge-queue guidance.

GitHub lists push, pull_request, pull_request_review, pull_request_target, deployment, and deployment_status among events whose workflow-job checks can be evaluated for a PR. A manually dispatched workflow_dispatch run on the PR head branch does not make its job checks appear in the PR checks section or satisfy a required branch-ruleset check. Choose an eligible event that matches the workflow’s intended behavior; do not add a privileged trigger without reviewing its security implications.

4. Check whether the check is queued by concurrency

If GitHub shows a run and its check state is pending, open the run and inspect its queue and concurrency details. GitHub defines this Actions state as a check at the front of the queue whose group-based concurrency limit has been reached. Review the workflow’s concurrency group and any other runs using the same group. Decide whether the grouping is intentionally serializing work or is broader than intended.

Adjusting concurrency changes how runs queue or replace one another, so preserve the project’s intended cancellation and ordering behavior. Do not change branch protection to hide a queued check; first determine whether the run is waiting for capacity or whether the workflow itself did not start.

5. Verify the SHA GitHub requires

Required checks must succeed on the latest relevant commit; a passing result on an earlier commit does not satisfy the rule. A pull request can also have a head commit and a test merge commit. In the PR’s status-check box, note which commit GitHub says it is showing:

If the test merge commit has a status, GitHub may require that merge commit’s check to pass.
If the test merge commit has no status, the head commit’s check is relevant.

Compare that SHA with the SHA in the Argos Builds entry and the check Details page. If new commits arrived after the build, rerun or otherwise trigger the visual check for the latest relevant commit using the repository’s normal workflow. If branch protection requires the branch to be up to date, merge or rebase the base branch as appropriate, then let the required workflow report against the commit GitHub evaluates. GitHub documents the latest-SHA and head-versus-test-merge-commit rules.

6. Inspect branch protection and rulesets

If the Argos build is complete and matches the relevant SHA, inspect the repository’s branch protection or ruleset settings:

Confirm the required check name exactly matches the check reported for the PR.
If the rule specifies a GitHub App, confirm the status came from that expected app.
Check whether a check run and a commit status share the same required name. GitHub states that if both types have the same required name, both must pass.
Confirm the rule is applied to the target branch and that any up-to-date requirement has been met.

GitHub Actions creates checks, while external services and integrations can create commit statuses. A green Argos build and a blocked required check can therefore coexist when GitHub expects a different check identity, source, or SHA. See GitHub’s explanation of checks and commit statuses and required-check troubleshooting.

7. Use the commit-status API when the reporter is external

For an integration that reports commit statuses, inspect the status for the exact SHA and look at its context, state, and target URL. The API can report error, failure, pending, or success; the context identifies the reporting service. For a public repository, this cURL request retrieves the combined status for a commit:

curl -L \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/OWNER/REPO/commits/COMMIT_SHA/status"

Replace OWNER, REPO, and COMMIT_SHA. For a private repository, authenticate with a token that has read access to commit statuses; keep tokens out of source control and logs. The combined status can be pending when there are no statuses or when a context is pending, so inspect individual contexts in the response rather than treating the combined state as a diagnosis. This endpoint concerns commit statuses; GitHub Actions workflow jobs create checks, not commit statuses. GitHub REST API: commit statuses.

Common causes and fixes

What you see	Likely area	What to do
“Waiting for status to be reported”; no run or Argos build	Filtered or skipped workflow, wrong trigger, or no report for the expected context	Review branch/path filters, skip instructions, job conditions, event triggers, and the workflow’s Argos invocation. Avoid requiring a check that can be skipped.
Run exists; GitHub state is `pending`	GitHub Actions group-based concurrency limit	Inspect the run queue and concurrency group; decide whether the grouping is intentionally limiting simultaneous work.
Run passed but check is absent from the PR or does not satisfy the rule	Workflow event is not eligible for PR check evaluation	Use an eligible event for the intended workflow; add `merge_group` if a merge queue needs the check.
Argos is green, while the PR check remains blocked	SHA, check name, check type, or required GitHub App source mismatch	Compare the required check and source in branch rules with the PR’s exact SHA and the Argos build.
Check says `waiting`	Deployment protection rule	Inspect and satisfy the deployment protection requirement holding that check.
Only newer commits are failing to satisfy an earlier green result	The status is attached to an outdated SHA	Run the visual check for the latest relevant commit and meet any up-to-date branch requirement.

Reliability and cost considerations

For a reliable required-check setup, make sure the check is reported for every commit and event on which the merge rule depends. Avoid path or branch filters on the only required check unless a separate always-reported check covers changes outside those filters. Treat merge-queue validation as its own event path. When investigating, save the PR check name, state, SHA, Details link, workflow event, and matching Argos build metadata; together these make it easier to isolate whether the gap is in execution or GitHub’s acceptance of the result.

Do not infer an Argos outage from a missing or pending GitHub check alone. The supplied documentation describes GitHub’s check behavior and where to find Argos build metadata; diagnosing a particular repository requires its workflow YAML, PR commit, build record, and branch-rule configuration. Likewise, the sources do not establish a typical wait time or the most common cause.

Or skip the browser setup

For a browser screenshot used to inspect a page while debugging a visual workflow, ScreenshotNeo offers a website screenshot API and MCP server for developers. One GET request can return PNG, JPEG, WebP, or PDF. This does not change GitHub’s required-check configuration or fix a missing Argos status; it gives you a direct way to capture the page without managing browser setup.

Example request, using Stripe as the target URL:

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

See the ScreenshotNeo API documentation for the request options. Cookie banners are accepted and removed along with supported newsletter popups and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing state. Its MCP server lets AI agents using Claude, Cursor, or another MCP client take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

Does a green Argos build always satisfy a required GitHub check?

No. The required result must match the relevant commit SHA and the check name and source expected by the repository’s rule.

Should I manually dispatch the workflow again?

A manually dispatched workflow on the PR head branch may not satisfy a required workflow-job check. Confirm the event is eligible for PR check evaluation and use the appropriate trigger.

Can I make the required check optional to unblock this PR?

Changing a merge rule may allow a merge without the expected validation. First identify why the status is missing; change policy only if that is an intentional repository decision.

Where do I confirm whether Argos received the build?

Open the project’s Builds list and compare the PR metadata, branch, commit, status, and build type with the pull request.