fix: approve the stored CircleCI workflow when its pipeline listing omits it

[ndbroadbent]

Fixes #153.

Problem

ApproveJob always found the workflow to approve through GET /pipeline/{id}/workflow, so it could follow reruns. For a while after some pipelines start, CircleCI's listing returns only setup-workflow. The lookup then failed with no workflow found with name …, and the hold job stayed on hold even though the deploy was approved.

Fix

• Normal case: while the stored workflow's hold job is on_hold, it is approved directly, without the listing. That's the workflow named by the request's workflow_id.
• Reruns: the listing is only read when that job isn't on hold. A rerun is the newest workflow in the pipeline with the same name, created after the original; its hold job is approved instead.
• No rerun: the stored workflow's hold job is approved anyway, and CircleCI's response says why it can't be (for example, it was already approved). Error handling for that case is unchanged.
• Unchanged: verifyPipeline (revision, repository, not a fork) still runs before anything is approved. A rerun is in the same pipeline, so it's covered.

I also replaced the duplicated anonymous job structs in getWorkflow with one workflowJob type.

Tests

The fake CircleCI server can now be configured with workflows, hold-job statuses and listing contents. New cases:

• The listing omits the workflow (only setup-workflow): the stored workflow's hold job is approved, and the listing is never requested.
• The original hold job was canceled and a newer rerun is on hold: the rerun's hold job is approved.
• An older workflow with the same name isn't treated as a rerun.
• A pipeline mismatch stops the approval before any rerun is followed.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes
  • CircleCI approvals now target the requested workflow’s held job when it is still on hold. If it is no longer held, approval targets the newest matching rerun in the same pipeline, avoiding older or unrelated workflows.
  • Approvals stop when the workflow’s pipeline does not match, and report errors when workflow details or the matching approval job can’t be verified.
• Documentation
  • Updated CircleCI approval guidance to describe how reruns are handled.

[deepsource-io]

DeepSource Code Review

We reviewed changes in 4c66a59...ab5a274 on this pull request. Below is the summary for the review, and you can see the individual issues we found as inline review comments.

See full review on DeepSource ↗

PR Report Card

Overall Grade

Security   Reliability   Complexity   Hygiene

Code Review Summary

Analyzer	Status	Updated (UTC)	Details
JavaScript		Oct 13, 2026 11:20p.m.	Review ↗
Go		Oct 13, 2026 11:20p.m.	Review ↗

---

Important

AI Review is run only on demand for your team. We're only showing results of static analysis review right now. To trigger AI Review, comment @deepsourcebot review on this thread.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Essentials
• Run ID: 81e06eba-6860-4b91-acb7-f9369642e19e

📥 Commits

Reviewing files that changed from the base of the PR and between 4c66a59 and ab5a274.

📒 Files selected for processing: 4

• docs/src/content/docs/integrations/deploy-approvals/circleci.mdx
• internal/gateway/circleci/client.go
• internal/gateway/circleci/client_test.go
• internal/gateway/circleci/pipeline_verification_test.go

Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Walkthrough

CircleCI approval now verifies the pipeline before choosing a target. It approves the stored workflow’s on-hold job when available; otherwise, it checks for a newer same-name workflow in the pipeline. Tests and documentation describe these cases.

Changes

CircleCI approval handoff

Layer / File(s)	Summary
Verified workflow and rerun targeting internal/gateway/circleci/client.go, internal/gateway/circleci/client_test.go, internal/gateway/circleci/pipeline_verification_test.go, docs/src/content/docs/integrations/deploy-approvals/circleci.mdx	ApproveJob verifies the pipeline before selecting an approval job. It uses the stored workflow when its approval job is on hold; otherwise, it checks for a newer same-name workflow and falls back to the stored workflow when none qualifies. Tests cover target selection and prevent approval on a pipeline mismatch. The documentation describes this behavior.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant Gateway
  participant CircleCIWorkflowAPI
  participant CircleCIApprovalAPI
  Gateway->>CircleCIWorkflowAPI: Fetch stored workflow and verify pipeline
  Gateway->>CircleCIWorkflowAPI: Fetch stored workflow jobs
  alt Stored approval job is on hold
    Gateway->>CircleCIApprovalAPI: Approve stored workflow job
  else Stored approval job is not on hold
    Gateway->>CircleCIWorkflowAPI: List workflows and find a newer same-name rerun
    Gateway->>CircleCIWorkflowAPI: Fetch selected workflow job
    Gateway->>CircleCIApprovalAPI: Approve selected workflow job
  end

Loading

Merge Risk: ⚪ Minimal · up to ab5a2

The change appears ready to merge after normal checks; no concrete approval or verification failure remains identified.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 45.45% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 3 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the primary change: approving the stored CircleCI workflow when the pipeline listing omits it.
Linked Issues check		Issue #153 requires approval through the stored workflow when its approval job is on_hold, rerun lookup only for a non-held original job, fallback to the stored workflow, and pipeline verification b…
Out of Scope Changes check		The changes stay within issue #153. The shared workflowJob type removes duplicated response structs used by the approval flow. The fake CircleCI server and test updates support the required approval…

Full details: Docstring Coverage

Explanation

Docstring coverage is 45.45% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 3 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{A rabbit checked the workflow line,
And found the hold job right on time.
If reruns crossed the garden gate,
The newest match became the mate.
Then off the carrot cart would roll!}

_{Comment @coderabbitai help to get the list of available commands.}