Governance & Policies

GitGov transforms Git from a simple storage tool into a governed platform. By defining a gitgov.toml file per repository, you can enforce branch protection, group-based access control, and policy advisory checks across every developer workstation.

Policy Operational Modes

GitGov governance operates at two levels:

1. Workstation-Level (gitgov.toml)

The gitgov.toml file in the repository root configures branch protection and group permissions. When a developer attempts a push to a protected branch without the required group membership, the operation is blocked and an event is logged.

2. CI Advisory Check (/policy/check)

The Control Plane exposes a /policy/check endpoint that your CI pipeline (e.g. Jenkins) can call before executing a build. It returns an advisory response — allowed, reasons, and warnings — so you can enforce governance at the pipeline level without blocking developer workstations.

Configuring gitgov.toml

Policies are stored per-repository in a gitgov.toml file at the repository root. The file supports three configuration sections:

[branches]

Defines recognized branch patterns and the list of protected branches that block direct pushes.

[groups.*]

Defines named teams with their members, the branches they are allowed to push to, and the code paths they are authorized to modify.

admins

A list of usernames with administrative access across all branches and paths.

Configuration Example

# gitgov.toml — place at the repository root

[branches]
# Recognized naming conventions (informational — used for advisory checks)
patterns  = ["feat/*", "fix/*", "hotfix/*", "release/*", "docs/*"]
# Direct pushes to these branches are blocked for non-admins
protected = ["main", "release/*"]

[groups.backend]
members          = ["alice", "carlos"]
allowed_branches = ["feat/*", "fix/*", "hotfix/*"]
allowed_paths    = ["gitgov/gitgov-server/", "src/"]

[groups.frontend]
members          = ["bob", "diana"]
allowed_branches = ["feat/*", "fix/*"]
allowed_paths    = ["gitgov/src/", "gitgov-web/"]

admins = ["admin-lead", "devops-ops"]

Note: Policy enforcement blocks pushes to protected branches for developers not listed as admins or in a group with explicit allowed_branches access. All blocked operations are recorded as blocked_push events in the audit trail.

CI Advisory Check

For Jenkins and other CI systems, the Control Plane provides a /policy/check endpoint that evaluates whether a given commit or operation is compliant:

curl -s -X POST https://your-control-plane/policy/check \
  -H "Authorization: Bearer $GITGOV_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "YourOrg/YourRepo",
    "commit": "a3f8c2e",
    "branch": "main",
    "user_login": "alice"
  }'

The response includes:

advisory — true if the check is non-blocking
allowed — whether the operation passes current policy
reasons — list of specific violations
warnings — soft advisories (non-blocking)
evaluated_rules — the rules applied to reach this decision

Current state: The /policy/check endpoint is advisory by default and can return blocking HTTP 409 only for explicitly configured scopes. Release governance also has an optional manual workflow gate for customer-selected enforcement. GitGov does not make release blocking the default behavior.

Best Practices for Rollout

Phase 1 — Observation: Deploy gitgov.toml with no protected branches. Review the advisory data from /policy/check to identify frequent violations.
Phase 2 — Branch Protection: Add critical branches to protected. Only admins and explicitly authorized groups can push directly.
Phase 3 — Full Governance: Apply group-based allowed_paths restrictions and integrate /policy/check into your Jenkins pipeline as a gating step.

Next Phase

CI/CD Traceability — Bridge the gap between commits and deployments.