Skip to main content

CI Integration

Use agentmesh sync --check in CI to verify that agentmesh.lock and the filesystem are in agreement before merging.

Basic check​

agentmesh sync --check
Exit codeMeaning
0No drift — lockfile matches filesystem
1Drift detected — a real sync would change state (includes auto-resolvable conflicts and auto-imports)
2Strict-mode rule violated (see below)
3Integrity check failed
4Lockfile schema unsupported (upgrade AgentMesh)

--check is a dry run. It never writes files.

Strict mode with agentmesh.config.yaml​

Add optional CI policy keys to fail on specific conditions:

ci:
  fail_on_conflict: true # exit 2 when conflicts would be auto-resolved
  fail_on_capability_skip: false # exit 2 when entities are skipped due to capability mismatch
  require_clean_lock: true # explicit alias for "lockfile must not change"

GitHub Actions example​

name: AgentMesh sync check

on:
  pull_request:
    paths:
      - "AGENTS.md"
      - "CLAUDE.md"
      - ".ai/**"
      - ".claude/**"
      - ".codex/**"
      - "agentmesh.lock"
      - "agentmesh.config.yaml"

jobs:
  agentmesh:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install AgentMesh
        run: curl -fsSL https://agentmesh.sh/install.sh | sh

      - name: Verify sync state
        run: agentmesh sync --check

Adjust the install step once you pin a specific AgentMesh version in CI.

Non-interactive init in CI​

If CI needs to initialize a fresh repo (unusual), pass explicit flags:

agentmesh init --canonical-instructions=AGENTS.md -y --skip-hooks

In non-TTY environments without --canonical-instructions, init exits with code 10 when AGENTS.md and CLAUDE.md diverge. The flag only chooses the starting agent memory file for initial setup; later sync remains bidirectional.

Lockfile merge conflicts​

If a PR has a textual merge conflict in agentmesh.lock:

# after resolving other conflicts, with both sides merged in the working tree:
agentmesh reconcile-lock
git diff agentmesh.lock   # review
git add agentmesh.lock