The Quality Clouds GitLab CI/CD integration enables automated code quality analysis directly within your GitLab pipeline. Once configured, every push or Merge Request can trigger a Quality Clouds scan, allowing your team to identify quality issues early and enforce Quality Gates before code is merged — without storing a static API key in your project.
This article explains how to configure the GitLab CI/CD job for Salesforce repositories using JWT Bearer Flow authentication.
Prerequisites
Before configuring the integration, ensure you have:
- A Quality Clouds account.
- A GitLab project connected to your Quality Clouds organization
- A GitLab project with CI/CD pipelines enabled.
- Permission to create or modify .gitlab-ci.yml and CI/CD Variables.
If your GitLab project isn’t yet connected to a Quality Clouds instance, contact your Quality Clouds administrator or refer to Setting Up Salesforce Git Repositories.
Create the GitLab Pipeline #
Create a file named .gitlab-ci.yml in the root of your GitLab project, with the following content as an example:
stages:
- prepare
- scan
include:
- component: gitlab.com/qualityclouds/build-check/fb-scan@1.0.0
inputs:
stage: scan
token: "$ACCESS_TOKEN"
mode: "local"
zip_path: "modified_files.zip"
all_issues: "true"
codequality: "true"
prepare_oidc_and_zip:
stage: prepare
image: alpine:latest
id_tokens:
GITLAB_OIDC_TOKEN:
aud: "https://account.qualityclouds.com"
before_script:
- apk add --no-cache git zip curl jq
script:
- |
if [ -z "$GITLAB_OIDC_TOKEN" ]; then
echo "Error: GITLAB_OIDC_TOKEN did not generate."
exit 1
fi
KEYCLOAK_RESPONSE="$(curl -sS -X POST "https://account.qualityclouds.com/realms/qualityclouds/protocol/openid-connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
-d "client_id=gitlab-ci" \
-d "subject_token=$GITLAB_OIDC_TOKEN" \
-d "subject_token_type=urn:ietf:params:oauth:token-type:jwt")"
ACCESS_TOKEN="$(echo "$KEYCLOAK_RESPONSE" | jq -r '.access_token')"
if [ "$ACCESS_TOKEN" = "null" ] || [ -z "$ACCESS_TOKEN" ]; then
echo "Error obtaining Keycloak token"
echo "$KEYCLOAK_RESPONSE"
exit 1
fi
echo "ACCESS_TOKEN=$ACCESS_TOKEN" > access.env
git remote set-branches origin '*'
if [ -n "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" ]; then
git fetch origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" || true
TARGET_BRANCH="origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
else
git fetch origin "$CI_DEFAULT_BRANCH" || true
TARGET_BRANCH="origin/$CI_DEFAULT_BRANCH"
fi
git diff "$TARGET_BRANCH" --name-only > modified_files.txt || true
if [ ! -s modified_files.txt ]; then
echo "No Salesforce metadata changed; exiting."
exit 0
fi
rm -f modified_files.zip
zip -@ modified_files.zip < modified_files.txt
artifacts:
paths:
- modified_files.zip
reports:
dotenv: access.env
expire_in: 1 week
rules:
- if: $CI_MERGE_REQUEST_IID
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
qualityclouds-scan:
needs:
- job: prepare_oidc_and_zip
artifacts: true
artifacts:
when: always
expose_as: "Quality Clouds Code Quality report"
reports:
codequality: qc-codequality-report.json
paths:
- qc-codequality-report.json
expire_in: 1 week
rules:
- if: $CI_MERGE_REQUEST_IID
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
That’s it — no CI/CD variable to create, no API key to store. The next Merge Request you open will trigger the scan automatically.
The only requirement is that the user running the pipeline must be a Quality Clouds User
How the GitLab Pipeline works #
Once the workflow has been configured:
- A developer pushes code or creates a Merge Request.
- GitLab executes the Quality Clouds Component.
- Quality Clouds analyzes the proposed changes.
- The scan results are returned to GitLab.
- If Code Quality mode is enabled, findings are displayed directly in the Code Quality Report.
- If Quality Gates are configured, the Merge Request status reflects whether the configured quality requirements have been met.
No additional manual steps are required during normal development.
Inputs reference #
| Input | Default | Description |
|---|---|---|
stage |
test |
Pipeline stage where the scan job runs |
token |
none | Access token used to authenticate (here, $ACCESS_TOKEN from the OIDC exchange) |
mode |
cloud |
local here, since we scan a ZIP of changed files |
cloud |
2 |
2/salesforce |
version |
latest |
Scanner image tag |
all_issues |
"" |
Include blockers and non-blockers |
zip_path |
"" |
Required in local mode |
codequality |
True |
Enables GitLab’s native Code Quality report |
allow_completion_on_fails |
false |
Determines whether the merge request should be marked as failed when the Quality Gate does not pass. If set to False: The pipeline will fail if Quality Gate do not pass |
Code Quality Feedback #
When codequality is enabled, Quality Clouds publishes scan results directly in the code quality tab
Depending on the configuration, developers can review:
- Detected issues
- Severity
- File and line number
- Violated best practices
- Documentation links
- Blocker and non-blocker findings
This allows developers to resolve issues without leaving GitHub.
Quality Gate Status #
If your organization uses Quality Gates, the GitLab component validates every scan against the configured quality requirements.
Possible outcomes include:
Passed
The scan completed successfully and all configured Quality Gate conditions were satisfied.
If no Quality Gates have been configured, the workflow also completes successfully.
Failed
The scan completed successfully, but one or more blocking Quality Gate conditions were not met.
If allow_completion_on_fails is disabled, the pipeline is marked as failed until the blocking issues have been resolved.
Best Practices #
To get the most value from the GitLab integration, we recommend:
- Enable codequality parameter (
codequality: true). - Display all findings during development (
allIssues: true). - Enable Quality Gates to prevent critical issues from being merged.
- Run scans on every Merge Request to provide continuous feedback.
Related Integrations #
Quality Clouds can also be integrated into other CI/CD platforms.
Supported options include:
- Copado Integration
- Github Integration
- Flosum Integration
- Visual Studio Code Integration
- DevOps Center Integration
- Code Builder Extension
Refer to the corresponding integration guides for platform-specific configuration instructions.
Next Steps #
After configuring the GitLab component:
- Create a merge Request to verify that the workflow executes successfully.
- Review the scan results directly within the code quality tab
- Configure Quality Gates to enforce your organization’s quality standards.
- Learn more about the GitLab development workflow in GitLab Integration Overview.
