CI/CD Workflows

proxifai includes a built-in CI/CD system. Define workflows in YAML, trigger them on push, pull request, or manually, and monitor execution with real-time streaming logs. Workflows run on managed or self-hosted runners.

Workflow Definitions

Workflows are defined in .proxifai/workflows/ at the root of your repository — the same directory the workflow engine syncs from on server boot. Each YAML file describes one workflow; bare .proxifai/*.yml is also scanned as a fallback (internal/pipelines/workflows.go).

# .proxifai/workflows/build.yaml
name: Build & Test
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runner: default
    steps:
      - name: Checkout
        uses: checkout

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

      - name: Build
        run: npm run build

  deploy:
    runner: default
    needs: [test]
    when: branch == "main"
    steps:
      - name: Checkout
        uses: checkout

      - name: Deploy to staging
        run: ./scripts/deploy.sh staging
        env:
          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

Jobs and Steps

• Jobs run in parallel by default. Use the needs field to define dependencies between jobs.
• Steps run sequentially within a job. Each step can run a shell command (run) or use a reusable action (uses).
• Conditions — use the when field to conditionally skip jobs or steps based on branch, event, or environment.

Secrets Management

Store sensitive values securely and reference them in workflows:

Environment Variables

Define environment variables at multiple levels:

Scope	Where to set	Overrides
Workflow	Top-level env block in YAML	—
Job	env block within a job	Workflow vars
Step	env block within a step	Job vars
Repository	Repository Settings > Variables	—

Approval Gates

Add manual approval steps before sensitive stages like production deployments:

jobs:
  deploy-prod:
    needs: [deploy-staging]
    approval:
      required_reviewers: ["@devops-team"]
      timeout: 24h
    steps:
      - name: Deploy to production
        run: ./scripts/deploy.sh production

Approvers receive a notification and can approve or reject from the workflow run detail page or the inbox.

Workflow Runners

Workflows execute on runners — agents that pick up and run jobs:

• Managed runners — provided by proxifai. No setup required.
• Self-hosted runners — register your own machines for custom hardware, network access, or compliance needs.

Assign runners to jobs with the runner field. Use labels to target specific runner groups.

Runtime modes

Workflow runs use the same broker as the rest of the workflow engine. CI/CD jobs default to per_execution mode — every run gets a fresh container with 2 CPU and 1Gi memory built from the base image, torn down on completion. Override per workflow via runtime_config if you need a different image, more resources, or a long-lived container:

runtime_config:
  mode: per_workflow      # keep one container warm per workflow
  image: dev-node          # ghcr.io/proxifai/agent-images/dev-node:latest
  cpu: "4"
  memory: 4Gi
  replicas: 2              # round-robin across two warm containers

See Execution modes for the complete configuration reference.

Streaming Logs

Job output streams in real time to the workflow run detail page:

• Each step’s output is displayed in a collapsible section.
• Failed steps are highlighted and expanded by default.
• Download full logs as a text file for offline analysis.

Rerun & Cancel

• Rerun — restart a failed workflow run from the failed job or from the beginning.
• Cancel — stop a running workflow immediately. All in-progress jobs are terminated.

Manual Dispatch

Trigger a workflow manually with custom parameters:

on:
  manual:
    inputs:
      environment:
        type: choice
        options: [staging, production]
        default: staging
      dry_run:
        type: boolean
        default: true

Dispatch from the workflow runs list page by clicking Run Workflow and filling in the input form.

Commit Status Checks

Workflow run results are reported back to the commit and any associated pull requests:

• Pass — green check mark.
• Fail — red X with a link to the failed job.
• Pending — yellow dot while the run is in progress.

Configure branch protection rules to require specific workflows to pass before merging.