Gemini CLI Governance Files
Define enterprise-wide policies and compliance rules that control how Gemini CLI behaves across your organization. Governance files ensure consistent AI behavior, enforce coding standards, and protect sensitive data for every team member.
What Are Governance Files?
Governance files are configuration documents that define rules, constraints, and policies for how Gemini CLI behaves in your project or organization. Unlike personal configuration files that control user preferences, governance files establish mandatory boundaries that apply to every team member.
They serve three critical functions in an enterprise environment:
- Consistent AI behavior — Every developer on your team gets the same guardrails, coding conventions, and response patterns regardless of their personal setup.
- Coding standard enforcement — Define language-specific rules, naming conventions, architectural patterns, and forbidden practices that Gemini CLI must follow when generating or reviewing code.
- Security and compliance — Restrict which models can be used, block access to sensitive files, prevent dangerous commands, and ensure audit trails for regulated industries.
Think of governance files as your organization's policy layer on top of Gemini CLI — they transform a general-purpose AI tool into one that follows your specific rules.
Governance File Structure
Gemini CLI governance uses a layered file structure. Each file serves a distinct purpose and they combine to form a complete policy framework.
# Project governance file structure
my-project/
GEMINI.md # Project-level instructions (natural language)
.gemini/
settings.json # Machine-readable configuration
policies/
security.md # Security-specific policies
coding-standards.md # Language and style rules
compliance.md # Regulatory compliance rules
GEMINI.md
Project-level instructions written in natural language (similar to Claude's CLAUDE.md). This file tells Gemini CLI about your project's architecture, conventions, and expectations. It is read automatically when Gemini CLI runs in the project directory.
.gemini/settings.json
Machine-readable configuration that enforces hard constraints: allowed models, tool permissions, protected file paths, and blocked commands. These rules cannot be overridden by individual users.
.gemini/policies/
A directory for detailed, topic-specific policy documents. Organize complex governance requirements into separate files for easier maintenance and review.
Governance Hierarchy
Governance files follow a strict inheritance chain. More specific levels override general ones, but restrictions always flow downward:
# Override priority (highest to lowest)
1. Organization-level # Global rules for all teams
2. Team-level # Department-specific policies
3. Project-level # Repository-specific rules
4. User-level # Personal preferences (cannot override restrictions)
Setting Up Governance
Step 1: Create GEMINI.md at Project Root
Start by creating a GEMINI.md file in your project root. This is the primary governance document that Gemini CLI reads automatically.
# GEMINI.md
# Project: Payment Service API
## Architecture
This is a Node.js microservice using Express.js with
TypeScript. We follow a clean architecture pattern with
separate layers for routes, services, and repositories.
## Coding Standards
- Use TypeScript strict mode for all new files
- All functions must have JSDoc comments
- Error handling must use custom AppError classes
- Never use `any` type - use `unknown` and narrow
- All database queries go through the repository layer
## Security Rules
- Never log PII (email, SSN, card numbers)
- All endpoints require authentication middleware
- Use parameterized queries only - no string concatenation
- Secrets must come from environment variables
Step 2: Define Coding Standards
For detailed coding standards, create a dedicated policy file that Gemini CLI will reference when generating or reviewing code.
# .gemini/policies/coding-standards.md
## TypeScript Conventions
- Prefer `interface` over `type` for object shapes
- Use `readonly` for properties that should not change
- Enum values must be UPPER_SNAKE_CASE
- File names must be kebab-case
## Testing Requirements
- Every public function needs at least one unit test
- Test files must be co-located with source files
- Use `describe` / `it` pattern with clear descriptions
- Mock external dependencies, never real services
## Git Commit Messages
- Follow conventional commits: feat|fix|chore|docs
- Include ticket number: feat(PM-123): add payment flow
Step 3: Configure settings.json
The settings file enforces hard, machine-readable constraints that cannot be bypassed. This is where you define model restrictions, tool permissions, and protected paths.
{
"governance": {
"version": "1.0",
"enforced": true,
"allowedModels": ["gemini-2.0-flash-lite", "gemini-2.0-flash"],
"allowedTools": ["read", "write", "search", "grep"],
"protectedPaths": [".env", ".env.*", "secrets/", "*.key", "*.pem"],
"blockedCommands": ["rm -rf", "git push --force", "drop table"]
}
}
Step 4: Distribute to Team via Git
Commit your governance files to version control so every team member receives the same policies when they clone or pull the repository.
# Add governance files to version control
git add GEMINI.md .gemini/settings.json .gemini/policies/
git commit -m "chore: add Gemini CLI governance files"
git push origin main
# Team members automatically get governance on pull
git pull origin main
# Gemini CLI now follows project governance rules
Policy Configuration
The .gemini/settings.json file supports granular policy rules. Each section targets a specific governance concern.
Model Restrictions
Control which AI models your team can use. This prevents accidental usage of expensive or non-compliant models.
"modelPolicy": {
"allowedModels": ["gemini-2.0-flash-lite", "gemini-2.0-flash"],
"defaultModel": "gemini-2.0-flash-lite",
"maxTokenBudget": 100000,
"blockPremiumModels": true
}
This configuration restricts the team to cost-effective Flash models and prevents usage of premium-tier models that might exceed budget.
Tool Permissions
Define which Gemini CLI tools are available. Restrict dangerous tools in production environments or for junior team members.
"toolPolicy": {
"allowedTools": ["read", "write", "search", "grep", "list"],
"blockedTools": ["shell_exec", "network_request"],
"requireConfirmation": ["write", "delete"]
}
Tools listed in requireConfirmation will prompt the user before executing, adding a safety layer for destructive operations.
File Access Controls
Protect sensitive files and directories from being read or modified by Gemini CLI.
"filePolicy": {
"protectedPaths": [
".env",
".env.*",
"secrets/",
"*.key",
"*.pem",
"credentials/"
],
"readOnlyPaths": ["package-lock.json", "yarn.lock"],
"maxFileSize": "5MB"
}
Protected paths are completely invisible to Gemini CLI. Read-only paths can be read but never modified.
Command Restrictions
Block dangerous shell commands that could cause irreversible damage to your codebase or infrastructure.
"commandPolicy": {
"blockedCommands": [
"rm -rf",
"git push --force",
"git reset --hard",
"drop table",
"truncate table",
"chmod 777"
],
"blockedPatterns": ["curl.*| bash", "wget.*| sh"],
"auditAllCommands": true
}
When auditAllCommands is enabled, every command execution is logged for compliance review.
Team-Wide Governance
Sharing via Monorepo or Package
For organizations with multiple repositories, centralize governance in a shared package that all projects reference.
# Option 1: Monorepo shared governance
monorepo/
.gemini/ # Org-level governance
settings.json
policies/
packages/
api-service/
.gemini/settings.json # Project-level overrides
GEMINI.md
web-app/
.gemini/settings.json
GEMINI.md
# Option 2: Shared npm package
npm install --save-dev @your-org/gemini-governance
# Then reference in .gemini/settings.json:
{ "extends": "@your-org/gemini-governance" }
CI/CD Enforcement
Validate governance compliance in your CI/CD pipeline to catch violations before code reaches production.
# .github/workflows/governance-check.yml
name: Governance Compliance
on: [pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Verify governance files exist
run: |
test -f GEMINI.md || exit 1
test -f .gemini/settings.json || exit 1
- name: Validate settings schema
run: npx ajv validate -s governance-schema.json -d .gemini/settings.json
- name: Check for protected path violations
run: gemini governance audit --strict
Governance Inheritance and Overrides
Child projects inherit governance from parent directories. Understanding override rules is essential for multi-team organizations.
Inheritance rule: Restrictions always accumulate. A child project inherits all parent restrictions and can only add more — never remove them.
Override rule: Preferences (default model, output format) can be overridden at lower levels. Restrictions (blocked commands, protected paths) cannot be relaxed.
Conflict resolution: When org-level and project-level settings conflict, the more restrictive setting wins. This ensures security policies are never accidentally weakened.
Compliance Use Cases
Governance files are particularly valuable in regulated industries where AI tool usage must meet strict compliance standards.
HIPAA — Healthcare Data Protection
Prevent Gemini CLI from accessing or processing protected health information (PHI).
{
"hipaaCompliance": {
"protectedPaths": ["patient-data/", "medical-records/", "*.hl7"],
"blockedPatterns": ["SSN", "date_of_birth", "medical_record_number"],
"allowedModels": ["gemini-2.0-flash-lite"],
"auditLog": true,
"dataResidency": "us-only"
}
}
SOC 2 — Security Audit Controls
Ensure comprehensive audit logging and access controls required for SOC 2 Type II certification.
{
"soc2Compliance": {
"auditAllCommands": true,
"auditLogPath": "/var/log/gemini-audit/",
"requireConfirmation": ["write", "delete", "execute"],
"sessionTimeout": 3600,
"accessControl": "rbac"
}
}
GDPR — Data Privacy Protection
Prevent personally identifiable information (PII) from being sent to external AI models.
{
"gdprCompliance": {
"piiDetection": true,
"blockedDataPatterns": ["email", "phone", "address", "national_id"],
"protectedPaths": ["user-data/", "analytics/", "exports/"],
"dataResidency": "eu-only",
"rightToErasure": true
}
}
Financial Services — Code Review Requirements
Enforce mandatory review steps before any AI-generated code can be committed, meeting financial regulatory requirements.
{
"financialCompliance": {
"requireHumanReview": true,
"autoCommit": false,
"protectedPaths": ["transactions/", "ledger/", "*.sql"],
"blockedCommands": ["git commit", "git push"],
"mandatoryTests": true,
"changeApprovalRequired": true
}
}
Governance vs Configuration
Understanding the distinction between governance and configuration is key to using Gemini CLI effectively in a team. They serve fundamentally different purposes.
| Aspect | Configuration | Governance |
|---|---|---|
| Purpose | User preferences | Team and org rules |
| Scope | Individual developer | Entire team or organization |
| Examples | Theme, keybindings, default model | Blocked commands, protected paths, model restrictions |
| Enforcement | Optional, user-controlled | Mandatory, cannot be overridden |
| Storage | User home directory | Project repository (committed to Git) |
| Language | "I prefer", "default to" | "Must not", "must always", "restricted" |
Key principle: Configuration is personal and flexible. Governance is shared and enforced. A developer can change their default model in configuration, but governance can restrict which models are available to choose from. Governance always wins over configuration when they conflict.
Related Questions
Configuration Files Management
Learn how to manage and organize Gemini CLI configuration files for different environments and projects.
Sandbox Mode
Run Gemini CLI in isolated sandbox environments for safe experimentation and testing.
Environment Variables Setup
Set up and manage environment variables for Gemini CLI authentication and configuration.
MCP Server Configuration
Configure Model Context Protocol servers to extend Gemini CLI with additional tool capabilities.