CI validation

Troubleshooting validation and lockfile issues in CI/CD pipelines.

Schema validation failures

Error:

✖ Schema validation failed:
  Line 15: Missing required field 'spec_version'
  Line 23: Invalid severity 'critical' (must be: error, warn, info)

Cause: Rules don’t match JSON Schema requirements.

Common schema mistakes:

1. Missing required fields:

# ❌ Missing fields
id: my-rule
summary: Do the thing
 
# ✅ All required fields
id: my-project.category.my-rule
version: "1.0.0"
spec_version: "1"
rules:
  - id: do-the-thing
    summary: Do the thing
    severity: error

2. Invalid severity:

# ❌ Wrong values
severity: critical
severity: MUST
 
# ✅ Valid values
severity: error   # Must fix
severity: warn    # Should fix
severity: info    # Nice to have

3. Invalid rule ID pattern:

# ❌ Too short or special chars
id: rule1
id: my-project/rule
 
# ✅ Valid format (namespace.category.name)
id: my-project.backend.use-typescript
id: acme.security.no-secrets

Fix:

# Validate locally before committing
aligntrue check
 
# For verbose output
aligntrue check --json

Quick fix checklist:

• Run aligntrue check --json to pinpoint failing fields.
• Add missing frontmatter keys (id, version, spec_version) and valid severities (error|warn|info).
• Normalize IDs to namespace.category.name (no slashes, no short IDs).
• Re-run aligntrue check until it returns exit code 0.

Lockfile drift failures

Error (CI):

✖ Lockfile drift detected

  Expected: abc123...
  Actual:   def456...

Exit code: 1

Cause: The lockfile hash doesn’t match the current rules. This happens when rules changed since the last aligntrue sync.

Fix:

1. Refresh the lockfile in your branch:

# Regenerate lockfile (sync updates it automatically)
aligntrue sync --yes
 
# Commit updated lockfile
git add .aligntrue/lock.json
git commit -m "chore: update lockfile after rule changes"
git push

2. Or skip drift check temporarily:

# CI workflow (not recommended for production)
- run: aligntrue sync --yes
# Skip drift check: don't run `aligntrue drift --gates`

Exit code meanings

Exit code 0 - Success:

All validations passed. Safe to merge.

Exit code 1 - Validation error:

• Schema validation failed
• Lockfile drift detected (when using drift --gates)
• User-fixable issues

Action: Fix the validation errors and retry.

Exit code 2 - System error:

• Config file not found
• Permissions error
• Disk space issues
• Unexpected failures

Action: Check system logs, verify file permissions, ensure sufficient disk space.

Running sync in CI/automation

Non-interactive mode

By default, aligntrue sync shows interactive prompts for agent detection and ignore file management. To run in CI/automation workflows, use one of these flags:

Option 1: Use --yes (recommended)

Automatically accepts prompts, enables detected agents, and manages ignore files using your configured defaults:

aligntrue sync --yes

Behavior with --yes:

• Adds newly detected agents to .aligntrue/config.yaml
• Applies ignore-file updates using sync.auto_manage_ignore_files defaults (on by default)
• Overwrites conflicts using the default resolution strategy
• Skips all interactive prompts (including overwrite confirmations)
• Returns exit code 0 on success
• Returns exit code 1 on validation errors

Option 2: Use --non-interactive (alias -n)

Skips prompts and uses defaults (also auto-adds detected agents, but does not imply --force):

aligntrue sync --non-interactive
# or
aligntrue sync -n

Behavior with --non-interactive:

• Adds newly detected agents to .aligntrue/config.yaml
• Applies ignore-file updates using sync.auto_manage_ignore_files defaults (on by default)
• Uses overwrite as the default resolution strategy for conflicts
• Skips detection and ignore-file prompts
• Useful for validated CI pipelines that need zero prompts

Common CI patterns

GitHub Actions example:

- name: Sync with AlignTrue
  run: aligntrue sync --yes

GitLab CI example:

aligntrue-sync:
  script:
    - aligntrue sync --yes

Jenkins example:

stage('Sync Rules') {
  steps {
    sh 'aligntrue sync --yes'
  }
}

Dry-run for validation

To preview changes without writing files:

aligntrue sync --dry-run --yes

This is useful for:

• Validating that rules will sync correctly
• Checking for schema errors
• Previewing exporter output
• Pre-flight checks before deployment
• Ensuring lockfile and agent updates are understood before writing files

Quick CI tips

• Always run aligntrue check --ci before aligntrue sync in pipelines.
• Use aligntrue sync --dry-run --yes to preview, then aligntrue sync --yes to write files (lockfile included).
• Commit .aligntrue/lock.json whenever rules change in team mode.
• Use aligntrue drift --gates in CI to fail the pipeline if drift is detected.