Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• iac-recert-engine/example.config.yaml
• iac-recert-engine/cmd/ice/run.go
• iac-recert-engine/internal/engine/engine.go
• iac-recert-engine/internal/config/types.go
• iac-recert-engine/cmd/ice/root.go
• iac-recert-engine/internal/scan/recert_checker.go
• iac-recert-engine/internal/scan/file_scanner.go
• iac-recert-engine/internal/provider/github.go
• iac-recert-engine/github-action.yaml
• iac-recert-engine/internal/pr/generator.go

The Infrastructure as Code Recertification Engine (ICE) is a tool designed to automate the periodic review and recertification of IaC files within a repository. It operates by scanning for files based on defined patterns, checking their last modification date against a configured threshold, and automatically generating pull requests to assign the review task to the appropriate individuals or teams. This process ensures that infrastructure configurations remain current, compliant, and necessary.

The engine is driven by a central configuration file and can be executed as a command-line tool or integrated into a CI/CD pipeline, such as GitHub Actions. It supports multiple Git providers, including GitHub, Azure DevOps, and GitLab, and offers flexible strategies for grouping files into pull requests and assigning reviewers.

Sources: iac-recert-engine/cmd/ice/root.go:10-13, iac-recert-engine/internal/engine/engine.go

Configuration

The engine's behavior is controlled by a single YAML configuration file. The tool searches for this file using the --config flag, the ICE_CONFIG_PATH environment variable, or in default locations like $HOME/.ice.yaml.

Sources: iac-recert-engine/cmd/ice/root.go:34-53

Configuration Structure

The configuration file is composed of several key sections that define the scanning, authentication, and pull request generation behavior.

This diagram shows the hierarchical structure of the main configuration options.

Key Configuration Sections

The following table details the primary sections within the configuration file.

Section	Description	Key Fields
repository	Specifies the target repository to be scanned.	url (required, URL), provider (required, one of github, azure, gitlab).
auth	Defines authentication credentials for the Git provider.	provider (required), token_env (required, name of the env var holding the PAT).
global	Global settings that affect the entire run.	dry_run (boolean), verbose_logging (boolean), default_base_branch (string).
patterns	An array defining file groups to scan. This is the core of the scanning logic.	name, paths (glob patterns), exclude (glob patterns), recertification_days (integer).
pr_strategy	Determines how files needing recertification are grouped into pull requests.	type (one of per_file, per_pattern, per_committer, single_pr, plugin).
assignment	Defines how pull requests are assigned to users or teams.	strategy (one of static, last_committer, plugin, composite), fallback_assignees.
pr_template	Configures the content of the generated pull requests.	title, include_file_list, include_checklist, custom_instructions.
audit	Configures audit logging.	enabled, storage (one of file, s3).

Sources: iac-recert-engine/internal/config/types.go, iac-recert-engine/example.config.yaml

Example Pattern Configuration

Patterns are used to identify which files to monitor. Each pattern specifies file paths to include/exclude and the recertification period.

patterns:
  - name: "terraform-prod"
    description: "Production Terraform configurations"
    paths:
      # Glob patterns to include
      - "terraform/prod/**/*.tf"
      - "!terraform/prod/modules/**" # Exclude modules
    exclude:
      # Glob patterns to exclude
      - "**/*.test.tf"
    # Number of days before recertification is required
    recertification_days: 180
    enabled: true
    # Decorator to add to files when recertifying (optional)
    decorator: "# Last Recertification: {timestamp}\n"

Sources: iac-recert-engine/example.config.yaml:27-41, iac-recert-engine/internal/config/types.go:38-46

Execution

The recertification process is initiated via the run command. The engine can be executed locally or as part of a CI/CD pipeline.

Sources: iac-recert-engine/cmd/ice/run.go:15-17

Command-Line Interface

To start the process, run the following command:

./ice run

The run command accepts flags to override configuration settings:

• --dry-run: Executes the entire process without creating branches, commits, or pull requests. It logs the actions that would have been taken.
• --repo-url: Overrides the repository.url setting from the configuration file.

Sources: iac-recert-engine/cmd/ice/run.go:50-56

Execution Flow

The engine.Run function orchestrates the entire recertification process, from initialization to pull request creation.

The diagram below illustrates the sequence of operations performed by the engine.

1. Initialization: The run command loads the configuration, sets up a logger, and initializes the main Engine struct. This involves creating a Git provider instance (e.g., for GitHub) based on the auth and repository settings.
   Sources: iac-recert-engine/cmd/ice/run.go:18-35, iac-recert-engine/internal/engine/engine.go:32-67
2. Scan: The Scanner clones the target repository into a temporary directory and finds all files that match the configured patterns.
   Sources: iac-recert-engine/internal/scan/file_scanner.go:27-106, iac-recert-engine/internal/engine/engine.go:77-80
3. Enrich: The HistoryAnalyzer takes the list of scanned files and uses the Git provider to fetch the last modification date and commit details for each file.
   Sources: iac-recert-engine/internal/scan/git_history.go:24-58, iac-recert-engine/internal/engine/engine.go:88-91
4. Check: The Checker evaluates each enriched file. It compares the time since the last modification against the recertification_days threshold from the matching pattern to determine if recertification is needed and to assign a priority.
   Sources: iac-recert-engine/internal/scan/recert_checker.go:19-107, iac-recert-engine/internal/engine/engine.go:94-97
5. Group: The Strategy module groups all files needing recertification into logical units based on the configured pr_strategy (e.g., one PR per pattern).
   Sources: iac-recert-engine/internal/engine/engine.go:100-103
6. Process Groups: For each group, the engine resolves assignees, generates the PR title and body, and then uses the Git provider to create a new branch, commit the changes (including any decorators), and open a pull request. If dry_run is enabled, these final steps are skipped and logged instead.
   Sources: iac-recert-engine/internal/engine/engine.go:122-228

Recertification Check Logic

The Checker determines a priority for each file based on how overdue it is for recertification.

Priority	Condition (daysSince / threshold)	NeedsRecert
Critical	> 1.5	true
High	>= 1.0	true
Medium	>= 0.8	false
Low	< 0.8	false

Note: The priority is set to "Medium" if a file is approaching its due date but has not yet passed it. This can be used for notifications without creating a PR.

Sources: iac-recert-engine/internal/scan/recert_checker.go:70-88

Running with GitHub Actions

The engine is designed to run in CI/CD environments. A sample workflow for GitHub Actions is provided to run the recertification check on a schedule.

name: IaC Recertification

on:
  schedule:
    - cron: '0 2 * * 0' # Weekly on Sunday at 2am
  workflow_dispatch:

jobs:
  recertify:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    
    - name: Set up Go
      uses: actions/setup-go@v4
      with:
        go-version: '1.21'
        
    - name: Build ICE
      run: go build -o ice ./cmd/ice
      
    - name: Run Recertification
      run: ./ice run
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

This workflow builds the ice binary and executes the run command. It uses the GITHUB_TOKEN secret for authentication with the GitHub API. The configuration is expected to be present in the repository (e.g., as .ice.yaml or config.yaml).

Sources: iac-recert-engine/github-action.yaml