Configure workflows

Workflow location

Composal CI reads GitHub Actions-style workflow definitions from .vex/workflows. Keep workflow files with the repository they validate, and treat Composal compatibility as an explicit surface rather than assuming every GitHub Actions feature is available.

Add your first workflow

Create .vex/workflows/tests.yml in the repository. Replace the command below with your project’s dependency setup and test commands; the example assumes scripts/test.sh exists and exits nonzero when tests fail.

name: Tests
on:
  change:
  push:
    branches: [main, master]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - run: sh scripts/test.sh

Use your actual target bookmark instead of main or master if it differs. Declare the tools and dependencies your test command requires; do not assume a runner has your local environment. Submit the workflow through normal review, then open its check to see the job and step output.

Triggers and concurrency

Composal evaluates the configured workflow triggers against repository events and change lifecycle. A checkpoint workflow is opt-in through an explicit on: checkpoint: key, so an agent checkpoint does not silently trigger a bare on: push: workflow.

Split a large test suite across jobs

Use a matrix to run independent portions of a suite concurrently. Each job gets its own runner and dependency setup. Your test script must assign every selected test to exactly one shard and return a nonzero exit code if any test fails.

jobs:
  test:
    runs-on: [linux, x64]
    strategy:
      matrix:
        shard: [1, 2]
    steps:
      - run: sh scripts/test-shard.sh "${{ matrix.shard }}" 2

Replace scripts/test-shard.sh with your suite's partitioning command and add its dependency setup. Both matrix jobs must succeed for the workflow to pass. Keep the number of test processes inside each job within that runner's CPU and memory allocation. More shards consume more runners and repeat setup, so compare total job time and landing time before adding more. Increasing merge-queue concurrency alone does not shorten a test suite that already has a runner.

Configure path filters

Push workflow path filters use the native JJ diff between the old and new bookmark targets, including both sides of a rename. If that diff is unavailable, incomplete, or too large, Composal conservatively runs all otherwise applicable push workflows. Workflows without path filters still run.

Add paths under an event when only certain inputs affect the workflow. Include dependency locks, build scripts, shared libraries, and the workflow itself. For relationships across components, use Selective CI instead of duplicating dependency lists.

on:
  change:
    paths: ["web/**", "shared/**", "pnpm-lock.yaml", ".vex/workflows/web.yml"]
  push:
    branches: [main, master]
    paths: ["web/**", "shared/**", "pnpm-lock.yaml", ".vex/workflows/web.yml"]

Enable remote GitHub CI

When a Composal repository remains connected to GitHub, attach the GitHub App installation during the import or sync setup. This establishes the provider authority and the ability to reflect compatible checks where configured.

See import and sync for GitHub connection options and source control for Composal changes and landing.

Blocking diagnostics

Composal exposes compatibility and workflow diagnostics rather than silently accepting an unsupported configuration. Inspect checks on the change or repository surface before requesting a landing. The server continues to enforce CI, approval, queue-order, and target-freshness gates when a change is landed.

Next: Runners and concurrency, or inspect a failing run.