GitOps Flag Sync

Phase 1 — Webhook Receipt

When a pushevent or a merged pull request is detected on your configured branch, your git provider (GitHub, GitLab, or Bitbucket) dispatches a signed HTTP POST to your project's unique ToggleAI webhook endpoint (e.g., https://api.toggleai.fun/git/webhooks). ToggleAI validates the HMAC-SHA256 signature in the X-Hub-Signature-256 header to confirm the payload is authentic and untampered.

Phase 2 — File Fetch & Parse

The engine uses the stored access token to fetch the latest .toggleai/flags.yaml at the exact commit SHA referenced in the webhook payload. The YAML is parsed and validated against the ToggleAI config schema. Unknown fields emit a warning; structurally invalid documents abort the sync and trigger an error notification.

Phase 3 — Diff & Change Detection

The engine computes a diff between the parsed YAML state and the current configuration stored in the ToggleAI database. Only changed flags and configs are updated — unchanged entities are untouched — making syncs efficient and reducing database churn for large flag sets.

Phase 4 — Database Write & Cache Invalidation

Validated changes are committed to the primary database in a single atomic transaction. Immediately after, the edge cache TTLs for affected flags are invalidated so that SDK clients receive updated evaluations on the next polling cycle or SSE push — with no additional manual intervention.

Phase 5 — Sync Status & Audit Log

A sync event entry (including commit SHA, timestamp, changed entities, and status) is appended to the project audit log. The GitOps dashboard in the console reflects the latest sync state, including any validation warnings or conflict tickets needing manual resolution.

Step 1: Connect Repository

Navigate to the project settings in the ToggleAI console under Git Connections and select your provider (GitHub, GitLab, or Bitbucket). Provide a fine-grained access token with read access to repository Contents and read/write access to Webhooks (required for bidirectional sync). The token is encrypted at rest using AES-256.

Step 2: Add Configuration File

Create a file named .toggleai/flags.yaml at the root of your repository. This file is the single source of truth for your flag states, targeting rules, and remote config values. You can scaffold the initial file from your existing flags using the ToggleAI CLI:

toggleai flags export --format yaml > .toggleai/flags.yaml

Step 3: Configure Webhook

ToggleAI provides a unique webhook payload URL visible in the Git Connections dashboard. Register it in your repository webhook settings:

• Payload URL: https://api.toggleai.fun/git/webhooks/{project-id}
• Content type: application/json
• Events: Push and Pull Request (merged)
• Secret: Copy the HMAC secret from the console and paste it into the webhook secret field

Step 4: Select Sync Direction

Choose your synchronization direction in the connection settings. We recommend Git-only for teams adopting Flags-as-Code for the first time to establish a clean one-way source of truth before enabling bidirectional sync.

Git → ToggleAI (Git-only, Recommended)

Commits to your configured branch are the only way to change flag configurations. The console becomes read-only — all edits must go through a pull request. This is the most auditable and conflict-free mode, recommended for regulated industries and large teams.

ToggleAI → Git (Console-only)

Changes made in the ToggleAI console are automatically committed and pushed to the connected branch. The YAML file stays up to date as a git-backed audit trail, but the console remains the primary interface. Useful for teams gradually migrating to Flags-as-Code.

Bidirectional Sync

Changes from both Git pushes and console edits are synchronized. Non-conflicting changes are resolved automatically. When the same flag is modified in both Git and the console simultaneously, ToggleAI pauses auto-sync for that flag and creates a Conflict Ticket requiring manual resolution.

Schema Validation

Every incoming YAML document is validated against the ToggleAI JSON Schema. Fields with incorrect types, unsupported operators, or missing required keys are rejected with a detailed error referencing the exact field path (e.g., flags.new-billing-dashboard.type).

CI Dry-Run via ToggleAI CLI

Add the following GitHub Actions workflow to validate pull requests before merging:

# .github/workflows/toggleai-validate.yml
name: Validate ToggleAI Config
on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install ToggleAI CLI
        run: npm install -g @toggleai/cli
      - name: Validate flags.yaml
        run: toggleai flags validate .toggleai/flags.yaml
        env:
          TOGGLEAI_API_KEY: ${{ secrets.TOGGLEAI_API_KEY }}

Rollback via Git Revert

Because the YAML file is versioned in git, rolling back a bad flag change requires only a git revert. When the revert is pushed, ToggleAI's webhook handler re-processes the file and restores the previous configuration atomically — no manual intervention required.

# Roll back the last commit to .toggleai/flags.yaml
git revert HEAD --no-edit
git push origin main