Skip to content

gitops.md

Latest commit

 

History

History
165 lines (114 loc) · 4.67 KB

gitops.md

File metadata and controls

165 lines (114 loc) · 4.67 KB

GitOps with Flagent

Flagent supports GitOps: flag configuration lives in the repository and syncs via CI/CD.

Overview

  • Export: export flags to YAML/JSON
  • Import: import from file into Flagent
  • GitHub Action: automatic sync on push to main
  • GitHub Webhook: auto-create flag when PR is opened

Quick Start

1. Configure GitHub secrets

In repository Settings → Secrets and variables → Actions add:

Secret Description
FLAGENT_URL Flagent instance URL (e.g. https://flagent.example.com)
FLAGENT_API_KEY API key for import (X-API-Key)

2. Add workflow

Copy .github/workflows/flagent-sync.yml or create:

name: Flagent GitOps Sync
on:
  push:
    branches: [main]
    paths: ['flags.yaml', 'flags/*.yaml']
  workflow_dispatch:
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Sync flags to Flagent
        run: |
          chmod +x scripts/flagent-cli.sh
          ./scripts/flagent-cli.sh import --url ${{ secrets.FLAGENT_URL }} --file flags.yaml --api-key ${{ secrets.FLAGENT_API_KEY }}

3. flags.yaml format

Example:

flags:
  - key: new_checkout
    description: "New checkout flow"
    enabled: false
  - key: dark_mode
    description: "Dark mode UI"
    enabled: true

Full format: Import API.

CLI

The script requires curl and jq (for export/import, flags, and eval). Full reference: CLI Reference.

Export

./scripts/flagent-cli.sh export --url https://flagent.example.com --output flags.yaml --api-key sk-xxx

Import

./scripts/flagent-cli.sh import --url https://flagent.example.com --file flags.yaml --api-key sk-xxx

Flags list / create / eval

# List flags (table or JSON)
./scripts/flagent-cli.sh flags list --url http://localhost:18000
./scripts/flagent-cli.sh flags list --url http://localhost:18000 --output json

# Create a flag
./scripts/flagent-cli.sh flags create --key my_flag --description "My feature" --url http://localhost:18000

# Evaluate a flag
./scripts/flagent-cli.sh eval --flag-key my_flag --entity-id user1 --url http://localhost:18000

See CLI Reference for all options.

Create flag from branch (Trunk-based)

# From current git branch
./scripts/flagent-cli.sh flag create --from-branch --url https://flagent.example.com --api-key sk-xxx

# From specified branch
./scripts/flagent-cli.sh flag create --from-branch feature/new-payment --url https://flagent.example.com --api-key sk-xxx

Branch name is converted to flag key: feature/new-payment → feature_new-payment.

GitHub Webhook (auto-create flag on PR) {#github-webhook}

When a Pull Request is opened, Flagent can create a flag from the branch name.

GitHub setup

  1. Settings → Webhooks → Add webhook

  2. Payload URL:

    https://your-flagent.com/api/v1/integrations/github/webhook

  3. Content type: application/json

  4. Secret: generate a random string and set it. Use the same value for Flagent env var FLAGENT_GITHUB_WEBHOOK_SECRET.

  5. Which events: Let me select individual events → Pull requests

  6. Save webhook.

Flagent configuration

Variable Description Default
FLAGENT_GITHUB_WEBHOOK_SECRET Secret for signature verification (required in production) —
FLAGENT_GITHUB_AUTO_CREATE_FLAG Enable auto-create flag on PR true

Behavior

  • On pull_request with action: opened or synchronize
  • Uses branch from pull_request.head.ref (e.g. feature/new-payment)
  • Converts to key: feature_new-payment
  • If flag does not exist — creates with description Auto from PR #<number> branch: <branch>
  • If flag already exists — returns 200 with no changes

Security

  • Always set FLAGENT_GITHUB_WEBHOOK_SECRET in production
  • Webhook validates X-Hub-Signature-256 (HMAC SHA256)
  • Without valid secret, requests are rejected with 401

Testing webhook

# Without secret (only if FLAGENT_GITHUB_WEBHOOK_SECRET is empty)
curl -X POST https://your-flagent.com/api/v1/integrations/github/webhook \
  -H "Content-Type: application/json" \
  -d '{"action":"opened","pull_request":{"number":1,"head":{"ref":"feature/test"}}}'

The backend unit test that mocks this flow is disabled (it can return 500 in testApplication); the create-from-PR flow is verified against a live Flagent server or in integration tests.

See also