Deploying with GitHub Actions

Relevant source files

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

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

The iac-recert-engine, also known as ice, is designed to be executed within a CI/CD pipeline to automate the recertification of Infrastructure as Code (IaC) files. The primary deployment method is via a scheduled GitHub Action. This workflow builds and runs the ice command-line tool, which scans the repository, checks file modification dates against configured policies, and creates Pull Requests for files that require recertification.

The entire process is driven by a central configuration file within the repository. The GitHub Action serves as the trigger and execution environment, passing necessary authentication tokens to the engine, which then carries out the scan and remediation workflow based on the rules defined in the configuration.

Sources: iac-recert-engine/github-action.yaml, iac-recert-engine/cmd/ice/root.go:12-15

GitHub Action Workflow

The core of the deployment is the github-action.yaml file, which defines the CI job that runs the recertification engine.

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

Triggers

The workflow is configured to run on a predefined schedule or can be triggered manually.

• Scheduled Trigger: Runs weekly on Sunday at 2 AM, as defined by the cron expression 0 2 * * 0.
• Manual Trigger: Can be started at any time through the GitHub UI via workflow_dispatch.

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

Job: recertify

A single job named recertify runs on an ubuntu-latest runner and performs the necessary steps to execute the engine.

The following diagram illustrates the steps within the recertify job.

The steps are:

1. Checkout Code: The actions/checkout@v4 action checks out the repository's source code.
2. Set up Go: The actions/setup-go@v4 action configures the correct Go environment (version 1.21).
3. Build ICE: The command go build -o ice ./cmd/ice compiles the application from the cmd/ice package and creates an executable binary named ice.
4. Run Recertification: The command ./ice run executes the recertification engine.

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

Authentication

The Run Recertification step requires a GitHub token to interact with the repository (e.g., to create branches and pull requests). This is supplied via an environment variable.

- name: Run Recertification
  run: ./ice run
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The GITHUB_TOKEN environment variable is set using the automatically-provisioned secret from GitHub Actions. The engine's configuration file must reference this environment variable name to authenticate with the GitHub provider.

Sources: iac-recert-engine/github-action.yaml:22-24, iac-recert-engine/example.config.yaml:15-17, iac-recert-engine/internal/provider/github.go:23-26

Command Line Execution

The GitHub Action executes the ice run command. The ice binary is built from the cmd/ice package, which uses the cobra library for command-line parsing.

Sources: iac-recert-engine/cmd/ice/run.go, iac-recert-engine/cmd/ice/root.go

Configuration Loading

Upon execution, the ice application loads its configuration using the viper library. It searches for a configuration file in the following order:

1. A path specified by the --config flag.
2. A path specified by the ICE_CONFIG_PATH environment variable.
3. A file named .ice.yaml in the user's home directory.

The GitHub Action assumes a configuration file is present in the repository root or another specified location.

Sources: iac-recert-engine/cmd/ice/root.go:42-60

Command Flags

The run command supports flags that can override settings from the configuration file.

Flag	Viper Key	Description
--dry-run	global.dry_run	If set, the engine will perform a read-only scan and will not create any branches or pull requests.
--repo-url	repository.url	Overrides the repository URL specified in the configuration file.

Sources: iac-recert-engine/cmd/ice/run.go:44-47

Core Engine Execution Flow

When ice run is executed, it initializes and runs the main engine, which performs the recertification workflow in several distinct phases.

This sequence diagram shows the interaction between the run command and the core engine components.

The execution flow is as follows:

1. Scan: The Scanner finds all files in the repository that match the configured patterns.
2. Enrich: The HistoryAnalyzer uses the git Provider to fetch the last modification date and commit details for each file.
3. Check: The Checker evaluates each file against its pattern's recertification_days threshold to determine if it needs recertification.
4. Group: The Strategy component groups files that need recertification into batches based on the configured pr_strategy (e.g., per_pattern, per_file).
5. Process Groups: For each group, the engine:
   • Resolves assignees for the pull request.
   • Generates the PR title and description.
   • If not in dry_run mode, it uses the Provider to create a new branch, commit file changes (adding a recertification decorator), and open a pull request.

Sources: iac-recert-engine/internal/engine/engine.go:70-143, iac-recert-engine/internal/scan/recert_checker.go:21-112, iac-recert-engine/internal/strategy/strategy_test.go

Configuration for GitHub Actions

A valid configuration file (e.g., config.yaml or example.config.yaml) is essential for the GitHub Action to run correctly. The following sections are particularly relevant for this deployment method.

Repository and Auth Configuration

The repository and auth sections must be configured for the github provider. The token_env must match the environment variable set in the GitHub Action workflow.

Section	Key	Example Value	Description
repository	url	`https://github.com/example/infrastructure%60	The URL of the repository to scan.
repository	provider	github	Must be github for this workflow.
auth	provider	github	Must be github for this workflow.
auth	token_env	GITHUB_TOKEN	The name of the environment variable containing the auth token.

Sources: iac-recert-engine/config.yaml:3-10, iac-recert-engine/internal/config/types.go:15-23

Global Configuration

The global configuration block contains settings that affect the overall execution, such as dry_run mode.

Key	Type	Default	Description
dry_run	bool	false	If true, no pull requests will be created. Can be overridden by the --dry-run flag.
verbose_logging	bool	false	Enables more detailed development-style logging.
default_base_branch	string	main	The base branch to target for new pull requests.

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

Summary

Deploying the iac-recert-engine via GitHub Actions provides a fully automated, "set-and-forget" solution for enforcing IaC recertification policies. The workflow handles the building and execution of the ice binary, while the engine's logic is controlled by a version-controlled configuration file within the repository itself. This combination of a scheduled CI trigger and a declarative configuration file creates a powerful and maintainable system for managing code lifecycle and compliance.