GO Feature Flag

Open-source feature flag solution with file-based configuration and OpenFeature integration. Use when setting up self-hosted feature flags, configuring flag files, or deploying the relay proxy.

When to Use

Automatic activation triggers:

User mentions "GO Feature Flag", "GOFF", or "gofeatureflag"
Project has @openfeature/go-feature-flag-provider dependency
Project has flags.goff.yaml or similar flag configuration
User asks about self-hosted feature flags
Docker/K8s configuration includes gofeatureflag/go-feature-flag image

Related skills:

openfeature
OpenFeature SDK usage patterns
container-development
Docker/K8s deployment

Architecture Overview

┌─────────────────────────────────────────────────────────────┐ │ Application │ │ │ │ │ OpenFeature SDK │ │ │ │ │ GO Feature Flag Provider │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ GO Feature Flag Relay Proxy │ │ ┌─────────────────────────────────────────────────────────┐│ │ │ Retriever ││ │ │ (File, S3, GitHub, HTTP, K8s ConfigMap, etc.) ││ │ └─────────────────────────────────────────────────────────┘│ │ ┌─────────────────────────────────────────────────────────┐│ │ │ Exporter ││ │ │ (Webhook, S3, Kafka, PubSub, etc.) ││ │ └─────────────────────────────────────────────────────────┘│ │ ┌─────────────────────────────────────────────────────────┐│ │ │ Notifier ││ │ │ (Slack, Discord, Teams, Webhook) ││ │ └─────────────────────────────────────────────────────────┘│ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Flag Configuration │ │ (flags.goff.yaml) │ └─────────────────────────────────────────────────────────────┘

Flag Configuration Format

Basic Structure

flags.goff.yaml

flag-name: variations: # All possible values variation1: value1 variation2: value2 defaultRule: # Rule when no targeting matches variation: variation1 targeting: # Optional: targeting rules - name: rule-name query: 'expression' variation: variation2

Boolean Flags

Simple on/off flag

new-feature: variations: enabled: true disabled: false defaultRule: variation: disabled

For String, Number, and Object/JSON flag examples, see REFERENCE.md.

Targeting Rules

Query Syntax

GO Feature Flag uses a CEL-like query syntax for targeting:

targeting:

name: beta-users query: 'groups co "beta"' # contains variation: enabled
name: specific-user query: 'targetingKey eq "user-123"' # equals variation: enabled
name: email-domain query: 'email ew "@company.com"' # ends with variation: enabled
name: premium-tier query: 'plan in ["pro", "enterprise"]' # in list variation: enabled

Operators

Operator Description Example

Equals email eq "test@example.com"

Not equals plan ne "free"

Contains groups co "admin"

Starts with email sw "admin"

Ends with email ew "@company.com"

In list country in ["US", "CA"]

gt , ge , lt , le

Comparisons age gt 18

and , or

Logical plan eq "pro" and country eq "US"

Priority

Rules are evaluated top-to-bottom. First matching rule wins:

targeting:

Highest priority: specific user override

name: test-user query: 'targetingKey eq "test-user-id"' variation: enabled

Second: admin group

name: admins query: 'groups co "admin"' variation: enabled

Third: beta users

name: beta query: 'groups co "beta"' variation: enabled

Fallback is defaultRule

defaultRule: variation: disabled

Rollout Strategies

Percentage Rollout

new-checkout: variations: enabled: true disabled: false defaultRule: percentage: enabled: 20 # 20% of users disabled: 80 # 80% of users

For Progressive Rollout, Scheduled Changes, and A/B Testing patterns, see REFERENCE.md.

Relay Proxy Configuration

Docker Compose (Development)

docker-compose.yaml

services: goff-relay: image: gofeatureflag/go-feature-flag:latest ports: - "1031:1031" # API - "1032:1032" # Health/metrics volumes: - ./flags.goff.yaml:/goff/flags.yaml:ro environment: # Retriever configuration - RETRIEVER_KIND=file - RETRIEVER_PATH=/goff/flags.yaml

  # Polling interval (ms)
  - POLLING_INTERVAL_MS=10000

  # Logging
  - LOG_LEVEL=info
healthcheck:
  test: ["CMD", "wget", "-q", "--spider", "http://localhost:1032/health"]
  interval: 10s
  timeout: 5s
  retries: 3

