Configuration File (config.yaml)

Relevant source files

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

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

The config.yaml file is the central point of configuration for the Infrastructure as Code Recertification Engine (ICE). It defines all operational parameters, including the target repository, authentication credentials, scanning rules, and how pull requests for recertification should be generated and assigned. The application loads this configuration at startup, validates its structure and values, and uses it to initialize and drive the main recertification engine.

The configuration is parsed using the Viper library, which allows for flexible loading from a file, environment variables, or command-line flags. Upon loading, the configuration is unmarshalled into the config.Config struct and validated to ensure all required fields are present and have correct values.

Sources: cmd/ice/run.go:16-24, internal/config/types.go:8-16, cmd/ice/root.go:43-61

Configuration Loading

The engine loads its configuration using a prioritized approach managed by Cobra and Viper. This allows for overriding settings from multiple sources.

The loading sequence is as follows:

1. Command-line Flag: A --config flag can specify the exact path to the configuration file.
2. Environment Variable: If the flag is not used, the ICE_CONFIG_PATH environment variable is checked.
3. Default Path: If neither of the above is set, the engine searches for a file named .ice.yaml in the user's home directory.
4. Environment Variable Overrides: Viper's AutomaticEnv() allows any configuration key to be overridden by an environment variable (e.g., repository.url can be set by an env var).
5. Flag Overrides: Specific flags like --dry-run and --repo-url can override values from the config file.

Sources: cmd/ice/root.go:43-61, cmd/ice/run.go:44-47

This diagram illustrates the configuration loading and override logic.

Top-Level Structure

The config.yaml is mapped to the Config struct in Go. The diagram below shows the main components of the configuration.

version

A required string specifying the configuration file version.

Sources: internal/config/types.go:9

repository

Defines the target Git repository to be scanned.

Key	Type	Description	Validation
url	string	The full URL of the repository.	required, url
provider	string	The Git provider.	required, one of github, azure, gitlab

Sources: internal/config/types.go:18-21

repository:
  url: "https://github.com/baldator/iac-recert-engine%22
  provider: "github"

Sources: example.config.yaml:7-10

auth

Specifies the authentication method for the Git provider.

Key	Type	Description	Validation
provider	string	The authentication provider. Must match repository.provider.	required, one of github, azure, gitlab
token_env	string	The name of the environment variable containing the Personal Access Token (PAT).	required

Sources: internal/config/types.go:23-26

auth:
  provider: "github"
  token_env: "GITHUB_TOKEN"

Sources: example.config.yaml:13-16

global

Global settings that affect the engine's overall behavior.

Key	Type	Description	Default
dry_run	bool	If true, the engine runs in read-only mode and does not create PRs.	false
verbose_logging	bool	Enables detailed debug logging.	false
max_concurrent_prs	int	Maximum number of concurrent PRs to create.	5
default_base_branch	string	The base branch to target for new PRs (e.g., "main").	"main"

Sources: internal/config/types.go:28-33, example.config.yaml:21-23

patterns

A list of rules for discovering files that require recertification. This is a core part of the configuration, driving the scanning process.

Key	Type	Description	Validation
name	string	A unique name for the pattern.	required
description	string	A human-readable description.	Optional
paths	[]string	A list of glob patterns to include files.	required
exclude	[]string	A list of glob patterns to exclude files from the paths matches.	Optional
recertification_days	int	The number of days after which a file is considered due for recertification.	required, min=1
enabled	bool	If true, this pattern will be processed.	true
decorator	string	A string to prepend to a file's content upon recertification. Can include {timestamp}.	Optional

Sources: internal/config/types.go:35-43

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: example.config.yaml:26-37

pr_strategy

Defines how multiple files requiring recertification are grouped into pull requests.

Key	Type	Description	Validation
type	string	The grouping strategy.	required, one of per_file, per_pattern, per_committer, single_pr, plugin
max_files_per_pr	int	An optional limit on the number of files per PR.	Optional
plugin_name	string	The name of the plugin to use if type is plugin.	Optional

Sources: internal/config/types.go:45-49

assignment

Controls how assignees and reviewers are added to the generated pull requests.

Key	Type	Description	Validation
strategy	string	The assignment strategy.	required, one of static, last_committer, plugin, composite
rules	[]AssignmentRule	A list of rules used when strategy is composite.	Optional
fallback_assignees	[]string	A default list of assignees if a strategy fails or no rule matches.	Optional

Sources: internal/config/types.go:51-55

AssignmentRule

Key	Type	Description	Validation
pattern	string	A glob pattern to match file paths.	required
strategy	string	The strategy to use for this rule.	required, one of static, last_committer, plugin
plugin	string	The plugin to use if strategy is plugin.	Optional
fallback_assignees	[]string	Assignees for this specific rule.	Optional

Sources: internal/config/types.go:57-62

assignment:
  strategy: "composite"
  rules:
    - pattern: "terraform/prod/**"
      strategy: "static"
      fallback_assignees: ["infra-team"]
    - pattern: "k8s/**"
      strategy: "last_committer"
  fallback_assignees:
    - "devops-team"

Sources: example.config.yaml:57-67

pr_template

Customizes the content of the generated pull requests.

Key	Type	Description	Validation
title	string	The title of the PR. Can use placeholders like {pattern_name}.	required
include_file_list	bool	If true, includes a markdown table of files in the PR body.	Optional
include_checklist	bool	If true, includes a review checklist in the PR body.	Optional
custom_instructions	string	Custom text to be added to the PR body.	Optional

Sources: internal/config/types.go:74-79

plugins

Configuration for any external plugins used by the engine, such as for custom assignment strategies.

Sources: internal/config/types.go:64-70, example.config.yaml:69-75

audit

Configures audit logging for the engine's activities.

Key	Type	Description	Validation
enabled	bool	Enables or disables audit logging.	Optional
storage	string	The storage backend for audit logs.	required, one of file, s3
config	map[string]string	Key-value configuration for the chosen storage backend (e.g., path for file).	Optional

Sources: internal/config/types.go:81-85, example.config.yaml:85-89

schedule

Defines a cron schedule, primarily for reference when generating CI/CD configurations like GitHub Actions.

Sources: internal/config/types.go:72-75, example.config.yaml:77-79, github-action.yaml:4-5

Validation

The application validates the configuration object after it is loaded. The validation uses struct tags to enforce rules such as required fields, minimum values, and allowed enumerations (oneof). If validation fails, the application will exit with an error.

Sources: internal/config/types.go:87-90, cmd/ice/run.go:21-24, internal/config/types_test.go