Ferrum GitForgeOps

Your Gateway, as Code

Manage Ferrum Edge configuration entirely through pull requests. Declarative YAML resources, policy-as-code reviews, encrypted credential brokering, and drift detection — running on GitHub's free tier, with no UI, no Vault, and no paid cloud services required.

View on GitHub Quick Start

Pull-Request Driven Policy as Code GitHub Actions Encrypted Credential Broker Drift Detection

External Secret Managers Needed

~44K

Credential Slots per Environment

Ownership Modes (Shared / Exclusive)

50+

Environments from One Repository

Why GitOps?

The Pull Request Is the Deployment Pipeline

Some teams want a dashboard. Others want every gateway change reviewed, versioned, and applied the same way as application code. GitForgeOps turns a plain GitHub repository into the control plane for your Ferrum Edge fleet.

Every Change Reviewed

Open a PR and a bot review appears per environment: validation results, a change table, policy violations, security findings, and drift — before anything touches a gateway.

Full Audit Trail, Free

Git history and per-environment state files record who changed what, when, and why. No separate audit system, no retention policy to configure — it's just your repository.

Instant Rollback

A bad config is a git revert away. Merge the revert and the same apply pipeline restores the previous state across every environment.

No Secrets in Git

Consumers never store credentials in the repository. Placeholder syntax marks credential slots; values are generated on demand, stored in GitHub Environment Secrets, and delivered to PR authors encrypted to their SSH keys.

No External Dependencies

Everything runs on GitHub's standard features — Environments, Actions, Secrets, and the API. No Vault, no 1Password, no AWS account, no paid tier.

Plays Well with Admins

"Shared" ownership mode manages only the resources you declared and preserves changes made through the Admin API or Foundry. "Exclusive" mode makes the repo authoritative — with mass-deletion safeguards.

How It Works

From Pull Request to Running Gateway

Declare

Add proxies, consumers, upstreams, and plugins as YAML under resources/, with per-environment overrides in overlays/.

Open a PR

validate-pr.yml assembles the config for every environment and posts a per-environment review comment.

Review

Change tables, policy violations, and drift findings surface in the review. Error-severity violations block the apply.

Merge

apply-on-merge.yml applies to each environment with per-environment concurrency locks, incrementally or via full replace.

Watch for Drift

drift-check.yml compares declared config against live gateway state nightly and raises ownership-aware alerts.

In Detail

Declarative Resources, Real Environments

One Repository, Every Environment

Resources live as YAML files organized by namespace and kind. Environment-specific differences — hostnames, timeouts, replica targets — live in overlays, so staging and production share one source of truth.

Proxies, consumers, upstreams, and plugins as individual YAML files
Per-environment overlays instead of copy-pasted configs
Each environment maps to a GitHub Environment with scoped secrets
Parallel matrix workflows validate and apply across all environments
State tracked per environment under .state/

Repository layout

.gitforgeops/
  config.yaml        # environments & ownership
  policies.yaml      # policy rules

resources/
  <namespace>/
    proxies/
    consumers/
    upstreams/
    plugins/

overlays/
  <environment>/
    <namespace>/

.state/
  <environment>.json

Ownership Modes That Respect Your Team

Choose how authoritative the repository is, per environment. Shared mode coexists with admins working through the Admin API or Foundry; exclusive mode makes Git the single source of truth for the namespaces you name.

Shared — manages only previously-declared resources; admin-created resources are preserved
Exclusive — the repo owns its namespaces outright
Large-prune thresholds guard against accidental mass deletion
Incremental or full-replace apply strategies per environment
Drift alerting behavior adapts to the ownership mode

.gitforgeops/config.yaml

version: 1

environments:
  staging:
    overlay: staging
    apply_strategy: incremental
    ownership:
      mode: shared
      drift_report: true

  production:
    overlay: production
    apply_strategy: full_replace
    ownership:
      mode: exclusive
      namespaces: [ferrum]
      large_prune_threshold_percent: 25

default_environment: staging

Credentials Without a Secrets Manager

Declare a consumer's credential slots with placeholders — never actual values. The credential broker generates values on demand, encrypts them with libsodium into GitHub Environment Secrets, and delivers them to the PR author via age encryption keyed to their SSH key.

Zero-knowledge delivery — values never appear in logs or the repo
Automatic secret sharding: ~44,000 credential slots per environment
Manual rotation via the rotate.yml workflow or gitforgeops rotate
Works for API keys, basic auth, and other consumer credential types

resources/ferrum/consumers/app-mobile.yaml

