openclaw - 💡(How to fix) Fix CI/CD: Refactor complex workflow matrices into reusable workflows and JSON configs [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#59727Fetched 2026-04-08 02:41:19
View on GitHub
Comments
0
Participants
1
Timeline
0
Reactions
0
Author
Participants

Code Example

# Lines 30-50: Preflight outputs 20+ conditions
outputs:
  docs_only: ${{ steps.manifest.outputs.docs_only }}
  docs_changed: ${{ steps.manifest.outputs.docs_changed }}
  run_node: ${{ steps.manifest.outputs.run_node }}
  run_macos: ${{ steps.manifest.outputs.run_macos }}
  # ... 17 more outputs

# Lines 200-250: Downstream jobs check these conditions
if: always() && needs.preflight.outputs.run_checks == 'true' && needs.build-artifacts.result == 'success'

---

// .github/matrices/node-tests.json
{
  "include": [
    { "check_name": "test (shard 1/3)", "task": "test", "shard_count": 3, "shard_index": 1 },
    { "check_name": "test (shard 2/3)", "task": "test", "shard_count": 3, "shard_index": 2 },
    { "check_name": "test (shard 3/3)", "task": "test", "shard_count": 3, "shard_index": 3 },
    { "check_name": "channels", "task": "channels" }
  ]
}

---

strategy:
  matrix: ${{ fromJson(needs.preflight.outputs.checks_matrix) }}

---

# .github/workflows/_setup-node.yml
name: Setup Node Environment
on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: '24.x'
      install-bun:
        type: string
        default: 'false'
    outputs:
      cache-hit:
        value: ${{ steps.cache.outputs.cache-hit }}

jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: ./.github/actions/setup-node-env
        with:
          node-version: ${{ inputs.node-version }}
          install-bun: ${{ inputs.install-bun }}

---

jobs:
  preflight:
    uses: ./.github/workflows/_preflight.yml
  
  checks-fast:
    needs: preflight
    if: needs.preflight.outputs.run_checks_fast
    uses: ./.github/workflows/_checks-fast.yml
    with:
      matrix: ${{ needs.preflight.outputs.checks_fast_matrix }}
  
  checks:
    needs: [preflight, build-artifacts]
    if: needs.preflight.outputs.run_checks
    uses: ./.github/workflows/_checks.yml
    with:
      matrix: ${{ needs.preflight.outputs.checks_matrix }}
RAW_BUFFERClick to expand / collapse

Problem

The .github/workflows/ci.yml file has grown to 800+ lines with complex conditional matrices and scattered job dependencies. The preflight job alone outputs 20+ different conditions that downstream jobs consume using brittle if: always() && needs.x.outputs.y == 'true' chains.

Current Pain Points

  1. Hard to reason about — Adding a new platform or check requires touching multiple sections
  2. Duplicated boilerplate — Node setup + artifact download pattern repeated in ~10 jobs
  3. Fragile dependencies — The matrix output pattern creates tight coupling between jobs
  4. Review difficulty — Changes to CI logic require understanding the entire file context

Specific Examples

From .github/workflows/ci.yml:

# Lines 30-50: Preflight outputs 20+ conditions
outputs:
  docs_only: ${{ steps.manifest.outputs.docs_only }}
  docs_changed: ${{ steps.manifest.outputs.docs_changed }}
  run_node: ${{ steps.manifest.outputs.run_node }}
  run_macos: ${{ steps.manifest.outputs.run_macos }}
  # ... 17 more outputs

# Lines 200-250: Downstream jobs check these conditions
if: always() && needs.preflight.outputs.run_checks == 'true' && needs.build-artifacts.result == 'success'

Proposed Solution

Phase 1: Extract Matrix Definitions

Create .github/matrices/ directory with JSON configs:

// .github/matrices/node-tests.json
{
  "include": [
    { "check_name": "test (shard 1/3)", "task": "test", "shard_count": 3, "shard_index": 1 },
    { "check_name": "test (shard 2/3)", "task": "test", "shard_count": 3, "shard_index": 2 },
    { "check_name": "test (shard 3/3)", "task": "test", "shard_count": 3, "shard_index": 3 },
    { "check_name": "channels", "task": "channels" }
  ]
}

Reference in workflow:

strategy:
  matrix: ${{ fromJson(needs.preflight.outputs.checks_matrix) }}

Phase 2: Create Reusable Workflows

Extract common patterns to .github/workflows/_setup-node.yml:

# .github/workflows/_setup-node.yml
name: Setup Node Environment
on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: '24.x'
      install-bun:
        type: string
        default: 'false'
    outputs:
      cache-hit:
        value: ${{ steps.cache.outputs.cache-hit }}

jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: ./.github/actions/setup-node-env
        with:
          node-version: ${{ inputs.node-version }}
          install-bun: ${{ inputs.install-bun }}

Phase 3: Simplify Main Workflow

Target structure:

jobs:
  preflight:
    uses: ./.github/workflows/_preflight.yml
  
  checks-fast:
    needs: preflight
    if: needs.preflight.outputs.run_checks_fast
    uses: ./.github/workflows/_checks-fast.yml
    with:
      matrix: ${{ needs.preflight.outputs.checks_fast_matrix }}
  
  checks:
    needs: [preflight, build-artifacts]
    if: needs.preflight.outputs.run_checks
    uses: ./.github/workflows/_checks.yml
    with:
      matrix: ${{ needs.preflight.outputs.checks_matrix }}

Acceptance Criteria

  • .github/workflows/ci.yml reduced to <300 lines
  • Matrix definitions extracted to JSON files
  • At least 3 reusable workflow patterns extracted
  • No functional changes to CI behavior (verify with test PR)
  • Documentation added in .github/workflows/README.md

References

  • Current CI: .github/workflows/ci.yml
  • Related: Composite actions in .github/actions/

Priority: High Effort: Medium (2-3 days) Labels: ci, refactor, help wanted

extent analysis

TL;DR

Refactor the .github/workflows/ci.yml file by extracting matrix definitions to JSON files and creating reusable workflows to reduce complexity and improve maintainability.

Guidance

  • Extract matrix definitions to JSON files in the .github/matrices/ directory to decouple job dependencies and reduce the number of outputs in the preflight job.
  • Create reusable workflows for common patterns, such as setting up a Node environment, to reduce duplicated boilerplate code.
  • Simplify the main workflow by using the extracted matrix definitions and reusable workflows, and target a structure with clear job dependencies and conditional logic.
  • Verify the changes by checking the reduced line count of the ci.yml file, the extraction of matrix definitions, and the creation of reusable workflow patterns, and ensure no functional changes to CI behavior.

Example

# .github/workflows/_setup-node.yml
name: Setup Node Environment
on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: '24.x'
      install-bun:
        type: string
        default: 'false'
    outputs:
      cache-hit:
        value: ${{ steps.cache.outputs.cache-hit }}

Notes

The proposed solution is a multi-phase refactor, and it's essential to verify each phase to ensure no functional changes to CI behavior. The acceptance criteria provide a clear checklist to validate the changes.

Recommendation

Apply the proposed refactor solution, as it addresses the current pain points, such as complexity, duplicated boilerplate, and fragile dependencies, and improves the maintainability and readability of the CI workflow.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING