GitLab Integration
Relevant source files
The following files were used as context for generating this wiki page:The GitLab integration provides the iac-recert-engine with the capability to interact with GitLab repositories. It implements the GitProvider interface, acting as the bridge between the core engine logic and the GitLab API. Its primary responsibilities include fetching repository and file history, checking for the existence of branches and merge requests, and creating new branches and merge requests to facilitate the recertification process.
This provider is one of several available, alongside GitHub and Azure DevOps, and is selected via the main configuration file. It uses the official GitLab Go client (gitlab.com/gitlab-org/api/client-go) for all API communications.
Sources: internal/provider/gitlab.go, internal/provider/provider.go:29-35, internal/engine/engine.go:39-42
Configuration
To use the GitLab provider, you must specify gitlab in the repository and auth sections of your config.yaml file. The engine requires a personal access token with appropriate permissions to interact with the target repository.
Sources: internal/config/types.go:19, internal/config/types.go:24
Configuration Parameters
| Section | Key | Description | Required |
|---|---|---|---|
repository | url | The full URL of the GitLab repository (e.g., https://gitlab.com/group/project.git). | Yes |
repository | provider | Must be set to gitlab. | Yes |
auth | provider | Must be set to gitlab. | Yes |
auth | token_env | The name of the environment variable containing the GitLab personal access token. | Yes |
Sources: internal/config/types.go:18-26, example.config.yaml:7-14
Example Configuration
version: "1.0"
repository:
url: "https://gitlab.com/my-group/my-infra-project.git"
provider: "gitlab"
auth:
provider: "gitlab"
token_env: "GITLAB_TOKEN"
# ... other configurations
Sources: example.config.yaml, internal/provider/gitlab.go:24-27
Architecture and Initialization
The integration is encapsulated within the GitLabProvider struct, which holds the GitLab API client, the numeric project ID, and a logger instance.
type GitLabProvider struct {
client *gitlab.Client
project int64 // Project ID
logger *zap.Logger
}
Sources: internal/provider/gitlab.go:20-24
The initialization process is handled by the NewGitLabProvider function. It is called by the main engine when the configuration specifies gitlab as the provider.
The following diagram illustrates the initialization flow:
This diagram shows the steps taken by NewGitLabProvider to set up the connection to a GitLab project.
Sources: internal/provider/gitlab.go:26-50
Core Operations
The GitLabProvider implements the methods defined in the GitProvider interface. Some operations are fully supported, while others are not yet implemented.
*Sources: internal/provider/provider.go:13-35, internal/provider/gitlab.go *
Implemented Operations
| Method | Description |
|---|---|
GetRepository | Fetches basic repository details like name, owner, URL, and default branch. |
GetLastModificationDate | Retrieves the timestamp and commit details of the last modification for a given file path. |
BranchExists | Checks if a branch with the specified name exists in the repository. |
CreateBranch | Creates a new branch from a specified base reference (e.g., main). |
PullRequestExists | Checks if an open merge request already exists for a given source and target branch pair. |
CreatePullRequest | Creates a new merge request with a title, description, source branch, and target branch. |
UpdatePullRequest | Updates an existing merge request's title, description, or state (e.g., to close it). |
ClosePullRequest | A wrapper around UpdatePullRequest that sets the merge request state to close. |
AddLabels | Adds a list of labels to an existing merge request. |
AddComment | Adds a new note (comment) to a merge request. |
Sources: internal/provider/gitlab.go:53-104, internal/provider/gitlab.go:121-218
Unimplemented or Limited Operations
The following operations are currently not implemented and will return an error if called:
| Method | Status |
|---|---|
CreateCommit | Not Implemented. The engine's ability to commit file changes (e.g., decorators) will fail. |
AssignPullRequest | Not Implemented. The provider cannot assign users to a merge request. A note indicates that resolving usernames to user IDs is required. |
RequestReviewers | Not Implemented. The provider cannot request reviewers for a merge request. |
Sources: internal/provider/gitlab.go:106-108, internal/provider/gitlab.go:189-196, internal/provider/gitlab.go:198-201
Data Flow Examples
Fetching File History
The HistoryAnalyzer component of the engine relies on the provider's GetLastModificationDate method to enrich file information.
The sequence diagram below shows this interaction:
This diagram illustrates how the last commit for a specific file is retrieved from the GitLab API.
Sources: internal/scan/git_history.go:32-46, internal/provider/gitlab.go:76-98
Creating a Merge Request
After identifying files that need recertification, the engine processes them in groups and calls the provider to create a merge request.
This diagram shows the process of creating a merge request via the GitLab provider.
Sources: internal/engine/engine.go:283-287, internal/provider/gitlab.go:139-156, internal/types/types.go:54-62
Summary
The GitLab integration enables the core functionality of the iac-recert-engine for projects hosted on GitLab. It successfully handles discovery operations like fetching file history and state-changing operations like creating branches and merge requests. However, key features such as committing file changes (CreateCommit) and assigning reviewers (AssignPullRequest, RequestReviewers) are not implemented. Users should be aware of these limitations when using the engine with GitLab repositories, as it may impact parts of the automated workflow, particularly the application of recertification decorators to files.
Sources: internal/provider/gitlab.go