kind: Consumer
spec:
  id: app-mobile
  namespace: ferrum
  credentials:
    api_key:
      key: "${gh-env-secret:alloc=generate}"
    basic_auth:
      username: app-mobile
      password: "${gh-env-secret:alloc=generate|len=48}"

Policy as Code, Enforced in Review

Opt-in policy rules encode your organization's standards. Violations appear directly in the PR review, and error-severity findings block the merge from applying — with a permission-checked, audited override path when you really need it.

proxy_timeout_bands — enforce connect/read/write timeout ranges
backend_scheme — restrict backends to HTTPS, WSS, or gRPCs
require_auth_plugin — mandate authentication on every proxy
allowed_backend_domains — whitelist backend hosts

PR review comment

Environment: `staging` · Ownership: `Shared` · Strategy: `Incremental`

## Ferrum Edge Config Review

### Validation: PASSED

### Changes
| Action | Kind  | ID          | Details                 |
|--------|-------|-------------|-------------------------|
| Add    | Proxy | new-service | -                       |
| Modify | Proxy | my-api      | backend_read_timeout_ms |

### Policy Violations
[error] `backend_scheme` on **Proxy `my-api`**:
backend_protocol=http not in allowed list
(https, wss, grpcs) · BLOCKING

Automation

Workflows and CLI

Five GitHub Actions workflows automate the lifecycle; the gitforgeops CLI runs the same operations locally.

GitHub Actions Workflows

Workflow	Trigger
`validate-pr.yml`	Every PR — matrix validate and review per environment
`apply-on-merge.yml`	Merge to main — apply per environment with concurrency locks
`drift-check.yml`	Nightly — compare declared config against live gateways
`rotate.yml`	Manual — rotate credentials with encrypted delivery
`materialize-file.yml`	Manual — produce a resolved config file encrypted to the requester

CLI Commands

Command	Purpose
`gitforgeops validate`	Check configuration syntax and policies
`gitforgeops plan`	Preview changes without applying
`gitforgeops apply`	Deploy configuration changes
`gitforgeops diff`	Compare live state against declared config
`gitforgeops review --pr N`	Generate PR review comments
`gitforgeops rotate`	Rotate specific credentials
`gitforgeops export --materialize`	Produce encrypted deployment files

Integration

Built on the Ferrum Edge Admin API

GitForgeOps drives the same interfaces Foundry and the CLI use — no side channels, no special agents on your gateways.

API Mode

Pushes configuration to live gateways through the Admin API — full replace via POST /restore or incremental updates, with GET /backup powering drift detection.

File Mode

Assembles a complete resolved YAML for gateways running in file mode — materialized on demand and delivered encrypted for boot-time loading.

Validated Before Apply

Every assembled configuration is validated against the ferrum-edge binary itself, so what passes review is exactly what the gateway will accept.

UI or No UI

GitForgeOps and Foundry Work Together

They're complements, not competitors. Many teams run both: Foundry for observability and day-to-day inspection, GitForgeOps as the change-control path for configuration.

Choose GitForgeOps When…

You want reviewed, versioned, auditable changes; your team already lives in pull requests; you need policy enforcement before anything reaches production; or you simply prefer editing YAML to clicking through a UI.

Choose Foundry When…

You want real-time metrics, health monitoring, and circuit-breaker visibility; you're exploring or debugging a running gateway; or you prefer managing proxies, consumers, and plugins through a modern web UI.

Running both? Use shared ownership mode and GitForgeOps will preserve resources created through Foundry or the Admin API.

Get Started

Quick Start

Prerequisites

GitHub account (free tier works) Ferrum Edge gateway reachable

Fork the repository — ferrum-edge/ferrum-edge-git-forge-ops
Create GitHub Environments matching your declared names (Settings → Environments)
Populate environment secrets — FERRUM_GATEWAY_URL, FERRUM_ADMIN_JWT_SECRET, and any TLS material
Define environments in .gitforgeops/config.yaml
Add resources under resources/<namespace>/
Open a PR to see validation, policy review, and the change plan
Merge to apply across every environment

Your First Resource

resources/ferrum/proxies/my-api.yaml

kind: Proxy
spec:
  id: my-api
  namespace: ferrum
  listen_path: /api
  backend_scheme: https
  backend_host: api.internal.example.com
  backend_port: 443
  strip_listen_path: true

Licensing

Ferrum Edge GitForgeOps is licensed under PolyForm Noncommercial 1.0.0 for non-commercial use. Commercial licenses are available for production deployments.

View on GitHub Licensing Details