CLI Usage (`ice`)
Relevant source files
The following files were used as context for generating this wiki page:The ice command-line interface is the primary entry point for the Infrastructure as Code (IaC) Recertification Engine. It is a tool designed to automate the recertification of IaC repositories by scanning for files, checking their modification dates against configured policies, and generating pull requests for review and recertification.
The CLI is responsible for parsing commands and flags, loading and validating configuration, initializing the core engine, and executing the recertification workflow. It is built using the cobra and viper libraries for command structure and configuration management.
Sources: iac-recert-engine/cmd/ice/root.go:12-16
Commands
The ice CLI is structured around a root command and subcommands.
| Command | Description |
|---|---|
ice | The base command. It handles global flags and configuration loading. |
ice run | Executes the main recertification process of scanning and creating PRs. |
Sources: iac-recert-engine/cmd/ice/root.go:12-16, iac-recert-engine/cmd/ice/run.go:13-15
Global Configuration
The ice CLI's behavior is primarily controlled by a YAML configuration file. The location of this file can be specified in several ways, with a clear order of precedence.
Sources: iac-recert-engine/cmd/ice/root.go:40-62
Configuration Loading
The initConfig function determines which configuration file to use. The following diagram illustrates the search order.
This diagram shows the precedence for loading the configuration file.
Sources: iac-recert-engine/cmd/ice/root.go:40-62
Global Flags
| Flag | Description | Viper Key |
|---|---|---|
--config | Specifies the path to the configuration file. | N/A |
Sources: iac-recert-engine/cmd/ice/root.go:33-34
ice run Command
This is the main operational command. It triggers the entire recertification workflow, from loading configuration to potentially creating pull requests on a Git provider.
Sources: iac-recert-engine/cmd/ice/run.go:13-15
Execution Flow
When ice run is executed, it follows a sequence of steps to initialize and run the engine.
This sequence shows the high-level steps performed by the ice run command.
Sources: iac-recert-engine/cmd/ice/run.go:16-43
run Command Flags
These flags can be used to override settings from the configuration file.
| Flag | Description | Viper Key |
|---|---|---|
--dry-run | Run the process without creating pull requests. | global.dry_run |
--repo-url | Override the repository URL from the config. | repository.url |
Sources: iac-recert-engine/cmd/ice/run.go:53-59
Engine Workflow (engine.Run)
The core logic executed by ice run resides within the Engine.Run method. This workflow consists of several distinct phases.
This diagram details the step-by-step process of the recertification engine.
Sources: iac-recert-engine/internal/engine/engine.go:82-246
Configuration File (.ice.yaml)
The ice CLI is configured using a YAML file. The structure is defined in internal/config/types.go and an example is provided in example.config.yaml.
Top-Level Structure
| Key | Description | Required |
|---|---|---|
version | Configuration schema version. | Yes |
repository | Settings for the repository to scan. | Yes |
auth | Authentication details for the Git provider. | Yes |
global | Global operational settings like dry_run. | No |
patterns | A list of file patterns to scan and their rules. | Yes |
pr_strategy | Defines how files are grouped into pull requests. | No |
assignment | Defines how pull requests are assigned to users/teams. | No |
pr_template | Configuration for the generated pull request content. | No |
audit | Settings for audit logging. | No |
plugins | Configuration for any external plugins. | No |
schedule | Reference for CronJob generation. | No |
Sources: iac-recert-engine/internal/config/types.go:8-21, iac-recert-engine/example.config.yaml:4-75
patterns Section
This is a critical section defining which files to check and how. It is an array of pattern objects.
| Key | Description | Type | Required | Example |
|---|---|---|---|---|
name | A unique name for the pattern. | string | Yes | "terraform-prod" |
description | A human-readable description. | string | No | "Production Terraform" |
paths | An array of glob patterns to include files. | []string | Yes | ["terraform/prod/**/*.tf"] |
exclude | An array of glob patterns to exclude files. | []string | No | ["**/*.test.tf"] |
recertification_days | Number of days before a file is due for recert. | int | Yes | 180 |
enabled | Whether this pattern is active. | bool | No | true |
decorator | A string to prepend to files upon recertification. | string | No | "# Last Recertification: {timestamp}\n" |
Sources: iac-recert-engine/internal/config/types.go:42-51, iac-recert-engine/example.config.yaml:27-42
GitHub Action Usage
The ice CLI is intended for use in CI/CD pipelines, such as GitHub Actions. The repository includes a sample workflow that runs on a schedule.
# Source: iac-recert-engine/github-action.yaml
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 example demonstrates building the ice binary and executing ice run. It relies on a GITHUB_TOKEN secret for authentication and assumes a configuration file is present in the repository.