Provider Overview

Relevant source files

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

• iac-recert-engine/internal/provider/provider.go
• iac-recert-engine/internal/provider/github.go
• iac-recert-engine/internal/provider/azure.go
• iac-recert-engine/internal/provider/gitlab.go
• iac-recert-engine/internal/engine/engine.go
• iac-recert-engine/internal/config/types.go
• iac-recert-engine/example.config.yaml

The Provider layer is a fundamental component of the IAC Recertification Engine, serving as an abstraction layer for interacting with various Git hosting platforms. Its primary purpose is to decouple the core engine logic from the specific APIs of services like GitHub, Azure DevOps, and GitLab. This is achieved through the GitProvider interface, which defines a standard set of operations for repository interaction, such as fetching file history, creating branches, and managing pull requests.

The engine initializes a specific provider implementation at startup based on the user's configuration. This design allows the engine to remain agnostic to the underlying Git service, making it extensible to support new providers in the future without altering the main recertification workflow. All interactions between the Engine and the remote repository are channeled through the active GitProvider instance.

Sources: iac-recert-engine/internal/provider/provider.go:1-53, iac-recert-engine/internal/engine/engine.go:39-45

Architecture and Initialization

The provider architecture is centered around the GitProvider interface and a factory function, NewProvider, that instantiates the correct concrete provider based on the application's configuration.

Sources: iac-recert-engine/internal/provider/provider.go:44-53, iac-recert-engine/internal/engine/engine.go:39-45

Provider Factory

The NewProvider function acts as a factory. It takes the repository and authentication configurations, inspects the provider field (e.g., "github", "azure", "gitlab"), and returns the corresponding provider implementation. This is the single entry point for creating a provider instance.

The diagram below shows the initialization flow from the Engine to a specific provider.

Configuration

Provider selection is driven by the repository and auth sections of the configuration file. The provider field in both sections must specify one of the supported types.

# example.config.yaml
repository:
  # URL of the repository to scan. Supports GitHub, Azure DevOps, and GitLab.
  url: "https://github.com/baldator/iac-recert-engine%22
  # Provider type: github, azure, or gitlab
  provider: "github"

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

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

Class Diagram

The following diagram illustrates the relationship between the GitProvider interface and its concrete implementations.

GitProvider Interface

The GitProvider interface defines the contract for all interactions with a Git repository. Any struct that implements these methods can function as a provider for the engine.

Method	Description
GetRepository	Fetches metadata about the repository.
GetLastModificationDate	Retrieves the timestamp and commit details of the last modification for a given file path.
BranchExists	Checks if a branch with the given name exists.
CreateBranch	Creates a new branch from a base reference.
CreateCommit	Creates a new commit on a specified branch with a set of file changes.
PullRequestExists	Checks if an open pull request already exists for a given head and base branch.
CreatePullRequest	Creates a new pull request.
UpdatePullRequest	Updates an existing pull request's title, description, or state.
ClosePullRequest	Closes an existing pull request.
AssignPullRequest	Assigns users to a pull request.
RequestReviewers	Requests reviews from users for a pull request.
AddLabels	Adds labels to a pull request.
AddComment	Adds a comment to a pull request.

Sources: iac-recert-engine/internal/provider/provider.go:12-32

Provider Implementations

The engine currently includes implementations for GitHub, Azure DevOps, and GitLab.

GitHub (github)

The GitHubProvider is the most complete implementation. It uses the go-github client library to interact with the GitHub API.

• Initialization: NewGitHubProvider parses the owner and repo from the repository URL and initializes the client using a token from the configured environment variable.
• URL Format: `https://github.com/%7Bowner%7D/%7Brepo%7D%60
• Functionality: Implements all methods of the GitProvider interface.

Sources: iac-recert-engine/internal/provider/github.go:26-53

Azure DevOps (azure)

The AzureDevOpsProvider implementation interacts with the Azure DevOps REST API.

• Initialization: NewAzureDevOpsProvider parses the organization, project, and repo from the URL. It supports both dev.azure.com and visualstudio.com URL formats.
• URL Formats: https://dev.azure.com/{org}/{project}/_git/{repo} or https://{org}.visualstudio.com/{project}/_git/{repo}
• Functionality: This provider is partially implemented. Key functions like CreateBranch, CreateCommit, and PullRequestExists are currently stubs that return a "not implemented" error.

Sources: iac-recert-engine/internal/provider/azure.go:30-66, iac-recert-engine/internal/provider/azure.go:119-140

GitLab (gitlab)

The GitLabProvider uses the gitlab.com/gitlab-org/api/client-go library.

• Initialization: NewGitLabProvider parses the project path from the URL and uses it to fetch the numeric project ID required for most API calls.
• URL Format: https://gitlab.com/{group}/{project}.git
• Functionality: This provider is partially implemented. CreateCommit is not implemented. Methods for assigning PRs and requesting reviewers are also noted as not fully implemented or unsupported due to API differences.

Sources: iac-recert-engine/internal/provider/gitlab.go:25-50, iac-recert-engine/internal/provider/gitlab.go:116-118

Feature Implementation Status

Feature	GitHub	Azure DevOps	GitLab
Get Repository Info	✅	✅	✅
Get Last Modification	✅	✅	✅
Branch Exists	✅	❌	✅
Create Branch	✅	❌	✅
Create Commit	✅	❌	❌
PR Exists	✅	❌	✅
Create PR	✅	✅	✅
Update/Close PR	✅	❌	✅
Assign PR	✅	❌	⚠️
Request Reviewers	✅	❌	❌
Add Labels	✅	❌	✅
Add Comment	✅	❌	✅

(✅: Implemented, ❌: Not Implemented, ⚠️: Partially Implemented/Limited)
Sources: iac-recert-engine/internal/provider/github.go, iac-recert-engine/internal/provider/azure.go, iac-recert-engine/internal/provider/gitlab.go

Common Workflow: Creating a Pull Request

The following diagram shows how the Engine uses the GitProvider interface to create a pull request, abstracting away the details of the specific provider.

This flow demonstrates the engine's interaction with the provider to check for existing branches/PRs and then create the necessary Git objects. The engine does not need to know which specific Git platform it is communicating with.

Sources: iac-recert-engine/internal/engine/engine.go:203-255, iac-recert-engine/internal/provider/provider.go:12-32