or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

configuration-management.md core-operations.md dependency-management.md experimental-features.md index.md policy-management.md registry-operations.md utility-operations.md

tile.json

Policy Management

Manage check policies for organizational compliance and governance. Policies provide centralized configuration for lint and breaking change rules that can be applied across multiple modules and organizations.

Capabilities

Policy Operations

Push, update, and manage policies for distributed enforcement across modules.

/**
 * Push a policy to the registry
 * @param policy - Policy files, directories, or archives to push
 */
buf policy push [flags] [policy]

# Key flags:
--label string              Add label to the pushed policy commit
--create                   Create policy if it doesn't exist
--create-visibility string Visibility when creating policy (public, private)

/**
 * Update policy dependencies to latest versions
 */
buf policy update [flags]

# Key flags:
--only strings            Update only specified policies

/**
 * Remove unused policies from configuration
 */
buf policy prune [flags]

Usage Examples:

# Push policy to registry
buf policy push

# Push with label
buf policy push --label v1.0.0

# Push and create if needed
buf policy push --create --create-visibility public

# Update policy dependencies
buf policy update

# Update specific policies only
buf policy update --only buf.build/acme/security-policy

# Remove unused policies
buf policy prune

Registry Policy Management

Create, manage, and configure policies in the Buf Schema Registry.

/**
 * Create a new policy in the registry
 * @param name - Policy name in format owner/policy
 */
buf registry policy create <owner/policy>

# Key flags:
--format string           Output format (text, json)
--visibility string       Policy visibility (public, private)

/**
 * Show detailed information about a policy
 * @param policy - Policy reference (owner/policy[:ref])
 */
buf registry policy info <policy>

# Key flags:
--format string           Output format (text, json)

/**
 * Delete a policy (irreversible)
 * @param policy - Policy reference (owner/policy)
 */
buf registry policy delete <policy>

# Key flags:
--format string           Output format (text, json)

Usage Examples:

# Create policy
buf registry policy create acme/security-policy --visibility public

# Get policy information
buf registry policy info acme/security-policy
buf registry policy info acme/security-policy:v1.0.0

# Delete policy (dangerous!)
buf registry policy delete acme/unused-policy

Policy Commits

Manage individual commits within registry policies.

/**
 * List commits for a policy
 * @param policy - Policy reference (owner/policy)
 */
buf registry policy commit list <policy>

# Key flags:
--format string           Output format (text, json)
--page-size int          Number of commits per page
--page-token string      Page token for pagination
--reverse               List in reverse chronological order

/**
 * Show detailed information about a specific policy commit
 * @param commit - Commit reference (owner/policy:commit-id)
 */
buf registry policy commit info <commit>

# Key flags:
--format string           Output format (text, json)

/**
 * Resolve commit reference to specific commit ID
 * @param policy - Policy reference with label or commit (owner/policy:ref)
 */
buf registry policy commit resolve <policy>

# Key flags:
--format string           Output format (text, json)

/**
 * Add a label to an existing policy commit
 * @param commit - Commit reference (owner/policy:commit-id)
 * @param label - Label name to add
 */
buf registry policy commit add-label <commit> <label>

# Key flags:
--format string           Output format (text, json)
--label string           Label name to add

Usage Examples:

# List policy commits
buf registry policy commit list acme/security-policy

# List with pagination
buf registry policy commit list acme/security-policy --page-size 50

# Get commit details
buf registry policy commit info acme/security-policy:abc123def456

# Resolve label to commit ID
buf registry policy commit resolve acme/security-policy:v1.0.0

# Add label to commit
buf registry policy commit add-label acme/security-policy:abc123def456 stable

Policy Labels

Manage semantic labels for policy commits (versions, aliases, etc.).

/**
 * List labels for a policy
 * @param policy - Policy reference (owner/policy)
 */
buf registry policy label list <policy>

# Key flags:
--format string           Output format (text, json)
--page-size int          Number of labels per page
--page-token string      Page token for pagination
--archived               Include archived labels

/**
 * Show detailed information about a specific policy label
 * @param label - Label reference (owner/policy:label)
 */
buf registry policy label info <label>

# Key flags:
--format string           Output format (text, json)

/**
 * Archive a policy label (hide from default listings)
 * @param label - Label reference (owner/policy:label)
 */
buf registry policy label archive <label>

# Key flags:
--format string           Output format (text, json)

/**
 * Unarchive a previously archived policy label
 * @param label - Label reference (owner/policy:label)
 */
buf registry policy label unarchive <label>

# Key flags:
--format string           Output format (text, json)

Usage Examples:

# List all policy labels
buf registry policy label list acme/security-policy

# Get label information
buf registry policy label info acme/security-policy:v1.0.0

# Archive old version
buf registry policy label archive acme/security-policy:v0.9.0

# Unarchive label
buf registry policy label unarchive acme/security-policy:v0.9.0

