gastownhall/beads · error

gh run list --workflow=%s failed: %s

Error message

gh run list --workflow=%s failed: %s

What it means

When the `gh run list --workflow=<name>` subprocess exits non-zero and gh wrote to stderr, the function surfaces that stderr directly: "gh run list --workflow=%s failed: <stderr>". The message preserves gh's own diagnostics (auth failures, unknown workflow, network errors) so the user sees the real cause.

Source

Thrown at cmd/bd/gate.go:964

	}
	return queryGitHubRunsForWorkflowInRepoWithRunner(workflow, limit, repo, runGHCommand)
}

func queryGitHubRunsForWorkflowInRepoWithRunner(workflow string, limit int, repo string, runGH ghCommandRunner) ([]GHWorkflowRun, error) {
	args := []string{
		"run", "list",
		"--workflow", workflow,
		"--json", "databaseId,name,status,conclusion,createdAt,workflowName",
		"--limit", fmt.Sprintf("%d", limit),
	}
	if repo != "" {
		args = append(args, "--repo", repo)
	}

	output, stderr, err := runGH(args...)
	if err != nil {
		if len(stderr) > 0 {
			return nil, fmt.Errorf("gh run list --workflow=%s failed: %s", workflow, string(stderr))
		}
		return nil, fmt.Errorf("gh run list: %w", err)
	}

	var runs []GHWorkflowRun
	if err := json.Unmarshal(output, &runs); err != nil {
		return nil, fmt.Errorf("parse gh output: %w", err)
	}

	return runs, nil
}

// discoverRunIDByWorkflowName queries GitHub for the most recent run of a workflow.
// Returns (runID, error). This is ZFC-compliant: "most recent run" is deterministic.
func discoverRunIDByWorkflowName(workflowHint string) (string, error) {
	return discoverRunIDByWorkflowNameInRepo(workflowHint, "")
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the stderr tail in the error; run the same command manually (`gh run list --workflow=ci.yml -R owner/repo`) to see the full output.
2. Authenticate: `gh auth login` or set GH_TOKEN with sufficient scopes (repo, actions: read).
3. Use the exact workflow file name (e.g. "test.yml"), not the display name, and verify with `gh workflow list -R owner/repo`.
4. Confirm network/proxy access to api.github.com from the environment running bd.

Example fix

# before
$ bd doctor  # gh run list --workflow=ci.yml failed: exit status 4: ... not logged in
# after
$ gh auth login
$ gh auth status
$ bd doctor

// preflight auth and workflow existence before the real call
exec.Command("gh", "auth", "status").Run()
out, _ := exec.Command("gh", "workflow", "list", "-R", repo, "--json", "name,path").Output()
// verify the workflow filename exists in out before run list

runs, err := queryGitHubRunsForWorkflowInRepo("ci.yml", 5, "owner/repo")
if err != nil {
    var exitErr *exec.ExitError
    if strings.Contains(err.Error(), "gh run list --workflow=") {
        log.Printf("gh reported failure (check auth/scopes/workflow name): %v", err)
        return fallbackGateDecision()
    }
    _ = exitErr
    return err
}

When it happens

Trigger: gh is installed but `gh run list` fails: unauthenticated (`gh auth login` not run), the workflow name doesn't exist in the repo, insufficient token scopes, network failure, or wrong --repo target; reached via queryGitHubRunsForWorkflowInRepo(WithRunner) during gate/run matching.

Common situations: CI tokens lacking `actions: read`; typo'd workflow filename (gh expects the file name like "ci.yml"); expired gh auth session; corporate proxy blocking api.github.com.

Related errors

• gh run list failed: %s
• gh run list: %w
• gh run list: %w
• bd %s: %w: %s
• gh CLI not found: install from https://cli.github.com

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/79a6262465a0c183. Report an issue: GitHub.