Core Concepts

Relevant source files

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

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

The Infrastructure as Code Recertification Engine (ICE) is a tool designed to automate the periodic review and recertification of infrastructure files within a Git repository. It operates by scanning for files based on user-defined patterns, checking their last modification date against a configured threshold, and creating pull requests for files that are due for review. This process ensures that infrastructure configurations remain current, compliant, and necessary.

The engine's workflow is a multi-stage pipeline orchestrated by the main Engine component. It begins with configuration loading and initialization, proceeds through scanning and analysis, and culminates in the creation of pull requests on a specified Git provider like GitHub, Azure DevOps, or GitLab. The entire process is highly configurable through a central config.yaml file.

Sources: iac-recert-engine/cmd/ice/run.go:14-16, iac-recert-engine/internal/engine/engine.go:80-132

Execution Flow

The Engine.Run method orchestrates the entire recertification process. It executes a sequence of five main steps: Scan, Enrich, Check, Group, and Process. If the dry_run flag is enabled, the final step will log the actions it would have taken without actually creating any branches or pull requests.

Sources: iac-recert-engine/internal/engine/engine.go:80-132, iac-recert-engine/example.config.yaml:18

The following diagram illustrates the high-level execution flow of the engine.

Core Data Structures

The engine relies on a set of core data structures to pass information between its different stages. These types are central to the flow of data from initial file discovery to final pull request creation.

Sources: iac-recert-engine/internal/types/types.go

The relationship between these key data structures is shown below.

Structure	Description	Source File
FileInfo	Represents a single file discovered during the scan phase, enriched with Git history information.	internal/types/types.go:8-16
RecertCheckResult	Contains the outcome of checking a FileInfo against a recertification pattern, including priority and whether it needs action.	internal/types/types.go:18-26
FileGroup	A collection of RecertCheckResult objects that will be handled in a single pull request, grouped according to a defined strategy.	internal/types/types.go:28-34
PRConfig	Holds all the necessary information to create a pull request, such as title, description, branch names, and assignees.	internal/types/types.go:44-53

Configuration

The engine's behavior is controlled by a single YAML configuration file. This file defines the target repository, authentication, scanning patterns, and strategies for grouping and assignment.

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

Key Configuration Sections

Section	Description	Example
repository	Specifies the URL of the Git repository to scan and its provider type.	url: "https://github.com/baldator/iac-recert-engine%22%60%3Cbr%3E%60provider%3A "github"
auth	Defines the authentication method, typically by referencing an environment variable containing a personal access token.	provider: "github" token_env: "GITHUB_TOKEN"
global	Contains global settings like dry_run mode, logging verbosity, and the default base branch for PRs.	dry_run: false default_base_branch: "main"
patterns	An array of rules that define which files to scan, their recertification period, and an optional decorator to apply.	See patterns section below.
pr_strategy	Determines how files needing recertification are grouped into pull requests.	type: "per_pattern"
assignment	Defines the strategy for assigning pull requests to users or teams.	strategy: "composite"
pr_template	Configures the template for the title and body of the generated pull requests.	title: "🔄 Recertification: {pattern_name}"

Sources: iac-recert-engine/example.config.yaml:6-75, iac-recert-engine/internal/config/types.go:8-76

Patterns

Patterns are the core of the scanning logic. Each pattern defines a set of files to monitor using glob paths, along with a recertification_days threshold.

patterns:
  - name: "terraform-prod"
    description: "Production Terraform configurations"
    paths:
      - "terraform/prod/**/*.tf"
      - "!terraform/prod/modules/**" # Exclude modules
    exclude:
      - "**/*.test.tf"
    recertification_days: 180
    enabled: true
    decorator: "# Last Recertification: {timestamp}\n"

Sources: iac-recert-engine/example.config.yaml:25-36, iac-recert-engine/internal/config/types.go:37-45

Analysis and Checking

Scanning and Enrichment

1. Scanning: The Scanner clones the target repository into a temporary directory. It then walks the filesystem, matching file paths against the paths and exclude glob patterns defined in the configuration. It returns a list of FileInfo objects.
   Sources: iac-recert-engine/internal/scan/file_scanner.go:28-111
2. Enrichment: The HistoryAnalyzer takes the list of FileInfo objects and, for each file, queries the GitProvider to get the last commit details. This enriches each FileInfo object with its LastModified date and commit author information.
   Sources: iac-recert-engine/internal/scan/git_history.go:24-58

Recertification Check

The Checker processes the enriched FileInfo list. For each file, it finds the corresponding pattern and compares the time since the LastModified date with the recertification_days threshold. Based on this comparison, it determines if the file NeedsRecert and assigns a priority level.

Sources: iac-recert-engine/internal/scan/recert_checker.go:21-105

Priority Calculation

The priority is calculated based on how long the file has been due for recertification.

Condition	Priority
ratio > 1.5	Critical
ratio >= 1.0	High
ratio >= 0.8	Medium
ratio < 0.8	Low

(where ratio = daysSince / threshold)

Sources: iac-recert-engine/internal/scan/recert_checker.go:77-89

Grouping and PR Generation

Grouping Strategies

After the check phase, all files that need recertification are grouped together based on the configured pr_strategy. This determines how many pull requests will be created.

Strategy	Description
per_file	Creates a separate pull request for each individual file.
per_pattern	Groups all files that match the same configuration pattern into a single pull request.
per_committer	Groups all files last modified by the same author into a single pull request.
single_pr	Groups all files needing recertification across all patterns into one large pull request.

Sources: iac-recert-engine/internal/strategy/strategy.go:13-23, iac-recert-engine/example.config.yaml:50-51

PR Processing Flow

For each FileGroup, the engine executes a series of steps to create a pull request. This involves resolving assignees, generating the PR content, and interacting with the Git provider API.

The following sequence diagram shows the interactions within the processGroup function.

If a decorator is specified in the pattern, the engine will prepend a line to each file in the commit, typically containing a timestamp of the recertification. This action of modifying the file effectively "recertifies" it, as its LastModified date is now updated.

Sources: iac-recert-engine/internal/engine/engine.go:193-222, iac-recert-engine/example.config.yaml:35