Installation
Relevant source files
The following files were used as context for generating this wiki page:The Infrastructure as Code Recertification Engine (ICE) is a command-line tool named ice designed to automate the recertification of IaC repositories. Installation involves obtaining the executable, creating a configuration file, and providing necessary authentication credentials via environment variables.
The primary method of deployment is through a CI/CD pipeline, with a reference implementation provided for GitHub Actions. The tool can also be built from source and run locally for testing or manual execution. The core of the setup process is the config.yaml file, which defines the target repository, scanning patterns, and behavior of the engine.
Prerequisites
Before running the application, the following prerequisites must be met:
- Go Environment: Required for building the
iceexecutable from source. The GitHub Actions workflow specifies Go version 1.21. - Git Provider Token: An authentication token for your Git provider (e.g., GitHub, GitLab, Azure DevOps) is required for the engine to interact with the repository API. This token is passed to the application via an environment variable.
- Git: The
gitcommand-line tool is used by the file scanner to clone the target repository.
Sources: github-action.yaml:13-16, internal/provider/github.go:21-23, internal/scan/file_scanner.go:37-41
Installation Methods
Building from Source
The ice executable can be compiled from the project's source code using the Go toolchain.
go build -o ice ./cmd/ice
This command compiles the main application package and creates an executable file named ice in the current directory.
Sources: github-action.yaml:18, cmd/ice/main.go
Using GitHub Actions
The repository includes a github-action.yaml file that defines a workflow for running the recertification process. This is the recommended way to run the engine in a scheduled manner. The workflow can be triggered on a schedule (cron: '0 2 * * 0') or manually (workflow_dispatch).
The diagram below illustrates the steps in the recertify job.
This diagram shows the sequence of steps within the GitHub Actions job to run the recertification engine.
The Run Recertification step executes the ice run command and requires a GITHUB_TOKEN to be set in the environment, which is used for authenticating with the GitHub API.
Sources: github-action.yaml:3-22
Configuration
The ice application is configured primarily through a YAML file. The engine also supports overrides via command-line flags.
Configuration File Loading
The application searches for its configuration file in a specific order of precedence.
The following diagram shows the logic for locating the configuration file.
This diagram illustrates the prioritized search path for the configuration file.
The loading precedence is as follows:
- Path provided by the
--configcommand-line flag. - Path provided by the
ICE_CONFIG_PATHenvironment variable. - Default file named
.ice.yamlin the user's home directory.
Sources: cmd/ice/root.go:41-61
Core Configuration (config.yaml)
The configuration file defines all aspects of the engine's operation. Below are the key top-level sections.
Sources: internal/config/types.go:8-21, example.config.yaml
repository
Specifies the target Git repository to be scanned.
| Key | Type | Description | Required |
|---|---|---|---|
url | string | The full URL of the repository to scan. | Yes |
provider | string | The Git provider. Supported values: github, azure, gitlab. | Yes |
Sources: internal/config/types.go:23-26, example.config.yaml:7-10
auth
Defines the authentication method for the specified provider.
| Key | Type | Description | Required |
|---|---|---|---|
provider | string | The Git provider for authentication. Must match repository.provider. | Yes |
token_env | string | The name of the environment variable containing the personal access token (PAT). | Yes |
Sources: internal/config/types.go:28-31, example.config.yaml:12-15
global
Global settings that affect the entire run.
| Key | Type | Default | Description |
|---|---|---|---|
dry_run | bool | false | If true, the engine runs in read-only mode and does not create pull requests. |
verbose_logging | bool | false | Enables detailed debug logging. |
max_concurrent_prs | int | 5 | The maximum number of concurrent PRs to create. |
default_base_branch | string | main | The default base branch for creating pull requests. |
Sources: internal/config/types.go:33-37, example.config.yaml:17-23
patterns
An array of pattern objects that define which files to scan and their recertification rules.
| Key | Type | Description | Required |
|---|---|---|---|
name | string | A unique name for the pattern. | Yes |
paths | []string | A list of glob patterns to include files. | Yes |
exclude | []string | A list of glob patterns to exclude files from the paths matches. | No |
recertification_days | int | The number of days before a file is considered due for recertification. | Yes |
enabled | bool | Whether this pattern is active. | No |
decorator | string | A string to prepend to files upon recertification, with {timestamp} as a placeholder. | No |
Sources: internal/config/types.go:39-47, example.config.yaml:25-42
Running the Engine
The main entry point for executing a scan is the ice run command.
./ice run
This command initiates the entire recertification process. It can be modified with flags that override settings in the configuration file.
| Flag | Corresponding Config | Description |
|---|---|---|
--dry-run | global.dry_run | Run without creating PRs. |
--repo-url | repository.url | Repository URL to scan (overrides config). |
Sources: cmd/ice/run.go:13-16, 57-63
The following sequence diagram shows the high-level flow when ice run is executed.
This diagram outlines the initialization and execution sequence triggered by the run command.
Sources: cmd/ice/run.go:17-45, internal/engine/engine.go:33-70, 72