Environment Variables

Retriever (choose one)

File retriever

RETRIEVER_PATH=/path/to/flags.yaml

S3 retriever

RETRIEVER_BUCKET=my-bucket RETRIEVER_ITEM=flags/production.yaml AWS_REGION=us-east-1

GitHub retriever

RETRIEVER_REPOSITORY_SLUG=owner/repo RETRIEVER_FILE_PATH=flags/production.yaml RETRIEVER_BRANCH=main GITHUB_TOKEN=ghp_xxxx

HTTP retriever

RETRIEVER_URL=https://api.example.com/flags.yaml RETRIEVER_HEADERS=Authorization=Bearer xxx

Polling

POLLING_INTERVAL_MS=30000

Server

HTTP_PORT=1031 ADMIN_PORT=1032 LOG_LEVEL=info|debug|warn|error

For Kubernetes deployment configuration, see REFERENCE.md.

Exporters

Export flag evaluation data for analytics. Supported kinds: webhook , s3 , googlecloud , kafka , pubsub , log .

For detailed exporter environment variable configuration, see REFERENCE.md.

Notifiers

Send notifications on flag changes. Supported: Slack, Discord, Microsoft Teams, Webhook.

For webhook URL configuration, see REFERENCE.md.

CLI Tools

Validate Configuration

Install CLI

go install github.com/thomaspoignant/go-feature-flag/cmd/goff@latest

Validate flag file

goff lint --config flags.goff.yaml

Output format

goff lint --config flags.goff.yaml --format json

Testing Flags Locally

Start relay in foreground

docker run -p 1031:1031 -p 1032:1032
-v $(pwd)/flags.goff.yaml:/goff/flags.yaml:ro
-e RETRIEVER_KIND=file
-e RETRIEVER_PATH=/goff/flags.yaml
gofeatureflag/go-feature-flag:latest

Test flag evaluation

curl -X POST http://localhost:1031/v1/feature/new-feature/eval
-H "Content-Type: application/json"
-d '{"evaluationContext": {"targetingKey": "user-123"}}'

Best Practices

Flag Naming Convention

Namespace by feature/team

checkout.new-payment-form dashboard.beta-widgets api.v2-endpoints

Use consistent suffixes

*.enabled # boolean toggles *.config # object/JSON config *.percentage # rollout percentage

Track Flag Lifecycle

Add metadata comments (YAML supports comments)

new-feature:

Created: 2024-11-01

Owner: team-checkout

Jira: PROJ-123

Target removal: 2025-01-15

variations: enabled: true disabled: false

Monitor and Clean Up

Export evaluation data to track usage
Set up alerts for flags at 100% (ready for removal)
Review flags quarterly for cleanup

For GitOps CI/CD workflow and environment-specific flag patterns, see REFERENCE.md.

Troubleshooting

Flag Not Evaluating Correctly

Check relay logs

docker logs goff-relay

Test evaluation directly

curl -X POST http://localhost:1031/v1/feature/my-flag/eval
-H "Content-Type: application/json"
-d '{"evaluationContext": {"targetingKey": "test", "email": "test@example.com"}}'

Provider Connection Issues

// Check provider initialization const provider = new GoFeatureFlagProvider({ endpoint: process.env.GOFF_RELAY_URL, timeout: 5000, // Increase timeout });

// Handle events provider.on('PROVIDER_READY', () => console.log('Provider ready')); provider.on('PROVIDER_ERROR', (e) => console.error('Provider error', e));

Configuration Not Updating

Check polling interval

POLLING_INTERVAL_MS=10000 # 10 seconds

Verify file is readable

docker exec goff-relay cat /goff/flags.yaml

Check retriever status

curl http://localhost:1032/info

Documentation

Official Docs: https://gofeatureflag.org/docs
Flag Format: https://gofeatureflag.org/docs/configure_flag/flag_format
Relay Proxy: https://gofeatureflag.org/docs/relay-proxy
OpenFeature SDKs: https://gofeatureflag.org/docs/sdk

Related Commands

/configure:feature-flags
Set up complete feature flag infrastructure
/configure:dockerfile
Container configuration best practices

go-feature-flag

Safety Notice

Copy this and send it to your AI assistant to learn