Home / Reference / Configuration

Configuration Reference

Configure CodeAnvil behavior with the .anvil/config.yml file in your repository.

Overview

CodeAnvil uses a YAML configuration file located at .anvil/config.yml in your repository root. This file controls branch protection rules, build pipelines, and AI review settings.

yaml

# .anvil/config.yml
# CodeAnvil configuration file

# Branch protection rules - control merge requirements per branch
branch_protection:
  # Branch name (use "*" for all branches, or specify exact name)
  main:
    # Number of approvals required before merge (default: 1)
    required_signatures: 1
    
    # Block force pushes to this branch (default: true)
    block_force_pushes: true
    
    # Automatically merge when all approvals collected (default: false)
    auto_merge: false
    
    # Build configuration for this branch
    build:
      # Enable builds for this branch (default: false)
      enabled: true
      # Require successful build before merge (default: true)
      require_success: true
      # Build timeout in seconds (default: 3600)
      timeout_seconds: 1800
    
    # AI code review configuration
    ai_review:
      # Enable AI review for this branch (default: false)
      # Provider and model are configured by the server
      enabled: true

# Pipeline definition - build steps to run on agents
pipeline:
  # Pipeline version (currently "1.0")
  version: "1.0"
  
  # Environment variables available to all steps
  env:
    GO_VERSION: "1.21"
    CGO_ENABLED: "0"
  
  # Build steps (executed in order)
  steps:
    # Step 1: Download dependencies
    - name: Download Dependencies
      commands:
        - cd $ANVIL_WORKSPACE
        - go mod download
    
    # Step 2: Build the project
    - name: Build
      commands:
        - cd $ANVIL_WORKSPACE
        - go build -v ./...
    
    # Step 3: Run tests
    - name: Test
      commands:
        - cd $ANVIL_WORKSPACE
        - go test -v -race -coverprofile=coverage.out ./...
    
    # Step 4: Run linter
    - name: Lint
      commands:
        - cd $ANVIL_WORKSPACE
        - go vet ./...

Branch Protection

Branch protection rules control what requirements must be met before a PR can be merged.

Configuration Options

Option	Type	Default	Description
`required_signatures`	integer	`1`	Number of approvals required to merge
`block_force_pushes`	boolean	`true`	Block force pushes to this branch
`auto_merge`	boolean	`false`	Automatically merge when all approvals collected
`build.enabled`	boolean	`false`	Enable builds for this branch
`build.require_success`	boolean	`true`	Require successful build before merge
`build.timeout_seconds`	integer	`3600`	Build timeout in seconds
`ai_review.enabled`	boolean	`false`	Enable AI code review
`ai_review.provider`	string	`"zhipu"`	AI provider to use
`ai_review.model`	string	`"glm-4.7"`	AI model to use for review

Branch Patterns

You can configure rules for specific branches or use patterns:

yaml

branch_protection:
  # Specific branch
  main:
    required_signatures: 2
    block_force_pushes: true
  
  # Another specific branch
  develop:
    required_signatures: 1
    auto_merge: true
  
  # Wildcard pattern (catches all other branches)
  "*":
    required_signatures: 1

🔐 Signed Commits Always Required

Signed commits are always required for PRs — this is not configurable. This ensures code authenticity and non-repudiation.

Build Configuration

Configure when builds run and whether they block merging.

yaml

branch_protection:
  main:
    required_signatures: 2
    build:
      enabled: true           # Enable builds
      require_success: true   # Block merge if build fails
      timeout_seconds: 1800   # 30 minute timeout

  develop:
    required_signatures: 1
    build:
      enabled: true
      require_success: false  # Allow merge even if build fails

  "*":
    required_signatures: 1
    build:
      enabled: false  # Disable builds for other branches

Pipeline Definition

Define the build steps that run when code is pushed.

Pipeline Structure

yaml

pipeline:
  version: "1.0"
  
  # Optional: Environment variables available to all steps
  env:
    GO_VERSION: "1.21"
    NODE_VERSION: "18"
  
  # Build steps
  steps:
    - name: Checkout
      commands:
        - echo "Checked out $ANVIL_COMMIT_HASH"
    
    - name: Setup
      commands:
        - echo "Setting up Go $GO_VERSION"
        - go version
    
    - name: Build
      commands:
        - cd $ANVIL_WORKSPACE
        - go build -v ./...
    
    - name: Test
      commands:
        - cd $ANVIL_WORKSPACE
        - go test -v ./...
    
    - name: Lint
      commands:
        - cd $ANVIL_WORKSPACE
        - go vet ./...

Environment Variables

The following variables are available in all pipeline steps:

Variable	Description
`ANVIL_WORKSPACE`	Directory containing the checked out code
`ANVIL_REPO_NAME`	Repository name
`ANVIL_BRANCH`	Branch being built
`ANVIL_COMMIT_HASH`	Full commit hash being built
`ANVIL_COMMIT_SHORT`	Short commit hash (first 7 characters)
`ANVIL_JOB_ID`	Unique job identifier
`ANVIL_REPO_URL`	Repository URL

AI Review Configuration

Enable AI-powered code review for automatic feedback on pull requests.

Basic Configuration

yaml

branch_protection:
  main:
    required_signatures: 1
    ai_review:
      enabled: true

💡 Server Configuration

The AI provider and model are configured by the server administrator. Users only need to enable or disable AI review for their branches.

Complete Examples

Go Project

yaml

# .anvil/config.yml for a Go project
branch_protection:
  main:
    required_signatures: 2
    block_force_pushes: true
    build:
      enabled: true
      require_success: true
      timeout_seconds: 1800
    ai_review:
      enabled: true
  
  develop:
    required_signatures: 1
    build:
      enabled: true
      require_success: false
  
  "*":
    required_signatures: 1

pipeline:
  version: "1.0"
  env:
    GO_VERSION: "1.21"
    CGO_ENABLED: "0"
  steps:
    - name: Download Dependencies
      commands:
        - cd $ANVIL_WORKSPACE
        - go mod download
    
    - name: Build
      commands:
        - cd $ANVIL_WORKSPACE
        - go build -v ./...
    
    - name: Test
      commands:
        - cd $ANVIL_WORKSPACE
        - go test -v -race -coverprofile=coverage.out ./...
    
    - name: Lint
      commands:
        - cd $ANVIL_WORKSPACE
        - go vet ./...
        - go run honnef.co/go/tools/cmd/staticcheck@latest ./...

Node.js Project

yaml

# .anvil/config.yml for a Node.js project
branch_protection:
  main:
    required_signatures: 2
    build:
      enabled: true
      require_success: true
  
  "*":
    required_signatures: 1

pipeline:
  version: "1.0"
  env:
    NODE_VERSION: "18"
  steps:
    - name: Install Dependencies
      commands:
        - cd $ANVIL_WORKSPACE
        - npm ci
    
    - name: Build
      commands:
        - cd $ANVIL_WORKSPACE
        - npm run build
    
    - name: Test
      commands:
        - cd $ANVIL_WORKSPACE
        - npm test
    
    - name: Lint
      commands:
        - cd $ANVIL_WORKSPACE
        - npm run lint

Minimal Configuration

yaml

# .anvil/config.yml - Minimal configuration
branch_protection:
  main:
    required_signatures: 1
  
  "*":
    required_signatures: 1