GitHub Integration

Relevant source files

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

• iac-recert-engine/internal/provider/github.go
• iac-recert-engine/internal/provider/provider.go
• iac-recert-engine/internal/engine/engine.go
• iac-recert-engine/internal/config/types.go
• iac-recert-engine/example.config.yaml
• iac-recert-engine/internal/scan/git_history.go

The GitHub integration for the IAC Recertification Engine is a provider that implements the GitProvider interface, enabling the engine to interact directly with GitHub repositories. Its primary purpose is to perform Git-related operations such as fetching file modification history, creating branches, committing changes, and managing pull requests. This allows the engine to automate the entire recertification workflow, from identifying stale files to creating review assignments via pull requests.

The provider is selected and configured through the main config.yaml file. It uses the go-github library to communicate with the GitHub API, authenticating via a Personal Access Token (PAT) supplied through an environment variable. This integration is a core component that bridges the engine's abstract logic with the concrete implementation of a specific Git hosting service.

Sources: internal/provider/github.go, internal/provider/provider.go:13-33, internal/engine/engine.go:37-41

Configuration

To use the GitHub provider, you must specify github in the repository and auth sections of the configuration file.

Sources: example.config.yaml:7-14, internal/config/types.go:16-24

Example Configuration

# iac-recert-engine/example.config.yaml

repository:
  # URL of the repository to scan.
  url: "https://github.com/baldator/iac-recert-engine%22
  # Provider type must be 'github'
  provider: "github"

auth:
  provider: "github"
  # Environment variable containing the personal access token (PAT)
  token_env: "GITHUB_TOKEN"

Sources: example.config.yaml:7-14

Configuration Parameters

The following table details the configuration options for the GitHub provider.

Section	Key	Type	Description	Required
repository	url	string	The full URL of the GitHub repository (e.g., `https://github.com/owner/repo%60).	Yes
repository	provider	string	Must be set to github.	Yes
auth	provider	string	Must be set to github.	Yes
auth	token_env	string	The name of the environment variable that holds the GitHub PAT.	Yes

Sources: internal/config/types.go:16-24, example.config.yaml:7-14

Architecture and Initialization

The GitHubProvider is initialized by the NewProvider factory function, which selects the correct provider based on the configuration. The NewGitHubProvider function is responsible for setting up the connection to GitHub.

The initialization process involves:

1. Reading the GitHub token from the environment variable specified by auth.token_env.
2. Creating an oauth2 authenticated HTTP client.
3. Initializing the go-github client with the authenticated client.
4. Parsing the repository owner and name from the repository.url.
5. Returning a GitHubProvider struct containing the client and repository details.

Sources: internal/provider/provider.go:43-45, internal/provider/github.go:21-50

This diagram illustrates the initialization sequence.

The GitHubProvider struct holds the state required for all subsequent API interactions.

// iac-recert-engine/internal/provider/github.go:15-20
type GitHubProvider struct {
	client *github.Client
	owner  string
	repo   string
	logger *zap.Logger
}

Sources: internal/provider/github.go:15-20

Core Functionality

The GitHubProvider implements the GitProvider interface, offering methods to interact with repositories, manage branches, commits, and pull requests.

Sources: internal/provider/provider.go:13-33

Data Fetching

GetLastModificationDate

This function is critical for determining if a file needs recertification. It retrieves the timestamp and details of the last commit that modified a given file path. It uses the GitHub Repositories API to list commits, filtered by the file path (Path) and limited to the single most recent one (PerPage: 1).

Sources: internal/provider/github.go:73-98

The following diagram shows how the HistoryAnalyzer uses the provider to enrich file information.

Branch and Commit Management

The provider contains a full suite of methods to create a new branch, commit file changes, and open a pull request.

CreateBranch

Creates a new branch in the repository. It first fetches the SHA of the baseRef (e.g., main) and then creates a new ref (the new branch) pointing to that same commit SHA.

Sources: internal/provider/github.go:111-125

CreateCommit

This method performs a multi-step process to commit file changes to a branch without a local clone.

1. Get Parent Commit: Fetches the latest commit SHA of the target branch.
2. Create Blobs: For each file change, it creates a new blob in the repository via the API and collects the returned blob SHAs.
3. Create Tree: It creates a new Git tree object containing the new blobs, based on the parent commit's tree.
4. Create Commit: It creates a new commit object pointing to the new tree and the parent commit.
5. Update Branch Reference: It updates the head of the branch to point to the new commit's SHA.

Sources: internal/provider/github.go:127-170

This flowchart visualizes the commit creation logic.

Pull Request Management

PullRequestExists

Before creating a new pull request, the engine checks if one already exists for the given head and base branches. This prevents creating duplicate PRs on subsequent runs. It lists open PRs with a Head filter.

Sources: internal/provider/github.go:172-187

CreatePullRequest

This function creates a new pull request. After the PR is created, it proceeds to add any configured assignees, reviewers, and labels in separate API calls.

Sources: internal/provider/github.go:189-228

The provider also includes methods for updating, closing, and commenting on pull requests:

• UpdatePullRequest
• ClosePullRequest
• AssignPullRequest
• RequestReviewers
• AddLabels
• AddComment

Sources: internal/provider/github.go:230-286

Engine Integration

The main engine orchestrates the entire recertification process, relying on the GitHubProvider at key stages.

This diagram shows the high-level interaction between the engine and the provider during a run.

Summary

The GitHub integration is a complete implementation of the GitProvider interface, providing all the necessary functionality for the IAC Recertification Engine to operate on GitHub repositories. It handles authentication, data retrieval, and repository modifications (branches, commits, PRs) through the official GitHub API. Its behavior is configured via a simple YAML file, making it easy to point the engine at any GitHub repository and automate the code recertification lifecycle.