Development Setup

Relevant source files

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

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

The IaC Recertification Engine (ICE) is a command-line tool written in Go, designed to automate the recertification of Infrastructure as Code (IaC) repositories. It operates by scanning for files based on configured patterns, checking their last modification dates against a defined threshold, and generating pull requests to prompt for review and recertification. This document outlines the necessary steps for setting up a local development environment, configuring the engine, and executing a run.

The development workflow involves building the Go binary, creating a configuration file, and running the engine against a target repository. The core logic is encapsulated within the Engine struct, which orchestrates scanning, analysis, and PR creation. Testing is a key part of the development cycle, with tests designed to run against local, temporary Git repositories to ensure functionality without requiring live network access for every scenario.

Sources: iac-recert-engine/cmd/ice/root.go:11-14, iac-recert-engine/internal/engine/engine_test.go

Prerequisites

• Go: Version 1.21 or later.
• Git: Required for cloning repositories during the scan phase.

Sources: iac-recert-engine/github-action.yaml:14, iac-recert-engine/internal/scan/file_scanner.go:34-38

Building the Application

The application is a standard Go project. The main entry point is located in cmd/ice/main.go. To build the executable, run the following command from the root of the repository:

go build -o ice ./cmd/ice

This will produce an executable file named ice in the project's root directory.

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

Configuration

The engine is configured via a YAML file. The configuration path can be specified using the --config flag, the ICE_CONFIG_PATH environment variable, or by placing a .ice.yaml file in the user's home directory.

Sources: iac-recert-engine/cmd/ice/root.go:35-52

Configuration Structure

The main configuration object is defined in internal/config/types.go and has several nested sections. The diagram below illustrates the high-level structure.

Sources: iac-recert-engine/internal/config/types.go:8-22

Key Configuration Sections

repository

Defines the target repository to be scanned.

Field	Type	Description	Validation
url	string	The full URL of the repository to scan.	required, url
provider	string	The Git provider. Supported values: github, azure, gitlab.	required, oneof=github azure gitlab

Sources: iac-recert-engine/internal/config/types.go:24-27, iac-recert-engine/example.config.yaml:8-12

auth

Specifies authentication details for the Git provider.

Field	Type	Description	Validation
provider	string	The Git provider for authentication. Must match repository.provider.	required, oneof=github azure gitlab
token_env	string	The name of the environment variable containing the PAT.	required

Sources: iac-recert-engine/internal/config/types.go:29-32, iac-recert-engine/example.config.yaml:15-18

global

Global settings that affect the engine's behavior.

Field	Type	Description	Default
dry_run	boolean	If true, no PRs will be created (read-only mode).	false
verbose_logging	boolean	Enables detailed debug logging.	false
max_concurrent_prs	int	Maximum number of concurrent PRs to create.	5
default_base_branch	string	The base branch for creating PRs (e.g., main).	main

Sources: iac-recert-engine/internal/config/types.go:34-39, iac-recert-engine/example.config.yaml:21-27

patterns

An array of patterns to identify files for recertification.

Field	Type	Description	Validation
name	string	A unique name for the pattern.	required
description	string	A human-readable description of the pattern.	-
paths	[]string	An array of glob patterns to include files.	required
exclude	[]string	An array of glob patterns to exclude files from the paths matches.	-
recertification_days	int	The number of days after which a file is considered due for recertification.	required, min=1
enabled	boolean	Whether this pattern is active.	-
decorator	string	A string to prepend to the file content upon recertification. {timestamp} is replaced.	-

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

pr_strategy

Defines how files needing recertification are grouped into pull requests.

Field	Type	Description	Validation
type	string	The grouping strategy. Options: per_file, per_pattern, per_committer, single_pr, plugin.	required, oneof=...
max_files_per_pr	int	An optional limit on the number of files per PR.	-

Sources: iac-recert-engine/internal/config/types.go:52-56, iac-recert-engine/example.config.yaml:65-67

assignment

Defines how pull requests are assigned to users or teams.

Field	Type	Description	Validation
strategy	string	The assignment strategy. Options: static, last_committer, plugin, composite.	required, oneof=...
rules	[]AssignmentRule	Rules for the composite strategy.	-
fallback_assignees	[]string	Default assignees if a strategy fails or no rule matches.	-

Sources: iac-recert-engine/internal/config/types.go:58-63, iac-recert-engine/example.config.yaml:70-80

Running the Engine

The main command to execute a recertification scan is ice run.

./ice run

Command-Line Flags

The run command accepts flags that can override settings in the configuration file.

Flag	Viper Binding	Description
--dry-run	global.dry_run	Run without creating PRs.
--repo-url	repository.url	Repository URL to scan (overrides config).
--config	(none)	Path to the configuration file.

Sources: iac-recert-engine/cmd/ice/run.go:46-52, iac-recert-engine/cmd/ice/root.go:35-36

Execution Flow

When ice run is executed, it initializes the core Engine and triggers its Run method. The process follows a series of distinct steps to identify and act on files needing recertification.

This diagram shows the sequence of operations within the Engine.Run method.

1. 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/engine/engine.go:84-87, iac-recert-engine/internal/scan/file_scanner.go:27-41
2. Enrich: The HistoryAnalyzer takes the list of found files and uses the Git provider to fetch the last modification date and commit details for each file.
   Sources: iac-recert-engine/internal/engine/engine.go:97-100, iac-recert-engine/internal/scan/git_history.go:26-49
3. Check: The Checker compares each file's last modification date against its pattern's recertification_days threshold to determine if it needs recertification. It also assigns a priority (Critical, High, Medium, Low).
   Sources: iac-recert-engine/internal/engine/engine.go:103-106, iac-recert-engine/internal/scan/recert_checker.go:66-99
4. Group: The configured Strategy implementation groups the files that need recertification into logical units, where each unit will become a single pull request.
   Sources: iac-recert-engine/internal/engine/engine.go:109-112, iac-recert-engine/internal/strategy/strategy.go:21-27
5. Process Groups: For each group, the engine:
   • Resolves assignees using the assignment strategy.
   • Generates the PR title and description using the pr_template.
   • If not a dry run, it uses the Git provider to create a new branch, commit the changes (including decorators), and open a pull request.
     Sources: iac-recert-engine/internal/engine/engine.go:115-125, 145-234

Local Testing

The project includes tests that validate the engine's logic by running it against a temporary, local Git repository. This is a crucial part of the development setup, as it allows for testing the file scanning, checking, and grouping logic without network dependencies.

The test setup in engine_test.go demonstrates this pattern:

1. A temporary directory is created using os.MkdirTemp.
2. A new Git repository is initialized in this directory using exec.Command("git", "init", ...).
3. Test files are written to the directory and committed.
4. The engine is configured to use a file:// URL pointing to the temporary repository.
5. The engine is executed with DryRun: true to verify the logic that would lead to a PR, without actually creating one.

This approach is recommended for developing new features or debugging existing ones.

Sources: iac-recert-engine/internal/engine/engine_test.go:121-171