CI/CD integration

Automate formae in your pipelines.

Scenarios covered:

I want to integrate formae into a build/delivery pipeline

When to use this

Use this workflow when you:

  • Need automated, repeatable deployments — no manual formae apply from a laptop
  • Run different environments from the same forma — dev, staging, production parameterized via properties
  • Want guardrails — simulate changes in CI before applying in CD

What you'll do

  1. Validate in CI — catch syntax errors and preview changes
  2. Deploy in CD — apply changes automatically on merge
  3. Parameterize — deploy to multiple environments from one forma

Step-by-step

Before you begin: review the baseline prerequisites and ensure your CI runner can reach the agent.

Step 1: Validate in CI

Use formae eval to catch syntax and type errors, and --simulate to preview what would change — without touching anything:

# Validate syntax and types
formae eval infrastructure/main.pkl

# Preview changes (no cloud API calls)
formae apply --mode reconcile --simulate infrastructure/main.pkl

Step 2: Deploy in CD

Apply infrastructure changes when code lands on your main branch:

formae apply --mode reconcile --yes --watch infrastructure/main.pkl

Key flags for automation:

Flag Purpose
--yes Skip interactive confirmation prompts
--watch Block until the command completes (exits 0 on success, non-zero on failure)

Step 3: Parameterize for multiple environments

Use properties to deploy the same forma to different environments. Properties defined in your forma automatically become CLI flags:

# Deploy to staging
formae apply --mode reconcile --yes --watch --env staging infrastructure/main.pkl

# Deploy to production
formae apply --mode reconcile --yes --watch --env production infrastructure/main.pkl

See what flags are available:

formae apply --help infrastructure/main.pkl

Step 4: Use machine-readable output

For pipelines that need to parse results downstream, add --output-consumer=machine --output-schema=json:

formae apply --mode reconcile \
  --yes --watch \
  --output-consumer=machine \
  --output-schema=json \
  infrastructure/main.pkl > apply-result.json

Tips + gotchas

Tip Details
One agent, many clients Multiple pipelines (and humans) can connect to the same agent simultaneously. Don't start an agent per job.
Use --watch in CI Without it, formae apply returns immediately with a command ID. The pipeline won't wait for completion.

Common gotcha: Avoid running two applies against the same stack/target at the same time. Symptom: interleaved updates and unexpected conflicts. Fix: use your CI system's concurrency controls to serialize deploys per stack.

What's next

Goal Guide
Parameterize with properties Core Concepts → Properties
Self-service for developers Platform Engineering → Self-service infrastructure
Machine output reference CLI → Apply