Integration Guide

CI/CD Integration

Integrate APX into your continuous integration pipeline for automated semantic governance. Gate PRs, surface violations, and maintain audit trails.

Quick Start: GitHub Actions

Add APX to your GitHub workflow in 3 steps. The action runs checks on every PR and posts results as comments.

Workflow Configuration

.github/workflows/apx-check.yml
name: APX Semantic Check

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  apx-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Run APX Check
        uses: apx-labs/apx-action@v0
        with:
          policy: 'strict-k8s'
          json-output: true

      - name: Upload APX Results
        uses: actions/upload-artifact@v3
        with:
          name: apx-results
          path: |
            check.core.json
            check.receipt.json
            check.health.json

PASS

All constraints satisfied. PR can merge safely.

WARN

Soft constraints failed. Review needed but not blocked.

BLOCK

Hard constraints or blockers failed. Merge prevented.

PR Comment Template

APX automatically posts structured comments on pull requests. Use this template to customize the format or integrate with your own CI system.

APX Check Result Template
APX Check Result: {{DECISION}}  (policy: {{POLICY_NAME}})
- Hard failures: {{HARD_IDS or "none"}}
- Soft failures: {{SOFT_IDS or "none"}} {{SOFT_MARGINS}}
- Blockers (infra/external): {{BLOCKER_IDS or "none"}}

Details:
- Core JSON: {{LINK_TO_CHECK_CORE_JSON}}
- Receipt (audit): {{LINK_TO_CHECK_RECEIPT_JSON}}
- Health: {{LINK_TO_CHECK_HEALTH_JSON}}

{{#if BLOCKERS}}
⚠️ APX blocked: infra/external blockers [{{BLOCKER_IDS}}] — cannot satisfy policy safely; fix blockers and rerun.
Reason: constraint requires external/infra capability; search halted (no approximation).
Next steps: address listed blockers (e.g., enable HSM/KMS, configure DEA gateway), then rerun.
See [Why APX Blocks](/docs#why-blocks) for details on resolving infra/external constraints.
{{/if}}

{{#if HARD_FAILURES}}
⚠️ Hard constraints failed: [{{HARD_IDS}}]
Details: see check.core.json for margins/locations; see check.receipt.json for audit trail.
{{/if}}

{{#if SOFT_FAILURES}}
⚠️ Soft constraints failed: [{{SOFT_IDS}}]
Proceeding, but debt increased; see core/health JSON for details.
{{/if}}

Template Variables

  • DECISIONPASS, WARN, or BLOCK
  • POLICY_NAMEName of the policy pack used
  • HARD_IDSList of hard constraint failures
  • SOFT_IDSList of soft constraint failures
  • SOFT_MARGINSMargins for soft failures (e.g., "PAT-101: 12%")
  • BLOCKER_IDSInfra/external blockers that halted search

Features

  • Audit-ready links: Direct access to core, receipt, and health JSON files
  • Margin visibility: Shows confidence margins for soft failures to help prioritize fixes
  • Conditional guidance: Different next steps for blockers vs. policy failures
  • Auto-capped lists: Top 20 violations shown; use "show more" for longer lists

Console Output Examples

Infra/External Blockers

$ apx check --json --policy strict-hipaa

🔍 APX Check (policy: strict-hipaa)
   ├─ Evaluating 47 constraints...
   ├─ ✓ 42 passed
   ├─ ⚠ 2 soft failures
   ├─ ✗ 1 hard failure
   └─ 🚫 2 infra/external blockers

❌ BLOCK: infra/external blockers detected → [KMS-AES256-1, HSM-FIPS-2]

Reason: constraint requires external/infra capability; search halted (no approximation).
Next steps: address listed blockers (e.g., enable HSM/KMS, configure DEA gateway), then rerun.
See check.core.json for details.

Hard Constraint Failures (No Blockers)

$ apx check --json --policy strict-k8s

🔍 APX Check (policy: strict-k8s)
   ├─ Evaluating 32 constraints...
   ├─ ✓ 28 passed
   ├─ ✗ 4 hard failures
   └─ 🚫 0 blockers

⚠️ WARN/BLOCK: hard constraints failed → [PDB-MIN-1, HPA-SCALE-2, NET-POL-3, RBAC-NS-1]

Details: see check.core.json for margins/locations; see check.receipt.json for audit trail.
Search continues; fix constraints and rerun.

Soft Constraint Failures

$ apx check --json --policy permissive

🔍 APX Check (policy: permissive)
   ├─ Evaluating 18 constraints...
   ├─ ✓ 15 passed
   ├─ ⚠ 3 soft failures
   └─ 🚫 0 blockers

⚠️ WARN: soft constraints failed → [LOG-FMT-1, METRIC-TAG-2, DOC-COVER-3]

Proceeding, but debt increased; see core/health JSON for details.

Example PR Comments

APX Check Result: BLOCK (Infra Blockers)

APX Check Result: BLOCK (policy: strict-hipaa)

  • - Hard failures: none
  • - Soft failures: none
  • - Blockers (infra/external): KMS-AES256-1, HSM-FIPS-2

Details:

⚠️ APX blocked: infra/external blockers [KMS-AES256-1, HSM-FIPS-2] — cannot satisfy policy safely; fix blockers and rerun.

Reason: constraint requires external/infra capability; search halted (no approximation).

Next steps: address listed blockers (e.g., enable HSM/KMS, configure DEA gateway), then rerun.

See "Why APX Blocks" for details on resolving infra/external constraints →

APX Check Result: WARN (Hard Failures)

APX Check Result: WARN (policy: strict-k8s)

  • - Hard failures: PDB-MIN-1, HPA-SCALE-2
  • - Soft failures: none
  • - Blockers (infra/external): none

Details:

⚠️ Hard constraints failed: [PDB-MIN-1, HPA-SCALE-2]

Details: see check.core.json for margins/locations; see check.receipt.json for audit trail.

Customizing Comments

  • Limit violation lists to top 20 items with a "show more" toggle for readability
  • Include margin percentages for soft failures to help developers prioritize fixes
  • Link to Studio Lite with pre-loaded JSON for visual exploration
  • Add team-specific escalation paths for blocked PRs

Other CI Platforms

GitLab CI

apx-check:
  stage: test
  script:
    - npm install -g @apx/cli
    - apx check --json --policy strict-k8s
  artifacts:
    paths:
      - check.*.json

Use the APX CLI with GitLab's native artifact system

Jenkins

stage('APX Check') {
  steps {
    sh 'npm install -g @apx/cli'
    sh 'apx check --json'
    archiveArtifacts 'check.*.json'
  }
}

Install CLI and run checks in your Jenkinsfile

CircleCI

- run:
    name: APX Check
    command: |
      npm install -g @apx/cli
      apx check --json
- store_artifacts:
    path: check.core.json

Add APX to your CircleCI workflow config

Azure Pipelines

- script: |
    npm install -g @apx/cli
    apx check --json
  displayName: 'APX Check'
- publish: $(Build.SourcesDirectory)
  artifact: apx-results

Integrate with Azure DevOps pipelines