# List including archived labels
buf registry policy label list acme/security-policy --archived

Policy Settings

Configure policy-level settings and metadata.

/**
 * Update policy settings
 * @param policy - Policy reference (owner/policy)
 */
buf registry policy settings update <policy>

# Key flags:
--format string           Output format (text, json)
--visibility string       Update policy visibility (public, private)
--description string      Update policy description
--url string             Update policy homepage URL

Usage Examples:

# Update description
buf registry policy settings update acme/security-policy \
  --description "Security and compliance policies"

# Change visibility
buf registry policy settings update acme/security-policy --visibility private

# Update multiple settings
buf registry policy settings update acme/security-policy \
  --url https://security.acme.com \
  --description "Updated security policies"

Policy Configuration

Policy Structure

Policies are defined using YAML configuration files similar to module configuration:

# buf.policy.yaml
version: v1
name: buf.build/acme/security-policy

# Lint rules enforced by this policy
lint:
  use:
    - DEFAULT
    - COMMENTS
  except:
    - ENUM_ZERO_VALUE_SUFFIX
  
  # Path-specific overrides
  ignore_only:
    FIELD_LOWER_SNAKE_CASE:
      - proto/legacy/

# Breaking change rules enforced by this policy
breaking:
  use:
    - FILE
    - PACKAGE
  except:
    - FIELD_SAME_JSON_NAME
    
  # Path-specific overrides  
  ignore_only:
    MESSAGE_NO_DELETE:
      - proto/experimental/

Policy Application

Policies can be applied to modules through various mechanisms:

# buf.yaml - Reference policy in module
version: v1
name: buf.build/acme/user-api

# Apply organizational policy
policies:
  - buf.build/acme/security-policy:v1.0.0
  - buf.build/acme/api-standards:latest

# Module-specific overrides
lint:
  use:
    - DEFAULT
  # Additional rules beyond policy
  except:
    - MESSAGE_PASCAL_CASE  # Override policy requirement

Policy Inheritance

Policies support inheritance and composition:

# Base policy (buf.build/acme/base-policy)
version: v1
name: buf.build/acme/base-policy

lint:
  use:
    - DEFAULT
breaking:
  use:
    - FILE

---

# Extended policy (buf.build/acme/strict-policy)
version: v1
name: buf.build/acme/strict-policy

# Inherit from base policy
extends:
  - buf.build/acme/base-policy:v1.0.0

# Additional strict rules
lint:
  use:
    - COMMENTS    # Add to base rules
  except:
    - ENUM_ZERO_VALUE_SUFFIX  # Override base requirement

Policy References

Reference Formats

# Basic policy reference
buf.build/owner/policy

# Policy with label (version/tag)
buf.build/owner/policy:v1.0.0
buf.build/owner/policy:latest
buf.build/owner/policy:main

# Policy with commit ID
buf.build/owner/policy:abc123def456

Policy Names

# Valid policy names (lowercase, alphanumeric, hyphens)
owner/security-policy
organization/api-standards
company/governance-rules

# Invalid names (uppercase, underscores, special chars)
Owner/Security-Policy    # uppercase not allowed
org/api_standards       # underscores not allowed
company/rules@v1        # special chars not allowed

Error Handling

Policy operations provide detailed error information:

# Common error scenarios
# Policy not found
Error: policy "buf.build/owner/nonexistent" not found

# Permission denied
Error: permission denied for policy "buf.build/owner/private"

# Policy already exists
Error: policy "buf.build/owner/existing" already exists

# Policy rule conflict
Error: policy rule conflicts with module configuration

# Circular policy dependency
Error: circular dependency detected in policy inheritance

Exit Codes

0   # Success
1   # General error (authentication, network, etc.)
2   # Invalid arguments or configuration
3   # Permission denied
4   # Resource not found
5   # Resource already exists
6   # Policy rule conflict

Best Practices

Policy Design

Recommended practices for designing effective policies:

# 1. Start with base policies
buf.build/org/base-policy              # Common rules for all APIs
buf.build/org/public-api-policy        # Additional rules for public APIs
buf.build/org/internal-api-policy      # Rules for internal APIs

# 2. Use semantic versioning for policies
buf.build/org/security-policy:v1.0.0   # Production policy
buf.build/org/security-policy:v2.0.0   # Breaking change in policy

# 3. Provide policy documentation
# Include clear documentation of policy rationale and exceptions

# 4. Test policy changes
# Use policy push --label to test new versions before promotion

Policy Governance

Organizational governance patterns:

# Centralized policy management
Organization Admin → Creates/Updates Policies
Team Leads → Apply Policies to Modules  
Developers → Follow Policy Requirements

# Policy approval workflow
1. Create policy PR in policy repository
2. Review policy changes with stakeholders
3. Test policy with representative modules
4. Deploy policy with semantic version
5. Update module configurations to use new policy

Version

Tile

Files