Skip to main content

GitLab

Configure Connector​

Integrating StackGuardian with GitLab allows for seamless policy enforcement and scanning of structured configurations in your GitLab repositories. To set up the integration, you will need to obtain a Personal Access Token from GitLab. This document provides step-by-step instructions on how to configure the integration.

Create a Personal Access Token​

To integrate with GitLab, you need to create a Personal Access Token with the right permissions. Here's how to do it:

  1. Visit the GitLab platform.
  2. On the left sidebar, click on your avatar.
  3. Choose Edit profile .
  4. Navigate to Access Tokens in the sidebar.
  5. Click on Add New Token.
  6. Provide a meaningful name for the token. Ideally, it should relate to the app or task that will use it.
  7. Optionally, set an expiry date for the token. By default, the expiry is automatically set to 365 days from today.
  8. Choose the "api" Scopes for your token.
  9. Click Create Personal Access Token.
  10. Remember to copy and securely store the token immediately, as it won't be accessible again.

GitLab Token Creation


Project Access Token for GitLab Integration​

Integrating your GitLab project with StackGuardian requires a Project Access Token. This token grants StackGuardian the ability to fetch and scan your project's repositories securely.

Steps to Create a Project Access Token​

  1. Log in to your GitLab account.
  2. Navigate to your project by using the Search feature or directly accessing your project's URL.
  3. Go to Settings > Access Tokens.
  4. Click Add new token.
  5. Enter a token name. Avoid using sensitive information, as it will be visible to all project members.
  6. Set an expiry date for the token, which can be a maximum of 365 days later than the current date.
  7. Choose a role for the token. It must be Reporter or higher.
  8. Under Select scopes, check:
    • read_repository: Allows reading the repository.
    • api: Permits API access that includes various read and write actions.
  9. Click Create project access token.
  10. Save the token securely. Once you navigate away from the page, you cannot retrieve it again.
note

Handle the Project Access Token with care as it grants access to your GitLab project. Project Access Token

Inside StackGuardian Platform​

After obtaining your Access Token, set up a connector in StackGuardian with these steps:

  1. Go to the Orchestrator > Connectors tab.
  2. Select Connect to GitLab.
  3. Fill in the details:
    • Connector Name: Enter a descriptive name, like MyCompanyGitLabConnector.
    • GitLab Username: Your GitLab username, e.g., johndoe123.
    • Access Token: Paste your previously generated Access Token here.
    • GitLab HTTP URL: The web address for GitLab access, typically https://gitlab.com for GitLab's cloud service or a custom domain for self-hosted instances.
    • GitLab API URL: The endpoint for API calls, generally https://gitlab.com/api/v4 for GitLab's cloud-hosted users.
  4. Click Create to finalize the connector setup.

Successful GitLab Connector

GitLab Triggers​

GitLab triggers enable automation within your workflows, such as initiating builds on commits or deploying when a tag is created.

Trigger Settings​

To configure GitLab triggers in Orchestrator, follow these steps:

  1. Go to Workflow Groups and select the desired Workflow.
  2. Within the workflow, navigate to Settings > Source and Parameters > Git Repository.
  3. Click on the Advanced Options dropdown to expand it.
  4. Access the trigger settings by selecting the Configure GitLab Triggers (Preview) option.

Trigger Options​

Adjust the following triggers to automate gitlab workflows efficiently:

Run Workflow on:​

  • All merge requests in the repository - Initiates a workflow for each new merge request.
  • A merge request to the tracked branch - Executes a workflow when a merge request targets the tracked branch.
  • A push to the tracked branch - Triggers a workflow for pushes to the tracked branch.
  • Tag creation - Starts a workflow upon the creation of a new tag.

With options to:​

  • Run Terraform plan only - Executes a Terraform plan without applying changes.
  • Require Terraform plan approval before apply - Terraform plan needs approval before execution.

After Execution (Post):​

  • Commit status back to the GitLab pipeline - Updates the GitLab pipeline with the commit status.
  • Summary as a comment to the merge request - Posts a summary comment on the merge request.

Target Branch Configuration:​

  • Specify the target branch - Set the default branch for triggers; available when "A push made to the tracked branch" is selected.

📁 File Filters with Shell Pattern Matching​

🔍 Overview​

File filters allow you to trigger actions only when specific files or directories are changed. This is especially useful in CI/CD pipelines to avoid unnecessary builds or deployments when unrelated files are updated.

Shell pattern matching (also known as glob patterns) is used to specify which files or folders should trigger a workflow run.

🔧 Enabling File Filters​

  • ✅ Enable the Enable file filters checkbox.
  • ➕ Add one or more file trigger patterns using shell pattern syntax.

📄 Shell Pattern Syntax​

PatternMeaning
*Matches any string within the module
?Matches any single character
[seq]Matches any character in the sequence
[!seq]Matches any character not in the sequence

✅ Trigger Examples for Terraform Projects​

Assume you are working on this structure:

terraform/
├── main.tf
├── variables.tf
├── module1/
│   ├── main.tf
│   └── outputs.tf
├── module2/
│   └── main.tf
└── README.md

Example 1: Match Any File in module1​

Trigger pattern:

["module1/*"]

Matches:

  • module1/main.tf
  • module1/outputs.tf

Does NOT match:

  • module2/main.tf
  • main.tf

Example 2: Match All .tf Files​

Trigger pattern:

["*.tf"]

Matches:

  • main.tf
  • variables.tf
  • module1/main.tf
  • module1/outputs.tf
  • module2/main.tf

Example 3: Match Files with Specific Prefix or Extension​

Trigger pattern:

["module2/m??n.tf"]

Matches:

  • module2/main.tf

🚧 Limitations​

  • Patterns are matched against the entire path (e.g., module1/main.tf), so relative pathing matters.

Review all settings carefully and click Save to apply your configurations.