Lesson 6: Custom Compliance Frameworks#

In Lessons 2–5 you set up security scanners and policies on a single project. Most real-world organizations have to do this across hundreds of projects, prove that each one meets specific standards (SOC 2, ISO 27001, PCI-DSS, NIST 800-53, internal corporate policy), and answer auditor questions with evidence — not screenshots.

GitLab’s compliance frameworks are how you do that. A compliance framework is a named, reusable bundle of:

  • Requirements — the standard’s expectations, written as checks (e.g. “SAST runs on every default-branch pipeline”, “merge requests require code-owner approval”)
  • Controls — the GitLab-native or external checks that satisfy each requirement
  • Linked policies — pipeline execution policies and merge request approval policies that enforce the standard

Once applied to a project, GitLab continuously evaluates each control and produces an adherence report you can hand to an auditor.

This lesson covers:

  1. Why use a compliance framework
  2. Prerequisites
  3. Creating a custom compliance framework
  4. Starting from a compliance framework template
  5. Defining requirements and controls
  6. Linking policies to the framework
  7. Applying the framework to projects
  8. Viewing compliance status and adherence reports
  9. Exporting and reusing a framework as JSON

Why use a compliance framework#

The pattern you set up in Lesson 2 works for one project. As the number of projects grows, three things break:

  • Drift — each project’s .gitlab-ci.yml evolves independently and gets out of sync with the standard
  • Auditability — answering “is every Tier-1 project running SAST on its default branch?” becomes a custom query
  • Onboarding — every new project starts from scratch

A compliance framework solves all three:

  • The framework defines the standard once
  • Policies attached to the framework are enforced on every applied project
  • The compliance center shows adherence at the project, framework, and group level — without writing queries

In short, a compliance framework is security policy + scanner configuration + audit evidence, bundled by name.

Prerequisites#

To complete this lesson you need:

  • A GitLab group containing the Tanuki Shop project (frameworks live at the group level)
  • Owner or Security Manager role on that group (or a custom role with admin_compliance_framework)
  • GitLab Ultimate (compliance frameworks are available on Premium for labeling, but the policy enforcement and adherence reporting used here require Ultimate)

If your imported project is in a personal namespace, create a group now (Groups > New group) and transfer the project (Settings > Advanced > Transfer project). Frameworks cannot be applied to personal-namespace projects.

Creating a custom compliance framework#

We will build a framework called Tanuki AppSec Baseline that codifies the security setup from Lesson 2. You can use this exact pattern for SOC 2, ISO 27001, or an internal standard — only the requirements change.

  1. Navigate to your group’s page

  2. In the left sidebar, click Secure > Compliance center

  3. Open the Frameworks tab

  4. Click New framework

  5. You will see three creation methods. Pick Blank to author from scratch — we use this here to show how the pieces fit together. The other two are Create from template (built-in templates for standards like SOC 2, ISO 27001:2022, and NIST 800-53) and Import framework (upload a JSON file). For real audits, starting from a template is almost always faster — see Starting from a compliance framework template below.

  6. Fill in:

  • Name: Tanuki AppSec Baseline
  • Description: Baseline application security controls required for all Tanuki services — SAST, dependency scanning, secret detection, and maintainer approval for vulnerable code
  • Color: any color you like; the color shows next to the framework label on project pages

  1. Leave Set as default unchecked for now (we will apply it manually). Setting a framework as default automatically applies it to new projects created in the group.

  2. Click Save

The framework now exists. It has no requirements and is not applied to anything yet — that’s next.

Starting from a compliance framework template#

Authoring a framework from Blank is great for learning, but in practice you rarely start from nothing. GitLab ships compliance framework templates — predefined frameworks that come pre-populated with the requirements and controls for a recognized standard, so you can stand one up in a couple of clicks and then tailor it.

GitLab provides around 20 built-in templates, including:

  • SOC 2
  • ISO 27001:2022
  • NIST 800-53 Revision 5, NIST SP 800-218, NIST 800-171 Rev. 3 CMMC
  • FedRAMP High / Moderate / Low
  • CIS CSC v8.1, CSA CCM v4, Cyber Essentials
  • DORA, NIS 2, ISMAP, TISAX, and the IRAP variants

Create a framework from a built-in template#

  1. Navigate to your group’s page

  2. In the left sidebar, select Secure > Compliance center

  3. Open the Frameworks tab

  4. Select New framework

  5. Select Create from template

  6. Browse the templates and select one to preview its requirements and controls

  7. Optionally override the Name, Description, or Color, and decide whether to Set as default

  8. Select Create framework

The new framework arrives fully populated with that standard’s requirements and controls. From here you customize it exactly like the blank one — add, edit, or remove requirements and controls (covered in the next section) so it matches how your organization actually implements the standard.

Import a template from the templates library#

Beyond the built-in set, GitLab maintains a public Compliance Adherence Templates library of ready-to-use frameworks shared as JSON. To use one:

  1. In the templates library project, download the JSON file for the standard you need

  2. In your group, go to Secure > Compliance center and open the Frameworks tab

  3. Select New framework, then Import framework

  4. Select the downloaded JSON file from your local system

The Import framework flow accepts any valid framework JSON — both files from the library and frameworks you export from another group. Imported frameworks must have a unique name within the group. Template-based creation requires GitLab Ultimate (defining requirements and controls is an Ultimate capability) and is generally available in GitLab 19.1 and later.

