Skip to main content

CI Integration

GitHub Actions

Integrate DxCore into GitHub Actions to parallelize your CI workloads.

Overview

DxCore fits into GitHub Actions as a coordination layer. You use a matrix strategy to spin up multiple agent jobs, a dispatcher job to submit the task graph, and DxCore’s ci subcommands to manage the session lifecycle.

Workflow Structure

A typical workflow has three phases: session setup, parallel agents + dispatch, and teardown.

name: CI

on: [push, pull_request]



jobs:

  coordinator:

    runs-on: ubuntu-latest

    outputs:

      session_id: ${{ steps.session.outputs.session_id }}

    steps:

      - uses: actions/checkout@v4



      - name: Create session

        id: session

        run: |

          SESSION=$(dxcore ci create-session \

            -c ${{ secrets.DXCORE_URL }} -t ${{ secrets.DXCORE_TOKEN }})

          echo "session_id=$SESSION" >> "$GITHUB_OUTPUT"



      - name: Wait for coordinator

        run: |

          dxcore ci wait \

            -c ${{ secrets.DXCORE_URL }} --timeout 300



  dispatch:

    needs: coordinator

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4

      - name: Dispatch task graph

        run: |

          turbo run build test --dry=json | dxcore dispatch \

            -c ${{ secrets.DXCORE_URL }} \

            -s ${{ needs.coordinator.outputs.session_id }} \

            -t ${{ secrets.DXCORE_TOKEN }} \

            -b turbo



  agents:

    needs: coordinator

    runs-on: ubuntu-latest

    strategy:

      matrix:

        shard: [0, 1, 2, 3]

    steps:

      - uses: actions/checkout@v4

      - name: Run agent

        run: |

          dxcore agent \

            -c ${{ secrets.DXCORE_URL }} \

            -a agent-${{ matrix.shard }} \

            -s ${{ needs.coordinator.outputs.session_id }} \

            -t ${{ secrets.DXCORE_TOKEN }} \

            -b turbo



  finish:

    needs: [dispatch, agents]

    if: always()

    runs-on: ubuntu-latest

    steps:

      - name: Finish session

        run: |

          dxcore ci finish \

            -c ${{ secrets.DXCORE_URL }} \

            -s ${{ needs.coordinator.outputs.session_id }} \

            -t ${{ secrets.DXCORE_TOKEN }}

Required Secrets

Secret Description
DXCORE_URL Coordinator URL (e.g., https://dxcore.example.com)
DXCORE_TOKEN API bearer token for authentication

Warning

Always run the ci finish step with if: always() so the session is cleaned up even when jobs fail.

Agent Tags

Use the --tags flag to pass agent metadata for smarter scheduling:

- name: Run agent

  run: |

    dxcore agent \

      -c ${{ secrets.DXCORE_URL }} \

      -a agent-${{ matrix.shard }} \

      -s ${{ needs.coordinator.outputs.session_id }} \

      -t ${{ secrets.DXCORE_TOKEN }} \

      --tags "runner=github,os=linux"

Next Steps