For the rest of this lesson we’ll continue building out the blank Tanuki AppSec Baseline framework so you see each piece explicitly — but everything that follows applies equally to a framework you created from a template.

Defining requirements and controls#

Each requirement maps to a clause in the standard you are codifying. Each control is a GitLab-native check or an external API call that proves the requirement is met.

We will add three requirements:

  1. Static analysis on every default-branch pipeline
  2. Secret detection on every default-branch pipeline
  3. Maintainer approval for new vulnerabilities

Add the SAST requirement#

  1. From the framework’s edit page, scroll to Requirements and click New requirement

  2. Fill in:

  • Name: SAST is enabled on default branch
  • Description: GitLab SAST (including Advanced SAST) must execute on every default-branch pipeline, and the default branch must be protected.
  1. Click Add a GitLab control and add the following controls (up to five per requirement):
  • SAST is running — checks that a SAST job ran on the most recent default-branch pipeline
  • Default branch is protected — checks that the default branch has push protection enabled
  1. Click Save requirement

Add the Secret Detection requirement#

  1. Click New requirement

  2. Fill in:

  • Name: Secrets are not committed
  • Description: Secret detection scans must run on every default-branch pipeline and Secret Push Protection must be enabled.
  1. Add the following controls:
  • Secret Detection is running
  • Secret Push Protection is enabled
  1. Click Save requirement

Add the vulnerability-approval requirement#

  1. Click New requirement

  2. Fill in:

  • Name: New vulnerabilities require maintainer approval
  • Description: Merge requests that introduce new vulnerabilities must be approved by a maintainer.
  1. Add the following control:
  • Merge request approval policy enforces vulnerability gate
  1. Click Save requirement

The full list of GitLab controls is in the compliance controls reference. When a control you need isn’t there, use an external control — GitLab POSTs to a URL you choose and your service returns the compliance status. This is how teams plug GitLab into ServiceNow, internal GRC tools, or custom evidence pipelines.

Linking policies to the framework#

A requirement that only detects non-compliance is half the answer. The other half is preventing it. Policies linked to a framework are automatically applied to every project the framework is applied to.

  1. From your group’s compliance center, open the Policies tab

  2. Click New policy

  3. Choose Merge request approval policy

  4. Configure the policy the same way you did in Lesson 2 (require_maintainer_approval_for_detected_vulnerabilities), but on the Scope step pick Apply to projects with compliance framework:

  • Compliance framework: Tanuki AppSec Baseline

  1. Save and merge the policy MR

  2. Repeat for the scan execution policy (enforce_iac_scanning_on_all_branches) and the pipeline execution policy (inject_custom_soc2_echo_job) from Lesson 2 — scope each one to the Tanuki AppSec Baseline framework

Now any project that gets the framework also gets the policies. Drop a new project into the framework and it inherits SAST enforcement, IaC scanning, the SOC 2 echo job, and the approval gate — without anyone editing its .gitlab-ci.yml.

This is the leverage point. A framework lets a security team write one set of policies and have them ride along with every project that needs them. No more “we onboarded a new repo last week and nobody enabled SAST.”

Applying the framework to projects#

  1. From the group’s compliance center, open the Projects tab

  2. Find the Tanuki Shop row

  3. Click the framework dropdown and select Tanuki AppSec Baseline

  4. The framework label appears next to the project name. The linked policies start enforcing on the next pipeline.

You can apply up to 20 frameworks to a single project — useful when a project needs to satisfy multiple standards (e.g., SOC 2 and HIPAA).

Viewing compliance status and adherence reports#

Now let’s see the result.

  1. From the group’s compliance center, open the Projects tab

  2. Each project row shows its framework labels and an adherence percentage. Click into the Tanuki Shop project.

  3. The Compliance Status Report lists every requirement and every control on that project. Each control shows Pass, Fail, or Pending with the timestamp of the most recent check.

  4. Click any failed control to see the evidence — file path, configuration value, or external response — that GitLab used to make the determination.

  5. Use the Export menu to download the report as CSV or JSON for sharing with auditors

Status is recalculated on every default-branch pipeline and on a scheduled cadence, so the report stays current without any manual refresh.

Exporting and reusing a framework as JSON#

Once your framework is shaped right, you’ll want to share it — across groups, across organizations, or with a partner doing the same audit.

  1. From the group’s compliance center, open the Frameworks tab

  2. Click the ⋮ menu next to Tanuki AppSec Baseline

  3. Select Export as JSON file

GitLab downloads a JSON file containing the name, description, color, and the full nested requirements/controls/policies tree. To re-import it elsewhere, open the target group’s compliance center, click New framework, choose Import framework, and upload the JSON file.

GitLab also publishes a library of ready-to-use frameworks you can fork and modify, including templates for SOC 2, ISO 27001, NIST 800-53, and FedRAMP. As covered in Starting from a compliance framework template, importing one of these is almost always faster than authoring from scratch.

You now have everything you need to run security at scale on GitLab:

  • Scanners catching vulnerabilities in code, dependencies, containers, secrets, and running services
  • Policies enforcing gates on every project that needs them
  • Compliance frameworks rolling those scans and policies into named, auditable bundles

The final piece is governing who can operate all of this. Next we’ll cover roles and permissions — including building custom roles for least privilege and separation of duties.

Previous Lesson Next Lesson