Shipping a change is a shared effort. Developers, reviewers, pipelines and deployment systems each play a part, with agents taking on more of that work. Keeping the process secure depends on how those parts work together: who can act, which checks must run, what gets deployed, and how the team responds when something goes wrong.
The GitLab Security Standard connects those responsibilities. Version 1.0, published October 6, 2026, starts with Policy, Audit and Ownership, then follows five stages: Authorize, Isolate, Verify, Release and Respond. Together, they describe the conditions for giving people and agents responsibility for software delivery.
Begin with a service or workflow its owners understand. Follow the work from the original request to the system it affects, identifying who owns the application, security controls and release decisions along the way. That gives each configuration choice a concrete purpose.
The following chapters take you through access and execution restrictions, security checks, artifact approval, deployment and recovery. Each procedure includes the settings and files to change, the behavior to expect, and help with problems you may encounter. Apply the steps to a workflow that matters to your team, such as a code repair, policy change, package release or credential rotation.
If you're addressing a known gap, start with the relevant practice and check the permissions and dependencies around it. If an incident is active or suspected, go directly to stopping, investigating, and recovering and your incident-response process. Containment comes before completing an assessment; return to the wider workflow review once immediate harm is limited.
For unclear permissions, ownership, or records, start with ownership and authority. For excessive access to credentials, tools, or execution environments, start with containment. Missing scans or checks that can be bypassed lead to Verify; uncertainty about what reached production leads to Release.
Contents
- Prepare one workflow and its implementation environment
- Foundation: Establish policy, audit and ownership
- 01 Authorize: Scope identities and credentials
- 02 Isolate: Contain the work and protect its inputs
- 03 Verify: Configure checks and independent review
- 04 Release: Deploy the artifact you approved
- 05 Respond: Practise stopping, investigating, and recovering
- Find, fix and learn: Improve controls and revisit autonomy
- Retire temporary resources
The chapter names follow the official Standard. Each chapter links its named example controls to the steps that support them, including work begun in an earlier chapter. These are implementation choices for GitLab.com Ultimate; completing a setup step doesn't by itself establish the whole stage's outcome.
Prepare one workflow and its implementation environment
Choose the route through the guide
Use one representative application as the thread through the assessment. Select a real service or application whose owners can identify its normal source, pipeline, artifact and deployment path. The Foundation, Authorize and Verify work applies to that selected workflow: record its owners and actual delivery path, inspect the identities and credentials that carry out the work, then configure and observe the relevant scanner profiles, application tests and DAP reviews on ordinary changes.
The worked permission and runtime exercises deliberately use separate private practice projects. They let you make temporary branches, test a denial, register a runner and run local containers without changing the selected application's production path. Carry their result back to the selected workflow as a concrete implementation question:
| Work in this guide | Where it runs | Result to carry forward |
|---|---|---|
| Policy ownership and access checks | practice-application and security-policy |
The effective application and policy identities, plus the permitted and prohibited repository actions. |
| Local isolated task | A trusted local Docker host | The task image, mounts, privileges, network routes and resource limits the service owner would need to reproduce for the real task. |
| Dedicated runner | Its own private runner project | The observed runner configuration and job result, followed by a decision about whether the selected application's actual jobs and DAP flows are eligible only for that trusted runner. |
| Scanner profiles, application-test alignment and DAP review | The selected application | The exact source revision, jobs, reports, review output, exclusions and remaining admission gaps. |
| Release and connected response | A separate private release project and local Docker runtime | The approved artifact identity, release decision and recovery record. Connect these to the selected application's production release path only after its release and response owners implement the corresponding controls there. |
Completing the exercises doesn't establish an earned-autonomy level for the selected workflow. The service owner still needs to show that every prerequisite for the chosen level holds on the actual authoring, verification, runner, release and response paths. These procedures don't connect the Verify results to a gate that an untrusted application Maintainer can't bypass. Keep that requirement open when recording the workflow's supported authority.
Before you begin
The examples use GitLab.com Ultimate and three separate identities: a trusted group Owner, an application Maintainer and an independent reviewer. The Owner creates the namespace and manages access. Use the application identity when checking what an application author can do; an Owner session has broader permissions and would give a misleading result. Release and connected response add a service-account release operator; the same service-account identity receives a fresh token for recovery after the affected token is revoked. A standalone release can instead use an authorized human deployer and ends with the release chapter's rollback and cleanup.
For the command-line procedures, start by getting the example files and setting the absolute GSS_GUIDE_CHECKOUT path. Keep that variable when moving between project clones so commands continue to address the intended guide assets. Before creating resources, prepare the tools and credentials for the procedures you plan to follow:
- For the command-line procedures: Bash,
glab,jq, Git,curl, Python 3,sha256sumorshasum, and a trusted credential store. If you download a source archive instead of cloning the guide repository, use a matching extraction tool such asunzip. The release and response tools require Python 3.12 or later and OpenSSL 3, available aspython3andopenssl. - Separate authenticated GitLab sessions for the Owner, application Maintainer and independent reviewer, plus the service-account credential used by the release and connected-response walkthrough. Confirm the effective user before each set of consequential requests.
- For the local task, dedicated runner and release runtime: a trusted Linux ARM64 Docker environment. The local task and release commands use Docker Desktop's
desktop-linuxcontext. The dedicated runner has its own context selection and ARM64 Runner/helper images. The release build and job-token exercise use a GitLab-hosted Linux AMD64 runner with thesaas-linux-small-amd64tag; keep those image and runner requirements separate from the local runtime. - The exact pinned Python runtime used by the local isolated-task and release examples. Follow Prepare the Python runtime before either walkthrough; the repository contains the image reference and acquisition instructions rather than the image itself.
Keep two locations distinct throughout the guide: GSS_GUIDE_CHECKOUT is the guide and example asset root, while each authenticated application or release clone is a separate project checkout. Commands that change application source run from the intended project checkout. Commands that load example programs or drivers use absolute paths below GSS_GUIDE_CHECKOUT.
For scanner onboarding, choose a representative application with supported source files, dependency inputs and working CI/CD. Use an ordinary application change to check scanner activity. The permission and execution exercises use a private practice scope so their temporary branches, role checks and runtime changes don't interfere with a production workflow. Keep production credentials out of those exercises.
For an existing service, first identify its application project, default branch, policy project, runner, artifact registry and deployment environments. Record the settings you intend to change before changing them. Keep secrets in the credential store you already use; the record needs credential names, owners, scopes and expiry, not secret values.
Create the isolated project scope
Keep application code and policy administration in separate projects so their permissions can be managed independently. Create the following layout as the trusted group Owner:
- Open the intended parent group and select New subgroup. Create a private subgroup named
security-practice. Choose another unused name if it already exists. GitLab's subgroup instructions describe the creation and inheritance behavior. - Within it, create a private subgroup named
applicationsand a private blank project namedpractice-applicationin that subgroup. Initialize the project with a README. Use the blank-project creation flow and check the displayed namespace before creating it. - If you're also preparing policy ownership, create a separate private project directly under
security-practice. Use the display name Practice - security policy project and the project slugsecurity-policy. This places it outside theapplicationssubgroup. Initialize it with a README; policy configuration comes after ownership is established. - In each project's Manage > Members, inspect the Source of inherited and shared membership. Repeat at both subgroups and the parent group. A private subgroup still inherits access and other settings from its ancestors.
- Review inherited CI/CD variables, available runners and effective policies with their owners before running the sample. A new private project isn't automatically isolated from those resources. If the parent supplies production credentials or unsuitable execution access, choose an authorized namespace without those dependencies before continuing.
The resulting layout is:
<your-group>/security-practice/
├── security-policy/
└── applications/
└── practice-application/
Use names that fit your namespace and keep the resulting paths and project IDs handy for the commands below. Confirm that both subgroups and both projects are private, with the application project under applications. If an existing project already has a policy link, keep it in place while you review its purpose with the owner. Following this example layout is not a reason to replace it.
Assign and inspect the application role
Open practice-application and select Manage > Members > Invite members. Add the application test identity directly to that project with the Maintainer role. Add the independent reviewer as a Developer in this practice project so they can inspect the source and pipeline results. Review any separate restrictions on artifact access with the project owner. The project membership documentation explains how direct, inherited and shared grants combine.
Keep the application identity out of the governing groups and out of any role that can write to security-policy. If an existing ancestor membership grants more authority, changing the direct project role won't remove it. Resolve that grant with its owner or select a distinct test identity before treating a denial as meaningful.
Record the intended access and compare it with every membership source shown in GitLab:
| Identity | Application project | Policy project | Governing groups |
|---|---|---|---|
| Trusted namespace Owner | Setup and recovery | Policy administration | Owner |
| Application test identity | Direct Maintainer | No write access | No membership granting policy administration |
| Independent reviewer | Developer for source, job and artifact inspection | Only if separately authorized | No broader authority assumed |
In the application identity's session, open the application repository and make a harmless README change on a new branch. Confirm the commit and actor in the Owner session. This confirms that the application account can do ordinary work. The permission checks that follow must also show that it cannot change governing policy or make prohibited writes to the target.
Record the delivery path
With the projects and identities in place, trace a change through the service. Start with the result someone asked for, then identify the repositories, pipelines, artifacts, environments and external systems involved. Include the people who review, release and support the software.
Follow a recent instance of the work rather than relying only on intended architecture. Begin with the request and trace the actual path through source, build, verification, artifact storage, deployment, and operation. Include human, service, and agent identities. Record where work crosses into another project, group, runner environment, registry, cloud account, or third-party service. Those transitions often reveal authority that isn't visible in the application repository.
Then compare the path with the security information the team actually receives. Identify which scanners or other checks examine the change, when they run, what they cover, and where someone sees their results. A configured scanner doesn't establish coverage. A job can be skipped, scan the wrong artifact, or produce no usable report while the pipeline remains green. In the group, start at Secure > Security configuration > Scanners and inspect each project's profile and coverage. Check any existing CI/CD configuration or policy that also supplies scanning, then inspect the pipeline for the actual change. The security inventory supplies the group view; a configured profile and a completed scan answer different questions.
A small starting record is usually enough:
| Question | What to record |
|---|---|
| What work is being delegated? | The requested result, normal trigger, and consequential actions |
| What can the workflow reach? | Projects, files, tools, credentials, networks, registries, and environments |
| Who owns the outcome? | Service owner, workflow owner, security contact, and recovery authority |
| What protects the path today? | Reviews, scans, execution controls, release controls, and response procedures |
| What remains uncertain? | Missing owners, unobserved paths, unclear permissions, and incomplete records |
Give missing information an owner. If the team can't identify which artifact reached an environment, start with the available source and pipeline records and work with the release owner to connect them to the deployment. Resolve that missing connection before delegating release decisions to the workflow.
First address any gap that undermines a prerequisite for the workflow's current authority or prevents the team from stopping harm. Resolve those gaps before expanding what the workflow can do. Otherwise, begin with the action that could have the greatest impact. Agree who will make the change and how you'll check it: useful work should still succeed, and the action you meant to prevent should be refused. Use what you learn to choose the next improvement.
The Standard applies to each workflow according to its authority and impact. A code-writing workflow and a credential-response workflow can use the same security principles without using the same controls. Keep their assessments separate enough that success in one doesn't quietly justify more autonomy in the other.
Foundation: Establish policy, audit and ownership
The Standard's Foundation connects policy decisions to accountable people and durable records. The policy repository prepared here also supports Verify: Protected checks later in the journey.
| Foundation element | Implementation steps |
|---|---|
| Policy | Establish administration by protecting the policy branch and linking the policy project. Then define, approve and enable the actual rules, and check their enforcement. |
| Audit | Retain the activity record and preserve incident history. |
| Ownership | Assign accountable people and maintain the service runbook. |
Assign accountable people
Name the service owner, policy administrator, runner owner, security reviewer and release operator before assigning permissions. One person may fill several operational roles, but authorship and the independent approval of that author's change need separate decision makers. Record who takes over when an owner is unavailable and who can stop the workflow. These responsibilities apply to agents and service accounts as well as people.
Once the delivery path is clear, decide who may change its controls. The people responsible for security policy need to manage it without giving application authors the same authority. In this section, you'll protect a separate policy repository, link it to the application subgroup and check access with the Owner and application accounts. An enabled policy and checks on actual application changes are still needed to enforce a merge requirement.
Use the security-practice layout prepared earlier:
<your-group>/security-practice/
├── security-policy/
└── applications/
└── practice-application/
This procedure uses the trusted namespace Owner as the policy administrator. The application test identity remains a direct Maintainer of practice-application, receives Reporter access to security-policy, and has no membership in security-practice or applications, no custom role, and no other grant that can administer policy links. Reporter access lets the application identity inspect the policy repository without granting write or merge authority.
GitLab requires the Owner role, or a custom role with manage_security_policy_link, to link a security policy project. GitLab also recommends a separate policy location to reduce inherited access. Review security policy projects and project membership sources before assigning access.
Confirm the authority boundary
As the trusted Owner:
- Open
security-policyand select Manage > Members. - Add the application test identity directly with the Reporter role. If it already has access, inspect the Source column and reduce or remove any direct grant above Reporter.
- Open Manage > Members in
security-practice,applications,security-policy, andpractice-application. Check the application identity's direct, inherited, invited-group, and shared-project sources. - Stop if the application identity is an Owner of a governing group, a Maintainer or Developer of
security-policy, or has a custom role withmanage_security_policy_link. Remove the excess grant with its owner, or use a separate test identity. - Record the application and policy project paths, their numeric project IDs, the
applicationssubgroup path, the policy default branch, the application identity, and every membership source you accepted.
Use glab and jq for the checks below. Prepare one CLI session authenticated as the application identity and another authenticated as the trusted Owner, using your approved credential handling. GitLab's CLI authentication instructions cover interactive login and credential precedence. Separate terminal windows or configuration directories alone do not guarantee different credentials: environment variables and a shared keyring can override the intended account. Confirm the effective identity before each set of writes.
In both sessions, set these non-secret values to the paths and numeric IDs you recorded:
export GSS_APP_PATH='<your-group>/security-practice/applications/practice-application'
export GSS_APP_ID='<numeric-application-project-id>'
export GSS_POLICY_PATH='<your-group>/security-practice/security-policy'
export GSS_POLICY_ID='<numeric-policy-project-id>'
export GSS_SUBGROUP_PATH='<your-group>/security-practice/applications'
glab api --hostname gitlab.com user | jq '{id, username}'
glab api --hostname gitlab.com "projects/${GSS_POLICY_ID}" \
| jq '{id, path_with_namespace, default_branch}'
Check that each /user response names its intended identity and that both project reads identify the policy project. Stop on any mismatch. The following examples use a new private policy project whose default branch is main. If yours differs, use its actual branch name, URL-encoded when it appears in an API path.
Protect the policy default branch
In security-policy, as the trusted Owner:
- Select Settings > Repository and expand Branch rules.
- Open the rule for the actual default branch, commonly
main. Create an exact-name rule if none exists. - Set Allowed to merge to Maintainers.
- Set Allowed to push and merge explicitly to No one. Do not leave it unconfigured.
- Leave force push disabled and save each setting.
- Inspect every other rule whose exact name or wildcard also matches the default branch. GitLab combines matching rules and generally applies the most permissive result, so remove or tighten a matching rule that restores broader push or merge access.
These settings require changes to the default branch to arrive through a merge request while allowing trusted policy Maintainers and Owners to merge. GitLab documents both the settings and the effect of overlapping rules in protected branches and protection rules and permissions.
After saving, reopen the rule and check the branch name, Allowed to merge, Allowed to push and merge, force-push setting and every other matching rule. These settings protect changes to the policy repository. Application merge enforcement is a separate step.
Verify policy-repository and merge permissions
Check the permissions with a harmless documentation change. Using the same change for both accounts helps you see whether GitLab is rejecting the application account because of its permissions. Leave .gitlab/security-policies/policy.yml untouched so the check cannot enable or alter a security policy.
In the Owner terminal, record the current policy default-branch SHA:
glab api --hostname gitlab.com \
"projects/${GSS_POLICY_ID}/repository/branches/main"
Record commit.id as GSS_POLICY_MAIN_BEFORE. Check that the proposed policy-authority-positive branch and policy-ownership-check.txt file do not already exist; use fresh names if an earlier exercise retained them.
In both terminals, set GSS_POLICY_MAIN_BEFORE and GSS_PROBE_BRANCH as shown below. Prepare the request body once in a location both operators can read, or transfer the same non-secret file between their sessions. The example uses /tmp/policy-authority-commit.json. It creates a new branch from the recorded default branch and adds a harmless file; it does not edit policy YAML:
export GSS_POLICY_MAIN_BEFORE='<full-default-branch-commit-sha>'
export GSS_PROBE_BRANCH='policy-authority-positive'
jq -n \
--arg branch "$GSS_PROBE_BRANCH" \
--arg start_sha "$GSS_POLICY_MAIN_BEFORE" \
'{
branch: $branch,
start_sha: $start_sha,
commit_message: "Document separate policy ownership",
actions: [{
action: "create",
file_path: "policy-ownership-check.txt",
content: "Policy ownership is administered separately from the application.\n"
}]
}' > /tmp/policy-authority-commit.json
Run the request first in the application-identity terminal:
glab api --hostname gitlab.com --include --method POST \
"projects/${GSS_POLICY_ID}/repository/commits" \
--input /tmp/policy-authority-commit.json
GitLab must reject this commit request with an explicit permission denial. A stale SHA, invalid request, 404 or connection failure needs investigation before you can attribute the rejection to permissions. Switch to the Owner terminal and confirm that the default branch still points to GSS_POLICY_MAIN_BEFORE and that the proposed branch returns 404:
glab api --hostname gitlab.com \
"projects/${GSS_POLICY_ID}/repository/branches/main" \
| jq '{name, commit_id: .commit.id}'
glab api --hostname gitlab.com --include \
"projects/${GSS_POLICY_ID}/repository/branches/${GSS_PROBE_BRANCH}"
Now run the identical commit request as the Owner. It must return HTTP 201. Copy the returned commit id into GSS_SOURCE_SHA in both sessions:
export GSS_SOURCE_SHA='<full-returned-source-commit-sha>'
Check both branches before opening the merge request. The new branch must point to GSS_SOURCE_SHA, and the default branch must still point to GSS_POLICY_MAIN_BEFORE:
for GSS_BRANCH in main "$GSS_PROBE_BRANCH"; do
glab api --hostname gitlab.com \
"projects/${GSS_POLICY_ID}/repository/branches/${GSS_BRANCH}" \
| jq '{name, commit_id: .commit.id}'
done
In the Owner terminal, open a merge request from policy-authority-positive to the policy default branch:
glab api --hostname gitlab.com --include --method POST \
"projects/${GSS_POLICY_ID}/merge_requests" \
--field "source_branch=${GSS_PROBE_BRANCH}" \
--field 'target_branch=main' \
--field 'title=Verify separate policy ownership' \
--field 'remove_source_branch=false'
After the merge request is created with HTTP 201, set its numeric IID and open its API record in both sessions:
export GSS_MR_IID='<policy-project-merge-request-iid>'
glab api --hostname gitlab.com \
"projects/${GSS_POLICY_ID}/merge_requests/${GSS_MR_IID}?with_merge_status_recheck=true" \
| jq '{iid, state, sha, detailed_merge_status,
merge_when_pipeline_succeeds, merge_commit_sha}'
Both responses must identify the same open merge request at GSS_SOURCE_SHA. Wait for detailed_merge_status: mergeable before continuing. Resolve any pending approval, pipeline requirement or conflict first; otherwise, a merge rejection could come from that condition instead of the account's permissions.
In the application-identity terminal, attempt to merge that exact revision:
glab api --hostname gitlab.com --include --method PUT \
"projects/${GSS_POLICY_ID}/merge_requests/${GSS_MR_IID}/merge" \
--field "sha=${GSS_SOURCE_SHA}"
GitLab must reject the application account's merge with an explicit permission denial. Keep the status and response body so you can distinguish it from a stale SHA, missing approval, pipeline requirement, conflict, invalid request or connection failure. Immediately repeat the merge-request query above as the Owner and check the default branch:
glab api --hostname gitlab.com \
"projects/${GSS_POLICY_ID}/repository/branches/main" \
| jq '{name, commit_id: .commit.id}'
The request must still be open at GSS_SOURCE_SHA, with automatic merge disabled and merge_commit_sha: null. The default branch must still point to GSS_POLICY_MAIN_BEFORE. If a request timed out, use these records to find out whether it changed anything before trying again.
Run the identical exact-SHA merge request as the Owner. It must return HTTP 200, state: merged and a nonempty merge_commit_sha. Check the merge request and default branch again: the default branch must now point to that merge commit. GitLab documents the SHA check in the merge requests API. Once the merge is confirmed, delete the temporary source branch and check that it returns 404:
glab api --hostname gitlab.com --include --method DELETE \
"projects/${GSS_POLICY_ID}/repository/branches/${GSS_PROBE_BRANCH}"
glab api --hostname gitlab.com --include \
"projects/${GSS_POLICY_ID}/repository/branches/${GSS_PROBE_BRANCH}"
Review the merged diff; it must add only policy-ownership-check.txt. You've now checked that the Owner can make a policy-repository change while the application account cannot make or merge the same change.
Link the policy project to the application subgroup
The policy repository is protected, but its association with the application also needs protection. Use the GraphQL API to check who can assign and remove that link, then leave the policy linked at the subgroup. GitLab describes these operations in its GraphQL mutation reference.
First inspect the current links as the Owner. Use that account for all group-state queries below, because the application account has no subgroup membership and may not be able to read the private group:
export GSS_LINK_QUERY='query($group:ID!,$project:ID!){group(fullPath:$group){fullPath securityPolicyProject{id fullPath}} project(fullPath:$project){fullPath securityPolicyProject{id fullPath}}}'
glab api --hostname gitlab.com graphql \
--raw-field query="$GSS_LINK_QUERY" \
--raw-field group="$GSS_SUBGROUP_PATH" \
--raw-field project="$GSS_APP_PATH"
Both the group and project must be returned, with securityPolicyProject: null on each. If a link already exists, stop and review it with its owner before changing anything.
Set the mutation text in both terminals:
export GSS_ASSIGN_POLICY='mutation($path:String!,$policy:ProjectID!){securityPolicyProjectAssign(input:{fullPath:$path,securityPolicyProjectId:$policy}){errors}}'
export GSS_UNASSIGN_POLICY='mutation($path:String!){securityPolicyProjectUnassign(input:{fullPath:$path}){errors}}'
export GSS_POLICY_GID="gid://gitlab/Project/${GSS_POLICY_ID}"
In the application-identity terminal, attempt a direct application assignment:
glab api --hostname gitlab.com graphql \
--raw-field query="$GSS_ASSIGN_POLICY" \
--raw-field path="$GSS_APP_PATH" \
--raw-field policy="$GSS_POLICY_GID" \
| jq '{mutation: .data.securityPolicyProjectAssign,
errors: [.errors[]? | {path, message}]}'
The HTTP request must complete successfully, with mutation: null and one top-level error at ["securityPolicyProjectAssign"] that identifies a permission denial. Repeat the link query as the Owner; both links must still be null. If the response instead contains a nested policy error, another error message or a schema error, diagnose that problem before continuing. A failed connection or changed link also leaves the permission check unresolved.
Run the identical assignment as the Owner. It must return HTTP 200, no top-level GraphQL errors and an empty mutation errors array. Inspect the result with jq '{mutation: .data.securityPolicyProjectAssign, errors}', then query the links again. The application must name GSS_POLICY_GID, while the subgroup link remains null. Remove this temporary project-level link before setting the subgroup link:
glab api --hostname gitlab.com --include graphql \
--raw-field query="$GSS_UNASSIGN_POLICY" \
--raw-field path="$GSS_APP_PATH"
Wait for the removal to succeed and for both queried links to return null. If GitLab still shows the earlier link, wait and query it again before issuing another change. After a timeout, inspect the links to determine whether removal occurred.
Now assign the intended subgroup link in the Owner terminal:
glab api --hostname gitlab.com --include graphql \
--raw-field query="$GSS_ASSIGN_POLICY" \
--raw-field path="$GSS_SUBGROUP_PATH" \
--raw-field policy="$GSS_POLICY_GID"
After the assignment succeeds, run the link query again. It must show GSS_POLICY_GID on the subgroup and a null direct link on the application. The application now inherits its policy association from the subgroup; the direct field stays null because no separate project-level link was created.
Finally, in the application-identity terminal, attempt to unassign the subgroup link:
glab api --hostname gitlab.com graphql \
--raw-field query="$GSS_UNASSIGN_POLICY" \
--raw-field path="$GSS_SUBGROUP_PATH" \
| jq '{mutation: .data.securityPolicyProjectUnassign,
errors: [.errors[]? | {path, message}]}'
The HTTP request must complete successfully, with mutation: null and one top-level permission error at ["securityPolicyProjectUnassign"]. Query the links as the Owner: the subgroup must still name GSS_POLICY_GID, and the application's direct link must remain null. Diagnose any nested policy error, non-permission message, schema error, changed link or connection failure before continuing. Check the API response even if GitLab hides the corresponding UI control; a missing button alone doesn't confirm that the operation is denied.
GitLab applies a security policy project linked to a group or subgroup to the projects below it. The official link procedure also explains the Owner or custom-role prerequisite and the Secure > Policies readback.
Open Secure > Policies on applications and practice-application. Both pages should name Practice - security policy project. Use these pages when reviewing the policy association, and repeat the permission checks after changing group membership or custom roles.
Keep policy administration separate
The application identity should be able to work in practice-application and read security-policy, while changes to the policy repository and its namespace association remain with the policy administrators. Keep the subgroup association in place and review inherited roles whenever membership changes.
Linking a policy project does not enable a policy by itself. Before relying on application enforcement, create a narrowly scoped policy through GitLab's policy editor, review its generated merge request, merge it through the protected policy repository, and confirm its enabled scope. Enabled policies apply to linked descendants unless their policy scope narrows them. Check both an allowed application change and a change the policy should reject before relying on it.
Diagnose and recover policy authority
- The application identity's repository request succeeds: inspect all membership sources on
security-policyand its ancestors. Remove an inherited Developer, Maintainer, Owner, invited-group, or shared-project grant. Recheck any custom role. Delete the unexpected probe branch as the trusted Owner, confirm that the default branch did not move, and repeat the successful identity and project reads before repeating the permission check. - The application identity can merge: verify its effective role, then inspect every branch rule matching the default branch. A more permissive overlapping rule can control the result. Also confirm that Allowed to push and merge is explicitly No one.
- The Owner cannot create the positive branch through the commits API: confirm the Owner identity, the unchanged starting SHA, that no wildcard protects the proposed source branch, and that project push rules accept the commit. Use the organization's normal reviewed source-branch path if branch creation is intentionally restricted.
- The Owner cannot merge the positive merge request: confirm the target branch, merge status, and all applicable branch and approval rules. Correct the rule or obtain the required trusted approval; do not bypass the protected branch with a direct push.
- The policy project cannot be assigned: confirm GitLab Ultimate, the
Practice - security policy projectdisplay name, thesecurity-policyslug and full path, visibility, and the Owner's access. Do not weaken visibility or membership to force discovery. - The application does not show the inherited association: confirm that the link is on
applications, thatpractice-applicationis its descendant, and that a conflicting direct application link is absent. Allow the UI to refresh, then read both policy pages again. - An unexpected policy begins affecting projects: stop application changes, inspect the policy repository's default-branch
.gitlab/security-policies/policy.yml, and preserve the merge and audit records. As the subgroup Owner, open Secure > Policies > Edit Policy Project, remove the link with the trash icon, and save. Read back both subgroup and application policy pages. Unlinking is recovery from unintended scope, not a substitute for correcting and reviewing the policy.
If you decide not to keep this setup, first unlink the subgroup and confirm that the application no longer shows the association. Remove the Reporter membership added for this check and delete /tmp/policy-authority-commit.json. Archive or delete only the temporary resources, preserving the configuration and change records your retention policy requires. Keep credentials out of those records.
Plan audit coverage
The Standard's audit target is an immutable record connecting task to deployment, including agent and model identities, prompts, reasoning steps, tool calls, and actions. Work backward from a recent action to see which of those records you can retrieve, how they connect, and who could alter or delete them.
GitLab project history, pipelines, deployments, approvals, and audit events can supply parts of that account. Coverage and retention differ, and these records don't automatically expose an agent's internal execution or activity in connected systems.1 Check what your agent runtime and external services actually provide, protect retained records against alteration, and make missing details explicit. A boundary log can improve attribution; it doesn't fill in execution details that were never captured. Treat missing required coverage as an Audit gap when deciding autonomy.
Before moving to Authorize, assign an owner to each missing record and identify the system that can produce it. Configure retention and access in that system, then trace one recent task through the GitLab and external records you can actually retrieve. Carry the task, actor, source revision, pipeline or flow session, artifact and deployment identifiers into the delivery-path record. If those records can't yet be connected, keep Audit open and limit the workflow's authority accordingly.
01 Authorize: Scope identities and credentials
With the control owners established, identify who will carry out the work and what each identity can reach. Include the person who starts an agent, the service account that executes it, and any credentials passed to its tools.
| Standard example control | Implementation steps |
|---|---|
| Agent inventory | Inventory enabled agents and flows, with a named human owner. |
| Agent identity | Trace the initiating user and executing identity. |
| Secrets management | Limit credential scope and lifetime, then use the revocation procedure when access ends. |
Inventory enabled agents and flows
Open the group's and project's AI > Agents and AI > Flows pages. Record which items are enabled, the workflows that use them and the person responsible for each. Use the AI Catalog to inspect their definitions and managing projects. For custom items, record the selected version and who can update it; GitLab-managed foundational agents and flows don't use the same version-pinning model. Include integrations and service accounts that aren't represented in the catalog in the same inventory.
Reconcile service accounts with the inventory
Set GSS_GROUP_ID to the numeric ID of the group being reviewed, then list the group's service accounts:
glab api --hostname gitlab.com --paginate "groups/${GSS_GROUP_ID}/service_accounts?per_page=100" | jq --slurp '[.[][] | {id, username}]'
Check that every service account appears in the inventory with an owner. Reconcile the inventory against AI > Agents and AI > Flows at group and project level. Some enabled toggles and external integrations have no single readable API.
Trace the initiating user and executing identity
For runner-executed DAP flows, GitLab's composite identity limits access to the intersection of the initiating user's and service account's permissions. Inspect both memberships, including other projects they can both access. Record the flow session and resulting commit or merge request so another operator can identify the human initiator and the automated action. Agentic Chat in the UI and IDE doesn't use this same composite-identity mechanism, so inspect its authorization separately.
A service account's involvement doesn't make a change independently reviewed. Keep the initiating author separate from the human who approves the resulting change.
Read the merge request author and commit
Set GSS_APP_ID to the application's numeric project ID and GSS_MR_IID to the agent-authored merge request's number within that project. Read the author and commit:
glab api --hostname gitlab.com "projects/${GSS_APP_ID}/merge_requests/${GSS_MR_IID}" | jq '{author: .author.username, sha, web_url}'
Link one flow session to its initiating user, service account and resulting commit or merge request. Check that the executing identity is recorded and differs from the approver. The link between session and human isn't a single API field.
Limit credential scope and lifetime
For each credential the workflow uses, record its issuer, owner, purpose, reachable systems, expiry and revocation procedure without recording its value. Give a task only the access its next action needs. Keep release and policy-administration credentials outside application-controlled jobs. Use the organization's approved secret store; GitLab documents Secrets Manager and external secret providers as retrieval options. Choose the integration for the actual executor and review who can request each secret before supplying it to a flow.
Choose the workflow's delegated authority
With ownership and permissions defined, decide how much work an agent may carry out. The Standard makes that decision per workflow:
- Suggest requires a proven Foundation and Authorize stage. The agent recommends; a person makes the change.
- Propose requires the Foundation and stages through Verify. The agent can open a merge request; a human approves release.
- Act with guardrails requires the Foundation and all five stages, including a tested stop, with limits on volume and blast radius.
Apply these levels to individual workflows. A team can use Propose for application repairs while keeping changes to security controls in Suggest. Neither decision grants the same authority to another workflow, and either can be revisited when its controls change.
Write the authority decision so another practitioner can understand it. Name the allowed task and resources, prohibited actions, approval points, stop conditions, credential issuer and lifetime, records to retain, and accountable owner. For Act with guardrails, define enforceable limits on both the amount of work and the systems it can affect: for example, changes per run and the permitted projects or environments. Avoid blanket statements such as “the agent can maintain the project.” They make it difficult to distinguish intended authority from an accidental capability.
02 Isolate: Contain the work and protect its inputs
Clear ownership tells you who may act. The next step is to limit what their work can reach. Start with the task you just defined and give it the files, APIs, credentials, tools and network destinations it needs, for only as long as it needs them. A task such as “update this supported dependency in these projects” gives you concrete limits to configure and check.
Begin in the application project by reviewing its runners and variables, restricting ad hoc pipeline variables, and limiting job-token access to other projects. You'll then check an allowed repository read and a denied cross-project read. These settings control GitLab access. The local-task and dedicated-runner examples later in this chapter address execution and network restrictions; a complete Isolate implementation also needs trusted control of filesystems, privileges, tools, dependency sources, images, secrets and network routes.
| Standard example control | Implementation steps |
|---|---|
| Isolated execution | Inspect execution inputs, restrict a local task, and configure a dedicated runner. |
| Trusted dependencies | Review dependency sources. Finding vulnerable dependencies through SCA is separate from controlling what enters a build. |
| Sanctioned tools and access paths | Review agent tools and restrict job-token access. |
Record the effective execution inputs
Use the trusted Owner session and the application project ID prepared earlier. Record the project settings and every runner GitLab can offer to the project:
Record project settings and offered runners
glab api --hostname gitlab.com "projects/${GSS_APP_ID}" \
| jq '{id, path_with_namespace, visibility, default_branch,
shared_runners_enabled, group_runners_enabled,
ci_pipeline_variables_minimum_override_role,
ci_push_repository_for_job_token_allowed,
ci_allow_fork_pipelines_to_run_in_parent_project}'
glab api --hostname gitlab.com --paginate \
"projects/${GSS_APP_ID}/runners?per_page=100" \
| jq --slurp '[.[][] | {id, description, runner_type, status, paused,
is_shared, online} ]'
The runner list includes project runners, inherited group runners and allowed instance runners. In Settings > CI/CD > Runners, reconcile the API result with the UI and identify which runner should execute this workflow. Record its owner, scope, executor, tags, protected-runner setting, whether it accepts untagged jobs, projects that can submit work to it, and the operating boundary supplied by the runner owner. GitLab's runner scope documentation explains who can create and share each runner type.
An application Maintainer can create, edit, pause and remove project runners. Treat a project runner administered inside the application project as application-controlled. A group runner administered by trusted group Owners can separate runner administration, but its executor and network still need their own documented controls. GitLab-hosted runners can run the non-secret exercise below; their use alone does not demonstrate the workflow's required filesystem, privilege or egress limits.
For this exercise, select GitLab's hosted Linux AMD64 runner with the saas-linux-small-amd64 job tag. GitLab documents a newly provisioned VM for each job, deletion after execution, blocked public inbound and inter-VM traffic, and permitted public-internet outbound traffic. The VM has passwordless sudo, and the Linux fleet supports privileged Docker-in-Docker. This is a useful disposable execution environment, but it does not restrict the job to approved network destinations, tools or images. Match those limits to the task before supplying credentials. See GitLab-hosted runners and the Linux runner configuration.
Next open Settings > CI/CD > Variables in the application project and its ancestor groups. Record each variable's key, source, environment scope, type, Protected flag and visibility without copying its value. Review applicable pipeline execution policy YAML with its owner for variables supplied by policy. Do not use the variables API for this inventory in a shared terminal recording, because its response includes values.
Project Maintainers can administer project variables, and masked values can still be disclosed by malicious job code. Protected variables limit availability to protected refs; they do not protect a secret from untrusted code that is allowed to run on such a ref. Keep a consequential credential out of this application project unless the identity controlling CI configuration, ref eligibility and runner execution is within the credential's trust boundary. GitLab's CI/CD variable guidance describes masking, hiding, protection and their limits.
Close pipeline-variable and job-token paths
In Settings > CI/CD > Variables, set Minimum role to use pipeline variables to no one allowed unless this workflow has a reviewed need for manually supplied pipeline variables. Once this value is set, only an Owner can change it. Read the effective value back:
glab api --hostname gitlab.com "projects/${GSS_APP_ID}" \
| jq '{id, ci_pipeline_variables_minimum_override_role}'
Check that ci_pipeline_variables_minimum_override_role is no_one_allowed. This blocks the pipeline, trigger, schedule and manual-run variables covered by the setting. Variables in .gitlab-ci.yml, project or group settings, and pipeline execution policies remain available through their own paths. The pipeline-variable restriction documents that distinction.
In the application project, open Settings > CI/CD > Job token permissions:
- Leave the CI/CD job-token allowlist enabled.
- Remove every group or project entry that this workflow does not require. The application project itself is implicit.
- Leave Allow Git push requests to the repository off unless job-token pushes are an explicitly reviewed part of the workflow.
- If the project is public or internal, open Settings > General > Visibility, project features, permissions and limit repositories, artifacts, registries, releases, deployments and environments to project members where unauthenticated or broadly authenticated access is not intended.
Read back the inbound setting and the project and group allowlists:
Read back job-token scope and allowlists
glab api --hostname gitlab.com \
"projects/${GSS_APP_ID}/job_token_scope" \
| jq '{inbound_enabled}'
glab api --hostname gitlab.com --paginate \
"projects/${GSS_APP_ID}/job_token_scope/allowlist?per_page=100" \
| jq --slurp '[.[][] | {id, path_with_namespace}]'
glab api --hostname gitlab.com --paginate \
"projects/${GSS_APP_ID}/job_token_scope/groups_allowlist?per_page=100" \
| jq --slurp '[.[][] | {id, name, web_url}]'
Check for inbound_enabled: true and confirm that every allowlist entry is needed. A group entry includes future projects created anywhere below that group, so prefer a project entry when only one project needs access. The CI/CD job-token scope API describes these settings and responses.
Repeat the same review in every private target project this workflow might read, including security-policy. The target project's allowlist controls inbound job-token access. The user who triggered the source job must also have permission to the requested target resource. An allowlist entry supplies neither that membership nor a general-purpose API token.
These settings are useful limits, but the application Maintainer can change the application project's allowlist and job-token push setting. Place a durable cross-project restriction in the target project or its trusted parent, outside application-Maintainer administration. The allowlist controls supported GitLab resources; it is not a network allowlist, process sandbox, or outbound egress control.
Verify job-token access
Now check how a job token behaves with those settings in place. Use harmless repository files: the application's README.md for the allowed read and a separate private project's README.md for the denied read. The application identity should have Reporter access to the target, while the target's job-token project and group allowlists exclude the application and its ancestors. This lets you distinguish a job-token restriction from an account that cannot read the target at all. The security-policy project prepared earlier is suitable if it meets these conditions.
The local commands below require Bash, glab, jq, and Python 3. Before the pipeline, read both files as the trusted Owner and read the target file as the application identity. Require successful reads and retain the target's main SHA and file digest. In the Owner session, run:
(
set -euo pipefail
export GSS_DENIED_PROJECT_ID="<numeric-private-target-project-id>"
GSS_APP_MAIN_SHA="$(glab api --hostname gitlab.com \
"projects/${GSS_APP_ID}/repository/branches/main" \
| jq -er '.commit.id')"
GSS_TARGET_SHA="$(glab api --hostname gitlab.com \
"projects/${GSS_DENIED_PROJECT_ID}/repository/branches/main" \
| jq -er '.commit.id')"
GSS_OWNER_APP_FILE="$(mktemp)"
GSS_OWNER_TARGET_FILE="$(mktemp)"
glab api --hostname gitlab.com \
"projects/${GSS_APP_ID}/repository/files/README.md/raw?ref=${GSS_APP_MAIN_SHA}" \
>"${GSS_OWNER_APP_FILE}"
glab api --hostname gitlab.com \
"projects/${GSS_DENIED_PROJECT_ID}/repository/files/README.md/raw?ref=${GSS_TARGET_SHA}" \
>"${GSS_OWNER_TARGET_FILE}"
GSS_OWNER_APP_SHA256="$(python3 -c \
'import hashlib, sys; print(hashlib.sha256(open(sys.argv[1], "rb").read()).hexdigest())' \
"${GSS_OWNER_APP_FILE}")"
GSS_OWNER_TARGET_SHA256="$(python3 -c \
'import hashlib, sys; print(hashlib.sha256(open(sys.argv[1], "rb").read()).hexdigest())' \
"${GSS_OWNER_TARGET_FILE}")"
printf 'application_main_sha=%s application_bytes=%s application_sha256=%s\ntarget_sha=%s target_bytes=%s target_sha256=%s\n' \
"${GSS_APP_MAIN_SHA}" "$(wc -c <"${GSS_OWNER_APP_FILE}" | tr -d ' ')" \
"${GSS_OWNER_APP_SHA256}" \
"${GSS_TARGET_SHA}" "$(wc -c <"${GSS_OWNER_TARGET_FILE}" | tr -d ' ')" \
"${GSS_OWNER_TARGET_SHA256}"
rm -f "${GSS_OWNER_APP_FILE}" "${GSS_OWNER_TARGET_FILE}"
unset GSS_OWNER_APP_FILE GSS_OWNER_TARGET_FILE
)
In the separately authenticated application-identity session, use the same recorded target SHA. This command must succeed without printing the file body:
(
set -euo pipefail
export GSS_DENIED_PROJECT_ID="<numeric-private-target-project-id>"
export GSS_TARGET_SHA="<target-main-sha-from-owner-read>"
glab api --hostname gitlab.com "projects/${GSS_DENIED_PROJECT_ID}" \
| jq -e --argjson id "${GSS_DENIED_PROJECT_ID}" \
'select(.id == $id) | {id, path_with_namespace, visibility}'
GSS_ACTOR_TARGET_FILE="$(mktemp)"
glab api --hostname gitlab.com \
"projects/${GSS_DENIED_PROJECT_ID}/repository/files/README.md/raw?ref=${GSS_TARGET_SHA}" \
>"${GSS_ACTOR_TARGET_FILE}"
GSS_ACTOR_TARGET_SHA256="$(python3 -c \
'import hashlib, sys; print(hashlib.sha256(open(sys.argv[1], "rb").read()).hexdigest())' \
"${GSS_ACTOR_TARGET_FILE}")"
printf 'ordinary_target_bytes=%s ordinary_target_sha256=%s\n' \
"$(wc -c <"${GSS_ACTOR_TARGET_FILE}" | tr -d ' ')" \
"${GSS_ACTOR_TARGET_SHA256}"
rm -f "${GSS_ACTOR_TARGET_FILE}"
unset GSS_ACTOR_TARGET_FILE
)
The application account and Owner must receive files with the same digest. Set the target's numeric ID in GSS_DENIED_PROJECT_ID in the YAML below. GitLab's policy configuration access setting can separately grant access to the CI/CD configuration referenced by a policy; it doesn't grant access to other policy-project contents. Use README.md for this check, never the referenced CI/CD configuration file.
Use an existing authenticated clone of the application project and confirm that its origin URL names that exact project. Starting from the current application main, create the fixed disposable branch gss-containment/job-token-check. Confirm that the remote branch does not already exist before creating it. Add this temporary job to the application project's .gitlab-ci.yml, replace the target-ID placeholder, and review the change before pushing it as the application identity. It does not need to merge into the default branch:
(
set -euo pipefail
case "$(git remote get-url origin)" in
"https://gitlab.com/${GSS_APP_PATH}.git"|"git@gitlab.com:${GSS_APP_PATH}.git") ;;
*) printf 'origin does not name the prepared application project; stop.\n' >&2; exit 1 ;;
esac
git fetch origin main
if test -n "$(git status --porcelain)"; then
printf 'The working tree is not clean; stop before creating the exercise branch.\n' >&2
exit 1
fi
if git ls-remote --exit-code --heads origin \
refs/heads/gss-containment/job-token-check >/dev/null 2>&1; then
printf 'The fixed exercise branch already exists; stop and reconcile it.\n' >&2
exit 1
else
GSS_LS_REMOTE_STATUS="$?"
test "${GSS_LS_REMOTE_STATUS}" -eq 2
fi
git switch --create gss-containment/job-token-check origin/main
test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)"
)
containment-boundary-check:
image: curlimages/curl@sha256:43ebaa53d3806db6b1ce4353b6b26ae638ec1c167ee351524b05690f988bb20d
variables:
GSS_DENIED_PROJECT_ID: "<numeric-private-target-project-id>"
tags:
- saas-linux-small-amd64
script:
- |
set -eu
allowed_status="$(curl --silent --show-error --max-time 20 --retry 0 \
--output allowed.txt --write-out '%{http_code}' \
--header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
"${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/repository/files/README.md/raw?ref=${CI_COMMIT_SHA}")"
denied_status="$(curl --silent --show-error --max-time 20 --retry 0 \
--output denied.txt --write-out '%{http_code}' \
--header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
"${CI_API_V4_URL}/projects/${GSS_DENIED_PROJECT_ID}/repository/files/README.md/raw?ref=main")"
allowed_bytes="$(wc -c < allowed.txt | tr -d ' ')"
denied_bytes="$(wc -c < denied.txt | tr -d ' ')"
allowed_sha256="$(sha256sum allowed.txt | cut -d ' ' -f 1)"
denied_sha256="$(sha256sum denied.txt | cut -d ' ' -f 1)"
printf 'same_project=%s same_bytes=%s same_sha256=%s cross_project=%s cross_bytes=%s cross_sha256=%s runner=%s protected_ref=%s\n' \
"$allowed_status" "$allowed_bytes" "$allowed_sha256" \
"$denied_status" "$denied_bytes" "$denied_sha256" \
"$CI_RUNNER_ID" "$CI_COMMIT_REF_PROTECTED"
test "$allowed_status" = 200
test "$allowed_bytes" -gt 0
case "$denied_status" in
403|404)
printf 'cross_project_denial_body='
cat denied.txt
printf '\n'
;;
*)
printf 'Unexpected cross-project status; denial is unproved.\n' >&2
exit 1
;;
esac
rules:
- if: '$CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == "gss-containment/job-token-check"'
Review and commit only the CI change, then push using the application identity's Git credentials:
(
set -euo pipefail
test "$(git branch --show-current)" = "gss-containment/job-token-check"
git diff -- .gitlab-ci.yml
git add -- .gitlab-ci.yml
git commit -m "test: exercise scoped job-token access"
git rev-parse HEAD
git push --set-upstream origin HEAD:refs/heads/gss-containment/job-token-check
)
Keep the commit SHA so you can find the resulting pipeline. If the push response is lost, compare the remote branch's SHA before retrying. Git and glab can use different credentials, so check that the pipeline below names the application account as its trigger identity.
The image digest identifies the Linux AMD64 build of curlimages/curl:8.17.0. If you change the image or runner, review the platform and repeat both access checks. A job tag selects eligible runners; compare the runner recorded on the job with the runner inventory to confirm which one executed it.
Find the single successful push pipeline for this commit, triggered by the application identity. The job must report same-project 200 with a nonzero file length, and cross-project 403 or 404. GitLab uses those denial statuses when a request is forbidden or the resource is absent or inaccessible to the caller. The job prints the harmless denial body only for those responses; it never prints the successful file body, headers or job token.
A 401, timeout, DNS or TLS failure, 5xx, or another unexpected response needs diagnosis; it doesn't confirm the intended restriction. In the Owner session, inspect the exact pipeline, job and runner records without printing either successful file body:
(
set -euo pipefail
export GSS_DENIED_PROJECT_ID="<numeric-private-target-project-id>"
export GSS_APPLICATION_ACTOR_ID="<numeric-application-actor-user-id>"
export GSS_EXERCISE_BRANCH="gss-containment/job-token-check"
GSS_ENCODED_BRANCH="gss-containment%2Fjob-token-check"
GSS_EXERCISE_SHA="$(glab api --hostname gitlab.com \
"projects/${GSS_APP_ID}/repository/branches/${GSS_ENCODED_BRANCH}" \
| jq -er '.commit.id')"
GSS_PIPELINES_FILE="$(mktemp)"
glab api --hostname gitlab.com --paginate \
"projects/${GSS_APP_ID}/pipelines?sha=${GSS_EXERCISE_SHA}&ref=${GSS_ENCODED_BRANCH}&source=push&per_page=100" \
| jq -s 'add' >"${GSS_PIPELINES_FILE}"
test "$(jq 'length' "${GSS_PIPELINES_FILE}")" -eq 1
GSS_PIPELINE_ID="$(jq -er '.[0].id' "${GSS_PIPELINES_FILE}")"
GSS_PIPELINE_FILE="$(mktemp)"
glab api --hostname gitlab.com \
"projects/${GSS_APP_ID}/pipelines/${GSS_PIPELINE_ID}" \
>"${GSS_PIPELINE_FILE}"
jq -e --arg sha "${GSS_EXERCISE_SHA}" --arg ref "${GSS_EXERCISE_BRANCH}" \
--argjson actor "${GSS_APPLICATION_ACTOR_ID}" \
'select(.sha == $sha and .ref == $ref and .source == "push" and
.status == "success" and .user.id == $actor)' \
"${GSS_PIPELINE_FILE}" >/dev/null
jq '{id, sha, ref, source, status, user}' "${GSS_PIPELINE_FILE}"
GSS_JOBS_FILE="$(mktemp)"
glab api --hostname gitlab.com --paginate \
"projects/${GSS_APP_ID}/pipelines/${GSS_PIPELINE_ID}/jobs?per_page=100" \
| jq -s 'add' >"${GSS_JOBS_FILE}"
jq '[.[] | select(.name == "containment-boundary-check") |
{id, name, status, commit, pipeline, runner, runner_manager}]' \
"${GSS_JOBS_FILE}"
test "$(jq '[.[] | select(.name == "containment-boundary-check" and .status == "success")] | length' \
"${GSS_JOBS_FILE}")" -eq 1
GSS_OWNER_APP_FILE="$(mktemp)"
GSS_OWNER_TARGET_FILE="$(mktemp)"
glab api --hostname gitlab.com \
"projects/${GSS_APP_ID}/repository/files/README.md/raw?ref=${GSS_EXERCISE_SHA}" \
>"${GSS_OWNER_APP_FILE}"
GSS_TARGET_SHA_AFTER="$(glab api --hostname gitlab.com \
"projects/${GSS_DENIED_PROJECT_ID}/repository/branches/main" \
| jq -er '.commit.id')"
glab api --hostname gitlab.com \
"projects/${GSS_DENIED_PROJECT_ID}/repository/files/README.md/raw?ref=${GSS_TARGET_SHA_AFTER}" \
>"${GSS_OWNER_TARGET_FILE}"
GSS_OWNER_APP_SHA256="$(python3 -c \
'import hashlib, sys; print(hashlib.sha256(open(sys.argv[1], "rb").read()).hexdigest())' \
"${GSS_OWNER_APP_FILE}")"
GSS_OWNER_TARGET_SHA256="$(python3 -c \
'import hashlib, sys; print(hashlib.sha256(open(sys.argv[1], "rb").read()).hexdigest())' \
"${GSS_OWNER_TARGET_FILE}")"
printf 'application_sha=%s application_readme_sha256=%s target_sha=%s target_readme_sha256=%s\n' \
"${GSS_EXERCISE_SHA}" \
"${GSS_OWNER_APP_SHA256}" \
"${GSS_TARGET_SHA_AFTER}" \
"${GSS_OWNER_TARGET_SHA256}"
printf 'target_project_allowlist='
glab api --hostname gitlab.com --paginate \
"projects/${GSS_DENIED_PROJECT_ID}/job_token_scope/allowlist?per_page=100" \
| jq -s -c 'add | map({id, path_with_namespace})'
printf 'target_group_allowlist='
glab api --hostname gitlab.com --paginate \
"projects/${GSS_DENIED_PROJECT_ID}/job_token_scope/groups_allowlist?per_page=100" \
| jq -s -c 'add | map({id, name, web_url})'
rm -f "${GSS_PIPELINES_FILE}" "${GSS_PIPELINE_FILE}" "${GSS_JOBS_FILE}" \
"${GSS_OWNER_APP_FILE}" "${GSS_OWNER_TARGET_FILE}"
unset GSS_PIPELINES_FILE GSS_PIPELINE_FILE GSS_JOBS_FILE \
GSS_OWNER_APP_FILE GSS_OWNER_TARGET_FILE
)
Keep the source SHA, pipeline and job IDs, runner ID, ref-protection value, status codes and file digests together. Compare the same-project digest with the Owner's application README digest at that source SHA. GSS_TARGET_SHA_AFTER and its README digest must still match the values recorded before the pipeline.
Check the target's complete project and group job-token allowlists again. They must exclude the application project and its containing groups. The target's implicit self-access may appear in the project allowlist, so the whole list needn't be empty.
The successful same-project read confirms that the job ran, had a working token and reached GitLab. The cross-project rejection is meaningful because you've also checked that the file exists, the application account can read it directly, and the target's allowlist excludes the application's jobs. A rejection on its own wouldn't tell you which restriction caused it.
This check uses the job's short-lived CI_JOB_TOKEN; it does not mint or persist a personal, project or group access token. Keep allowed.txt and denied.txt as temporary job files and do not publish them as artifacts.
The job-token endpoint list permits the repository-file raw endpoint, and GitLab's job-token troubleshooting guidance describes authorization failures as 404 Not Found or similar. The REST status reference defines 403 as a disallowed request and 404 as an inaccessible resource, including authorization failures. This checks one GitLab API permission. To control the job's other credentials, filesystem access and network routes, continue with the execution settings below.
Restrict a local task's execution
For work that needs neither credentials nor an external connection, the local container procedure shows how to restrict a small task on a Docker host. A trusted operator controls the Docker host, image, program and inputs. The application Maintainer must not be able to replace those controls.
Configure a read-only root filesystem and read-only program and input mounts. Run as a non-root user, drop Linux capabilities, enable no-new-privileges, disable networking, and give the task only a small temporary workspace. Set resource limits appropriate to the task. The procedure provides the container commands and a sample program that checks permitted local work and restricted access.
Confirm that the useful task completes, external access fails for the intended network reason, and writes stay within the temporary workspace. Inspect the container configuration as well as the program's output: a failed connection alone doesn't establish that the network is isolated. Remove the task container and its temporary resources when finished.
These controls share the host kernel and don't provide a complete sandbox for hostile code. They also don't configure GitLab CI jobs. Docker explains the mechanisms in Running containers, resource constraints, tmpfs mounts, and Docker Engine security.
Configure a runner outside application administration
A GitLab job needs connections for checkout and artifact upload. The dedicated group-runner procedure adds those connections while keeping runner administration outside the application project. Keep group-runner administration, the runner token, proxy configuration and Docker-host access with the platform owner. Application Maintainers must not receive those permissions.
The worked example uses a private project and a protected default branch that only the trusted Owner can update. Configure the runner while paused, preload the pinned images, and allow only the intended task image. Disable image pulls and services, run the build as a non-root user, drop capabilities, enable no-new-privileges, and set memory and CPU limits. The build and helper containers use an internal Docker network; a separate proxy permits HTTPS connections to GitLab. Only the trusted Runner manager receives the Docker socket.
Before accepting work, confirm the runner's scope, protected-ref eligibility, tag, manager identity and configuration. Run a job that performs a checkout and uploads an artifact, then inspect its actual runner and containers. Check that ordinary work succeeds while prohibited network connections are denied. A tag selects eligible runners; it doesn't prove which runner executed the job. The detailed procedure includes the commands, expected responses and troubleshooting steps.
This job establishes the behavior of the separate runner project only. Before adopting it for the selected application, the runner and service owners need to bind the application's required jobs to an eligible trusted runner and remove or constrain alternate runners that could accept the same work. Inspect scheduled, triggered, parent-child and policy pipelines as well as ordinary branch jobs. For DAP, inspect the actual authoring path: runner-executed flows need the intended runner eligibility and composite identity. Agentic Chat in the UI or IDE uses a different authorization model; inspect where its tools execute and which credentials they use. Repeat the permitted job and representative prohibited paths from the selected application before treating this runner as its execution control.
This Docker-executor configuration provides no PID ceiling. Build-container user settings also don't establish the helper's user identity. The shared host and allowed GitLab connection need to fit the task's risk; these settings alone aren't suitable isolation for arbitrary hostile code or production secrets. Review runner security when selecting the host and executor.
When retiring the runner, pause it and wait for active jobs to finish. Remove its host configuration and token as well as the GitLab runner record. Remove only its own containers, networks and volumes, preserving other work on the host.
Review dependency sources and agent tools
Review package registries, image registries, mirrors and outbound destinations with the runner owner. Check the dependency manifests and lockfiles, permitted registry endpoints and who can change them. The Standard's trusted-dependency example concerns control before packages reach the build. The SCA profile later in this guide reports vulnerable dependencies; enabling it doesn't install a dependency firewall or enforce registry routing.
For DAP, review the flow's execution environment and its project setup before it runs repository code or installs dependencies. A dedicated runner used for the example job isn't automatically the executor for every enabled flow. Inspect the actual flow's runner and access requirements, especially before adding credentials.
Inventory the tools and external connections the agent can use. Where available, use agent tool governance to configure those permissions and examine its supported clients and background-flow behavior. An interactive approval prompt cannot control an unattended action unless the execution path supports that decision. Test the intended restriction in that path before relying on it.
Apply those decisions to the selected workflow rather than stopping at an inventory. The dependency or platform owner should configure the permitted registries, mirrors, image references and outbound destinations on its real build path. The agent or flow owner should configure the allowed tools and credentials on its actual execution path. Record the effective settings and run one permitted dependency or tool action plus a representative prohibited action. If the product or client can't enforce the intended restriction, remove that dependency or tool from the delegated path, place an enforceable control around it, or keep the workflow's authority below the level that requires the restriction.
Check who can weaken the boundary
Before relying on the configuration, revisit the project, runner and job-token pages as the application Maintainer. Note which settings that account can edit, without changing them just to test the UI. GitLab gives Maintainers administration of project runners, project variables and job-token allowlists, so keep that authority in mind when choosing where to enforce a restriction.
Use the trusted Owner to check the controls outside the application role: group-runner administration in a trusted ancestor, the policy project's variables and job-token allowlist, protected policy refs, and the security-policy link. If an application Maintainer can replace, retag, share or reconfigure a required runner or credential, move its administration outside that role before relying on the restriction.
Before a pilot, test the actual permitted task and representative prohibited actions, including excess volume and affected-system scope. A denied action is useful only when the permitted task works. A broken runner, missing file or unreachable service can deny everything without proving a guardrail.
Diagnose and recover containment
- The same-project request fails: inspect the job trace, source SHA, runner eligibility, GitLab connectivity and exact encoded file path. Resolve that failure before interpreting the cross-project result; the job must first be able to read its own project.
- Both requests return
200: stop the exercise. Inspect the target project's project and group allowlists, the trigger user's membership, target visibility and feature visibility. Remove unintended target-side entries with the target owner, then repeat both checks. - The denied request returns neither
403nor404: preserve the status and safe diagnostics without printing credentials or a successful response body. A401,5xx, timeout, DNS or TLS failure is not the expected allowlist denial; resolve authentication, service or network health before repeating the check. - The job runs on an unexpected runner: cancel it, preserve the job's runner ID and trace, then reconcile tags, untagged-job settings, runner scope and inherited runners. Do not put a credential into the job until the intended runner is selected reliably.
- A protected variable appears on an unprotected branch: cancel the pipeline, remove or rotate the credential through its owner, preserve the job/ref/settings record, and resolve protected-ref eligibility before continuing.
- An unneeded allowlist entry or runner remains: remove or pause it with its trusted owner and read the complete paginated inventory again. Deleting a runner in GitLab does not remove its host configuration; the runner owner must also unregister or decommission that configuration.
After the exercise, retain the trace and state readbacks, confirm the pipeline is terminal, and remove the disposable source branch. Remove any membership granted solely for the exercise and revoke temporary access tokens using the response procedure below. If the job has already been merged, remove it through a reviewed merge request unless it will remain as an owned regression check. Restore temporary allowlist or runner changes with their owner; never restore broader access merely because it was the starting state. Keep temporary projects private, assign an owner and a review or deletion date, and preserve required logs before deleting a project.
Before extending this setup to untrusted application code, sensitive credentials or production systems, review the execution environment with its owner. The example shares a local Docker host and allows GitLab connections through a proxy. You still need to resolve alternative-runner eligibility, select the required kernel and tenant separation, and define secret delivery and allowed destinations. Check the permitted task and relevant prohibited actions again after those choices are implemented.
03 Verify: Configure checks and independent review
Security checks need to fit the team's normal delivery workflow. Start by enabling scanner coverage, then add agent-assisted review and triage where they help people act on the results. Keep the decision to accept a change with controls that its author can't alter.
| Standard example control | Implementation steps |
|---|---|
| Policy in the execution path | Enable scanner profiles, align application tests and scanners, then connect required checks to admission. Profile attachment alone doesn't enforce merge. |
| Protected checks | Separate policy administration, protect its branch, and inspect who can change scanner, profile and execution inputs. |
| Separation of duties | Review DAP proposals and configure independent approval. An agent's assessment isn't an approval. |
Enable SAST, SCA and secret detection
GitLab security configuration profiles enable scanners without adding templates to each project's .gitlab-ci.yml. This procedure uses the default profiles for static application security testing (SAST), dependency scanning, and secret detection. For software composition analysis (SCA), this walkthrough uses GitLab Dependency scanning to identify vulnerable application dependencies.
Use the representative application selected during preparation. If you're continuing in practice-application, add reviewed application source and dependency inputs first; a README-only project won't exercise SAST or dependency scanning.
Profiles require GitLab Ultimate. Use a Security Manager, Maintainer, or Owner role for the group. Projects also need working CI/CD pipelines and eligible runners. Before enabling dependency scanning, confirm that each project contains a supported lockfile or dependency graph export, or can produce one through supported resolution or manifest fallback. A profile can't create meaningful coverage from an unsupported layout.
Apply the default profiles to the selected project
Use Advanced setup so the change applies only to the projects and scanners you choose:
- In the top bar, select Search or go to and open the group that contains the application project.
- In the left sidebar, select Secure > Security configuration, then select the Scanners tab.
- Select Enable scanners.
- Select Advanced setup, then Start advanced setup. Quick setup applies GitLab's default profiles to every uncovered project in the group, so it is too broad for this procedure.
- On Select projects, select the application project. Review the Scanner coverage column for any existing coverage. Advanced setup accepts up to 100 items.
- On Select scanners, select Static application security testing (SAST), Dependency scanning, and Secret detection. Choose the GitLab default profile for each scanner.
- On Review configuration, check the exact project, scanners, and profiles. Use the edit icons beside Items or Scanners to correct the selection.
- Select Apply configuration. GitLab applies profiles in batches, which can take several minutes. On the confirmation step, check each scanner, profile, and item count.
Applying a profile to a group selection attaches it to each selected project. Profiles aren't inherited through the group or subgroup hierarchy. Apply them explicitly to future projects.
The default profiles cover complementary events:
- SAST and dependency scanning run in merge request pipelines when commits are pushed to a branch with an open merge request, and in pipelines for the default branch.
- Secret detection runs in merge request and default-branch pipelines. Its default profile also enables push protection, which checks Git pushes in real time.
Attaching a profile doesn't create a historical result or prevent someone with sufficient authority from replacing it. Use the independently controlled verification steps below to assess who can alter or bypass required checks.
Align application tests with profile scanners
Profile-based scanners and application tests need to meet in the pipeline for the change being reviewed. A test job with no rules, only or except configuration is excluded from merge request pipelines by default, even when profile scanners run there. Include the application's tests explicitly so reviewers can inspect both results for the same source revision.
The following Node example assumes the project already has a reviewed package.json, a usable npm test script, and a committed package-lock.json. It also assumes the project can use an eligible GitLab-hosted Linux AMD64 runner with the saas-linux-small-amd64 tag and can pull node:22-alpine. The lockfile supplies the dependency versions for npm ci and dependency scanning. The example uses npm ci --ignore-scripts to avoid running package lifecycle scripts during installation. If the application's trusted build or tests depend on those scripts, adapt the install and test steps through the project's existing review path rather than silently omitting required setup.
Application test job alongside profile scanners
workflow:
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
- if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
- if: '$CI_COMMIT_BRANCH && $CI_OPEN_MERGE_REQUESTS && $CI_PIPELINE_SOURCE == "push"'
when: never
- when: always
stages:
- test
node_test:
stage: test
image: node:22-alpine
tags:
- saas-linux-small-amd64
script:
- npm ci --ignore-scripts
- npm test
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
- when: on_success
The first two workflow rules create merge request and default-branch pipelines. The third suppresses only a non-default branch's push pipeline when that branch already has an open merge request. This avoids a duplicate push pipeline without suppressing the MR pipeline. The final fallback retains ordinary branch pushes before an MR opens, along with tag, web, API, scheduled, and other pipeline sources. Review that fallback against any intentional exceptions in the existing configuration; it shouldn't weaken a rule that deliberately prevents a source from creating a pipeline.
Treat the YAML as a pattern to merge into the existing file, not as a replacement for it. Keep existing stages, jobs, include entries, variables, and source-specific rules. If the project already has workflow:rules, add the MR and duplicate-suppression behavior in the existing ordered rule set and check how the first matching rule affects every supported source. Add the explicit MR condition to each application job that needs to accompany the scanners. A job can't combine rules with only or except; either retain the team's established mechanism or translate its existing source restrictions into an equivalent ordered rules list before adding the MR condition. GitLab's workflow:rules documentation and job rules documentation explain ordering, duplicate pipelines, and source matching. Scanner selection still comes from the profiles in Secure > Security configuration > Scanners; don't copy scanner templates or profile settings into this application-job example.
Open an ordinary merge request and inspect the pipeline for its current head SHA. Confirm that the application test and SAST, dependency scanning, and secret detection jobs are present and individually successful, with the expected test output and scanner reports. Then merge through the normal review path and repeat those checks in the pipeline for the resulting default-branch SHA. Job selection before the MR opens can differ: an ordinary branch push can run the application test while the profile scanners wait for an MR or the default branch.
If the application test is missing but scanners are present, inspect the application's job-level rules, only or except clauses, declared stage and includes. If a scanner is missing while the application test runs, inspect the applied profile and its triggers, supported source or lockfile, and declared stages. For a job that exists but remains pending, check runner eligibility and tags; for a failed job, use its log to diagnose analyzer-image access, installation or execution errors. Fix the configuration at its source. An ordinary application change is enough for this check of job selection and execution.
Profile scanner jobs can use allow_failure: true, so the overall pipeline can remain green when a scanner fails. Inspect the expected job list, each scanner's status, and its report rather than inferring scanner execution from the pipeline status. A successful scan can still contain findings, and running the jobs together doesn't prevent a Maintainer from changing an application-controlled admission path. For checks that must block a merge, assess the admission decision and who can alter it.
To roll back a CI-only alignment change, revert the reviewed rules change through an ordinary merge request and confirm the next affected pipelines. Remove only the rules introduced for the alignment; preserve unrelated jobs, stages, includes, and intentional source gating.
Check configuration and scanner health
Use the next ordinary, reviewed application change to check the setup.
- Before relying on the profiles, review
.gitlab-ci.yml, included CI/CD configuration, security policies, and existing scanner settings. The wizard configures profile-based scanners; configuration supplied by CI/CD or a security policy must be changed at its origin. GitLab can show conflicting status when legacy and profile-based configuration coexist. Once the intended profiles and scope are confirmed, remove redundant legacy scanner includes through the normal review path if profiles will be authoritative. - Follow the pipeline alignment check for an ordinary merge request and the resulting default-branch revision. Confirm that the application test and selected scanner jobs are present and individually successful for the expected SHA. A job can complete successfully with no findings.
- Investigate an absent, skipped, or failed scanner job. Check its rules, supported languages and dependency files, runner eligibility, analyzer-image access, declared stages, and profile triggers. Dependency scanning needs scannable dependency data; a successful application build doesn't establish SCA coverage.
- After the next default-branch pipeline completes, return to Secure > Security configuration > Scanners. Review the Unprotected projects, Needs attention, and Stale scans cards, then select View details beside each scanner. Confirm the project, applied profile in Source, Status, and Last scan. A stale scan has been absent from at least three consecutive default-branch pipelines.
- You can also open Secure > Security inventory and review Test Coverage. Inventory evaluates pipeline-based coverage from the most recent completed default-branch pipeline. Push protection is event-based, so it can be active without a last-scan date.
Retain the selected profile names and project scope, source revision, pipeline URLs, and scanner job statuses. These records establish scanner activity for supported content at those revisions. A clean result doesn't prove that unsupported languages, out-of-scope dependencies, other branches, or a deployed artifact were examined.
See the Scanner Enablement Wizard for current prerequisites and behavior.
Interpret secret push-protection status
In the application project, open Secure > Security configuration > Security testing. Two parts of this page can describe secret push protection from different configuration sources:
- In Profile-based scanner configuration, open the applied secret-detection profile and inspect its triggers. Secret push protection: On means that profile contains the Git-push trigger.
- The separate Secret push protection card and project toggle report the legacy project setting. That card can say Not enabled while an applied profile supplies the Git-push trigger.
GitLab can enable push protection through either the project toggle or an applicable secret-detection profile with the Git-push trigger. An off legacy toggle alone therefore doesn't mean protection is disabled. The profile must be attached and available under the project's license. Instance availability, supported HTTP or SSH push handling, push and diff size limits, exclusions, and documented skip behavior also affect what is checked. See the secret push protection workflow and the security configuration profile documentation.
Use the profile details and project toggle to identify which configuration supplies protection. These settings describe whether eligible pushes should be checked; they don't demonstrate that a particular push was blocked or that every path is covered. Pipeline success doesn't establish push-time blocking either: push protection runs when Git receives a push, before pipeline jobs execute.
If the values appear contradictory, first confirm the profile attachment, trigger, license and relevant exclusions. Check the legacy toggle separately, and record which configuration source the project relies on. Use a controlled, non-production exercise only when the team needs runtime enforcement evidence; follow GitLab's documented workflow and avoid real credentials.
Change or remove a scanner profile
For a temporary project, return to the scanner's View details page, open the project's actions menu and select Disable profile-based scanning only for the profile you intend to remove. Recheck the project's configuration and preserve records needed for review. For a service you intend to keep scanning, review a replacement with the security owner before removing its current coverage. Disabling a profile doesn't remove pipeline scans supplied by another profile, CI/CD configuration, or a security policy. Removing the secret-detection profile also doesn't necessarily disable push protection supplied by the legacy project setting, another applicable profile, or instance enforcement. See configuring a scanner for projects.
Add DAP security review, triage and remediation
A scanner finding begins a security decision; it doesn't finish one. GitLab Duo can review changed code for logic flaws, assess whether a SAST finding is probably false, and prepare a merge request that attempts a fix. Keep those paths distinct because they need different human checks.
These security flows require GitLab Ultimate and the relevant GitLab Duo Agent Platform features. At the top-level group, an Owner turns on GitLab Duo and the Agent Platform, then enables Allow flow execution, Allow foundational flows, and the intended flows in Settings > GitLab Duo. Check the current foundational flow prerequisites and flow execution requirements, including an eligible runner.
Security Review starts from an ordinary merge request. For SAST triage and remediation, start with a successful supported scan and a real finding in the default-branch Vulnerability Report. Those flows act on ingested findings; they don't configure the scanner or establish its coverage.
Review business logic in the merge request
Security Review Flow reviews a merge request diff and context for logic-level weaknesses such as authorization gaps and information disclosure. It complements SAST; its findings aren't added to the Vulnerability Report or counted by merge request approval policies.
After an Owner allows Security Review and foundational flows, a Developer, Maintainer or Owner assigns Duo Security Review in the merge request's Reviewers section. The flow runs only when assigned; during the beta it doesn't automatically review every merge request and it consumes GitLab Credits.
When it completes, inspect the internal note for scope. On a private project, findings normally appear as diff threads with a CWE, severity, explanation and possible suggestion. Public projects receive findings in the internal note. Serious findings can set Request changes, but the flow never approves the merge request.
Treat each thread as a review prompt. Check the reported path against the application's authorization model, tests and expected data exposure. Mention @duo-security-review to ask a clarifying question, but a reply isn't a new full review. After a correction, assign Duo Security Review again. A human reviewer still decides whether the change is correct and whether the remaining risk fits policy.
Record the merge request SHA, flow note, threads and the corrected SHA. Large diffs might not be fully covered. A no-findings result isn't proof that the change is secure, and a Duo thread doesn't itself block or authorize a merge.
Triage SAST findings before asking for a fix
The SAST False Positive Detection Flow evaluates vulnerabilities produced by GitLab-supported SAST analyzers. It provides a confidence assessment, explanation and badge. This is analysis of a scanner finding, not the merge-request logic review described above.
For a project pilot, an Owner allows SAST False Positive Detection under the top-level group's Settings > GitLab Duo > Allow foundational flows. A Security Manager, Maintainer or Owner then opens project Settings > General, expands GitLab Duo, turns on Turn on SAST false positive detection, and saves. Configure push rules to permit the flow's service account. The user who initiates the flow opens their avatar menu, selects Preferences, finds the GitLab Duo section on the AI assistance tab if that tab is shown, selects the appropriate Default group, and selects Save changes; see Set a default GitLab Duo namespace. The project also needs an eligible runner and default-branch SAST results. Add and protect .gitlab/duo/agent-config.yml when the flow needs project-specific setup.
With the project setting enabled, a successful default-branch SAST scan automatically sends eligible findings for assessment. To analyze an existing finding, open Secure > Vulnerability report, select it, then select AI actions > Check for false positive. Authorized users can also run the flow on selected findings in the report.
Read the explanation alongside the finding, affected code, reachable call paths, tests and application context. The assessment doesn't justify dismissal on its own. A security professional should record the independent reason for confirming, dismissing or deferring the finding through the normal vulnerability workflow.
For an interactive second look, first confirm that the group has foundational agents turned on as described in the Security Analyst Agent prerequisites. Open the GitLab Duo sidebar, select Add new chat, choose Security Analyst, and give it a specific vulnerability ID or URL. For example: “Assess whether this SAST finding is reachable, explain the likely impact, and list the code and runtime assumptions a reviewer should verify.” The agent can help interpret scanner context, EPSS and reachability. It is a chat assistant for investigation; it is not Security Review Flow and doesn't review the merge request as an assigned reviewer.
Review a proposed fix as an ordinary change
Agentic SAST Vulnerability Resolution uses repository context to propose a source fix. At the top-level group, allow both Resolve SAST Vulnerability and SAST False Positive Detection. Configure push rules to permit the flow's service account. The user who initiates the flow opens their avatar menu, selects Preferences, finds the GitLab Duo section on the AI assistance tab if that tab is shown, selects the appropriate Default group, and selects Save changes; see Set a default GitLab Duo namespace. The project also needs an eligible runner. Add and review .gitlab/duo/agent-config.yml when the flow needs build or test setup that it can't infer safely.
Automatic resolution begins after a successful default-branch SAST scan. It considers eligible findings from supported analyzers after false-positive analysis. When it can produce a fix, it opens a merge request and runs its pipeline. To start it manually, open the vulnerability in Secure > Vulnerability report and select Resolve with Agentic AI.
The merge request is a proposed remediation, not a verified outcome. Review the diff for behavior changes and new trust assumptions. Confirm its pipeline and security scan completed for the head SHA, inspect whether the finding is absent from that result, and run focused tests. Use the project's normal reviewers, approval rules and protected-branch path. The flow doesn't approve or merge its proposal, and a passing pipeline doesn't establish production remediation.
For vulnerable dependencies, dependency scanning auto-remediation is a separate beta path. Its generated jobs are untagged, require privileged mode and don't use the project's .gitlab-ci.yml. Review runner and service-account permissions, then assess each proposed version bump normally.
Apply the journey consistently across projects
For broader rollout, security configuration profiles can separate scanner configuration from the Automated triage and remediation profile for false-positive detection, SAST resolution and dependency remediation. Pilot the documented per-project settings above first. When moving to profiles, choose a preset that fits reviewer capacity and use the documented GraphQL API to apply it; don't assume the profile has an equivalent UI action.
Profiles make rollout consistent, but they don't make results authoritative. Verify that the expected scan and flow ran and that any proposal passed human review. Keep merge enforcement, reviewer independence and release authorization in the separately protected controls below.
Make trustworthy verification part of delivery
Scanner results and agent reviews give authors useful feedback. Required checks also need to affect the decision to merge or release a change. That decision needs to account for the source revision or content identity, target branch and relevant target state, rules and scanner versions, results examined, decision made, and events that invalidate that decision. A green pipeline by itself doesn't show that a required check ran, covered the relevant files, used trusted inputs, or produced the result being admitted.
Put checks where they can change the outcome. Early feedback helps an author fix a problem while the change is still familiar. Default-branch and scheduled scans can catch weaknesses missed earlier or disclosed later. When a check is required, its result needs a trustworthy path into the merge or other admission decision.
Where enforcement matters, treat the application Maintainer as untrusted for that particular decision. The policy owner or verifier therefore needs authority outside the application path. Check whether the application actor can change policy selection, scanner configuration, rules, variables, runner execution, report contents, approval eligibility, merge settings, branch protections, or another route to the target.
GitLab security policy projects can separate policy management from application projects and apply policies through namespace relationships.2 That separation is useful only when effective permissions preserve it. Inherited roles matter, as do the people allowed to link, unlink, or manage the policy relationship. Start at Secure > Policies in the project and its parent namespaces. Review security policy project enforcement with the namespace owners, then test the paths available to the application Maintainer.
Merge request approval rules can support independent review, but the rule, eligible approvers, reset behavior, and alternate write paths all affect the outcome.3 A named reviewer isn't independent if the application actor can add another eligible approver, change the rule, push directly to the target, or satisfy the decision through a credential with equivalent authority. Use the merge request approvals documentation to identify the product behavior, then check it in the namespace and role model you actually use.
Inspect project approval defaults in Settings > Merge requests > Merge request approvals, then compare them with the rules on the actual merge request. Inspect the target's branch rules in Settings > Repository > Branch rules. Include every matching rule and its source; a single restrictive entry doesn't establish the effective permissions.
For every control you intend to rely on, compare a permitted result with a prohibited one. First show that a legitimate clean change can complete the intended path. Then attempt a representative bypass through that same admission path and confirm that the target remains unchanged. Make sure an unrelated failure didn't cause the denial. If a request times out, reconcile its result before treating it as a denial or retrying a possible write. Include the alternate update paths found during the permission review; testing only the merge button says little about direct pushes, force pushes, tokens, integrations, or privileged automation.
If a prohibited change reaches the target, restrict the affected authority and correct the cause before relying on the control. When a result is missing or a request has an uncertain outcome, reconcile the state before continuing. After the correction, check that legitimate work still succeeds.
Code review and security verification answer different questions. A risk exception may authorize proceeding despite a known problem, but it doesn't satisfy the Standard's unwaivable Verify outcome. Record the exception's owner, reason, compensating action, expiry and recheck trigger.
Scanner profiles, DAP flows and separate policy ownership do not by themselves provide a complete merge gate resistant to an application Maintainer. Keep that requirement open when assessing the workflow's authority. The release example below teaches artifact identity and deployment authorization separately; it doesn't supply the missing admission control.
Before following the separate release walkthrough, record exactly what the selected application's Verify work accepted: the source SHA or content identity, target state, required scanner jobs and reports, DAP or human review, policy revision and decision owner. Then identify who can connect that accepted result to the application's actual merge and release path. If an application Maintainer can alter or bypass that connection, or if no supported connection exists, keep the Verify-to-Release prerequisite open. A green pipeline, named approver or signed artifact can't replace an independent admission design that preserves the same untrusted-Maintainer model.
04 Release: Deploy the artifact you approved
A deployment should run the exact artifact approved for release. Build it once, record the source and job that produced it, approve its digest, and check that digest again immediately before it starts. Separate release authorization from application authorship so an author can't approve and deploy an arbitrary replacement.
The example below builds a small Python application in a private GitLab project, signs the release decision, and runs the approved bytes in a local Docker container. Two versions, A and B, make both deployment and rollback visible. This build doesn't consume the scanner-profile or DAP review results and doesn't establish a security-verification gate; the signature binds the operator's decision to particular bytes.
The container has no published ports and uses --network none. The example lets you work through digest checking and separate deployment authority. Its local key and shared Docker host aren't a production design; production traffic switching, signing-key custody, and SLSA provenance require additional controls.
| Standard example control | Implementation steps |
|---|---|
| Provenance and signing | Acquire the exact build and sign its release decision. The local signing example is not full SLSA provenance. |
| Verify before deploy | Deploy approved A and reject altered bytes or signers. |
| Immutable references | Carry the artifact digest through deployment and rollback. For a registry, also configure tag protection and overwrite restrictions; the local example doesn't configure them. |
Set application and release permissions
Use a fresh private release project initialized with a README so its default main branch and initial SHA exist before this procedure begins:
- A project Owner protects
main, reviews the build configuration and source, and supplies Owner-only configuration reads. - The application actor remains a Maintainer in the application project but receives only Developer access to this release project. Use that account to confirm that application access does not grant deployment permission.
- For connected response, a release service account receives Developer access to this release project and is the sole deployer for
local-release-lab. A trusted human release operator controls its short-lived credential and the local Docker host. - For a standalone release, an authorized human can receive Developer access and be selected as the sole deployer instead. Choose this identity during permission setup; don't add it later alongside the service account.
Under Settings > Repository > Branch rules, protect main. Allow push, merge, and unprotect only for the named Owner, disable force push, and inspect every matching rule because matching permissions are additive. See protected branches and the Protected branches API.
Under Settings > CI/CD:
- Set the minimum role allowed to use pipeline variables to No one allowed.
- Keep job-token repository pushes disabled.
- Confirm the project can use an online GitLab-hosted Linux AMD64 runner carrying
saas-linux-small-amd64. - Inspect project and ancestor variable metadata. Resolve any inherited build override or credential before continuing; do not export variable values into the release record.
Create an environment named local-release-lab with tier testing. Protect it and allow deployment only by the configured release deployer: the service account for connected response or the authorized human for a standalone release. The Environments REST field is tier; deployment_tier is the CI keyword. See environments, protected environments, and the Environments API.
Whenever the configured deployer's project membership changes, check protected-environment access again. Re-inviting a user doesn't restore a removed user-specific deploy permission, so add that same user to the protected environment again before resuming deployment.
Before adding source, read back the direct and effective memberships, branch rule, project settings, environment, protected-environment rule, runner eligibility, policies, and variable metadata. Record the project ID/path, three user IDs, environment ID, and initial main SHA. These values anchor the later build, authorization, and deployment checks to the project you configured.
Prepare the workstation and sample application
First get the example files. That setup defines GSS_GUIDE_CHECKOUT as the absolute directory containing chapters/01-prepare.md and examples. Keep it separate from the private release-project clone. The workstation commands use release_driver.py, release_tools.py, and docker_runtime.py from that reviewed guide checkout. Keep the driver and Docker helper out of the private build project.
Check the workstation before creating any release state. You need Python 3.12 or later, OpenSSL 3, jq, glab, and Docker Desktop with the desktop-linux context. The build job runs on a Linux AMD64 runner; the local example runtime is ARM64 and uses a pinned image referenced by the example, not included in the downloaded files. Follow Prepare the Python runtime to load and verify that exact image before continuing. Stop before any release operation if a prerequisite differs:
set -euo pipefail
python3 --version
python3 -c 'import sys; sys.exit(0 if sys.version_info >= (3, 12) else "Python 3.12 or later is required")'
openssl version | grep -E '^OpenSSL 3\.'
jq --version
glab --version
docker --context desktop-linux version
docker --context desktop-linux image inspect \
'python@sha256:f77ac9e44ae96ef2c90b8053ea08c31f8be030f824196b0ae4db6d462c84e51f' \
>/dev/null
test -f "$GSS_GUIDE_CHECKOUT/chapters/01-prepare.md"
test -d "$GSS_GUIDE_CHECKOUT/examples"
export GSS_DRIVER="$GSS_GUIDE_CHECKOUT/examples/connected-release/release_driver.py"
export GSS_TOOLS="$GSS_GUIDE_CHECKOUT/examples/connected-release/release_tools.py"
export GSS_PROJECT_ID='<private-release-project-id>'
export GSS_PROJECT_PATH='<namespace/private-release-project>'
export GSS_RELEASE_CHECKOUT='<absolute-path-for-private-release-project-clone>'
export GSS_INITIAL_MAIN_SHA='<recorded-initial-main-sha>'
export GSS_OWNER_ID='<trusted-owner-user-id>'
export GSS_ACTOR_ID='<application-actor-user-id>'
export GSS_RELEASE_OPERATOR_ID='<configured-release-deployer-user-id>'
export GSS_ENVIRONMENT_ID='<local-release-lab-environment-id>'
export GSS_RECORD_DIR='<absolute-path-outside-both-checkouts-for-release-records>'
[[ "$GSS_GUIDE_CHECKOUT" = /* && "$GSS_RELEASE_CHECKOUT" = /* && "$GSS_RECORD_DIR" = /* ]]
GSS_RELEASE_CHECKOUT="$(python3 -c 'import os,sys; print(os.path.realpath(sys.argv[1]))' "$GSS_RELEASE_CHECKOUT")"
GSS_RECORD_DIR="$(python3 -c 'import os,sys; print(os.path.realpath(sys.argv[1]))' "$GSS_RECORD_DIR")"
python3 - <<'PY'
import os
from pathlib import Path
guide = Path(os.environ['GSS_GUIDE_CHECKOUT']).resolve()
release = Path(os.environ['GSS_RELEASE_CHECKOUT']).resolve()
record = Path(os.environ['GSS_RECORD_DIR']).resolve()
if guide == release or guide in release.parents or release in guide.parents:
raise SystemExit('Guide files and release clone need separate directories')
if any(record == checkout or checkout in record.parents for checkout in (guide, release)):
raise SystemExit('Release records must be outside both checkouts')
PY
test ! -e "$GSS_RELEASE_CHECKOUT"
test ! -e "$GSS_RECORD_DIR"
install -d -m 700 "$GSS_RECORD_DIR" "$GSS_RECORD_DIR/keys"
In the trusted Owner's glab session, require the configured account and project to match the IDs recorded during permission setup. Read the project's SSH clone URL from that authenticated numeric project lookup. The Owner's SSH key must already authenticate to gitlab.com as the same Owner with permission to push protected main. Clone that exact URL into the separate absolute path, select main, and require the recorded initial SHA, exact repository root and origin, and an empty worktree:
test "$(glab api --hostname gitlab.com user | jq -er '.id')" = "$GSS_OWNER_ID"
GSS_RELEASE_PROJECT="$(glab api --hostname gitlab.com \
"projects/$GSS_PROJECT_ID")"
test "$(jq -er '.path_with_namespace' <<<"$GSS_RELEASE_PROJECT")" \
= "$GSS_PROJECT_PATH"
export GSS_RELEASE_REMOTE_URL="$(jq -er '.ssh_url_to_repo' \
<<<"$GSS_RELEASE_PROJECT")"
test ! -e "$GSS_RELEASE_CHECKOUT"
git clone "$GSS_RELEASE_REMOTE_URL" "$GSS_RELEASE_CHECKOUT"
cd "$GSS_RELEASE_CHECKOUT"
test "$(git rev-parse --show-toplevel)" = "$GSS_RELEASE_CHECKOUT"
test "$(git remote get-url origin)" = "$GSS_RELEASE_REMOTE_URL"
test -z "$(git status --short)"
git fetch origin main
git switch main
test "$(git rev-parse HEAD)" = "$GSS_INITIAL_MAIN_SHA"
test "$(git rev-parse origin/main)" = "$GSS_INITIAL_MAIN_SHA"
Copy these reviewed files from the guide checkout to the release-project root, inspect the staged source, and commit and push them through the Owner path:
cp "$GSS_GUIDE_CHECKOUT/examples/connected-release/.gitlab-ci.yml" .gitlab-ci.yml
cp "$GSS_GUIDE_CHECKOUT/examples/connected-release/build_fixture.py" build_fixture.py
cp "$GSS_GUIDE_CHECKOUT/examples/connected-release/release_tools.py" release_tools.py
cp "$GSS_GUIDE_CHECKOUT/examples/connected-release/version.txt" version.txt
git diff --check
git diff
git add .gitlab-ci.yml build_fixture.py release_tools.py version.txt
git diff --cached --check
git diff --cached
git commit -m 'Add connected release fixture'
export GSS_A_SHA="$(git rev-parse HEAD)"
git push origin HEAD:main
test "$(git ls-remote origin refs/heads/main | awk '{print $1}')" = "$GSS_A_SHA"
test -z "$(git status --short)"
Build A uses known-good-a. Its default-branch push pipeline must have exactly one successful build_release_fixture job, which publishes dist/release.pyz and dist/build-manifest.json. This gives the operator one unambiguous build to acquire.
Use short-lived API credentials for the operator actions. If you plan to follow the connected response procedure, use the group service account selected as the deployer during permission setup. The trusted human operator acts through that service account; the service-account user ID remains the sole protected-environment deployer. The trusted group Owner creates its personal access token through the service accounts API. Record the owning group ID, service-account user ID, token ID, scope, and expiry so a responder can revoke that exact token and issue a replacement for the same account without adding another deployer. For a standalone release, select the authorized human as the sole deployer during permission setup, use that person's personal access token, and revoke it through that identity's token settings. Enter tokens at the driver's hidden prompt or expose them only to that process through the named environment variables. Keep their values out of command arguments and shell history.
Select and acquire exact build A
Start by recording A's full source SHA, pipeline ID, and job ID from GitLab. Before acquiring anything, confirm that the pipeline is a successful push on the default branch and that the job succeeded. The driver first uses each held credential to read /user and requires its numeric ID to match the recorded Owner or release-operator ID. A mismatch, authentication failure, or transport failure stops before the acquisition directory is created or any release resource is read. It then repeats the build checks through authenticated APIs, reads the actual runner details, downloads the exact job archive, extracts only the two expected artifacts, retrieves each exact source file with its response identity, and writes operator-inputs.json as the input record for the remaining steps. The receipt and journal retain the confirmed numeric IDs, not credential values or full user profiles:
# GSS_A_SHA is the full SHA pushed during sample initialization.
export GSS_A_PIPELINE_ID='<a-pipeline-id>'
export GSS_A_JOB_ID='<a-job-id>'
python3 "$GSS_DRIVER" acquire \
--project-id "$GSS_PROJECT_ID" --project-path "$GSS_PROJECT_PATH" \
--owner-id "$GSS_OWNER_ID" --operator-id "$GSS_RELEASE_OPERATOR_ID" \
--source-sha "$GSS_A_SHA" --pipeline-id "$GSS_A_PIPELINE_ID" \
--job-id "$GSS_A_JOB_ID" --job-name build_release_fixture \
--version known-good-a --output-dir "$GSS_RECORD_DIR/a" \
--owner-token-env GITLAB_OWNER_TOKEN \
--operator-token-env GITLAB_OPERATOR_TOKEN \
--journal "$GSS_RECORD_DIR/acquire-a.jsonl"
The driver creates the directory once with mode 0700. Don't reuse it after a partial acquisition, because that could mix records from separate attempts. Retain the complete job archive along with the extracted artifact, manifest, source files, input record, and journal. The Jobs API, Pipelines API, Repository files API, Runners API, and Job artifacts API define the values the driver observes.
Create the release identity and sign A
The signature needs a trust reference that doesn't come from the material being verified. Generate an exercise-only Ed25519 key and record its reported fingerprint through the release-approval channel before signing. The trusted fingerprint must not come from the artifact or signature being checked.
Create the release key and record its fingerprint
python3 "$GSS_TOOLS" keygen \
--private-key "$GSS_RECORD_DIR/keys/release-private.pem" \
--public-key "$GSS_RECORD_DIR/keys/release-public.pem" \
| tee "$GSS_RECORD_DIR/keygen.json"
export GSS_TRUSTED_FINGERPRINT="$(jq -er '.fingerprint_sha256' "$GSS_RECORD_DIR/keygen.json")"
Sign the promotion and define verification
Promote A using the exact identities in operator-inputs.json:
promote() {
inputs="$1"; release_id="$2"; output="$3"; signature="$4"
private_key="${5:-$GSS_RECORD_DIR/keys/release-private.pem}"
public_key="${6:-$GSS_RECORD_DIR/keys/release-public.pem}"
python3 "$GSS_TOOLS" promote \
--manifest "$(jq -er '.paths.manifest' "$inputs")" \
--artifact "$(jq -er '.paths.artifact' "$inputs")" \
--private-key "$private_key" --public-key "$public_key" \
--release-id "$release_id" \
--project-id "$(jq -er '.project.id' "$inputs")" \
--project-path "$(jq -er '.project.path' "$inputs")" \
--source-sha "$(jq -er '.source_sha' "$inputs")" \
--pipeline-id "$(jq -er '.pipeline.id' "$inputs")" \
--pipeline-source "$(jq -er '.pipeline.source' "$inputs")" \
--ref "$(jq -er '.pipeline.ref' "$inputs")" \
--job-id "$(jq -er '.job.id' "$inputs")" \
--job-name "$(jq -er '.job.name' "$inputs")" \
--runner-id "$(jq -er '.runner.id' "$inputs")" \
--version "$(jq -er '.version' "$inputs")" \
--builder "$(jq -er '.paths.builder' "$inputs")" \
--ci-file "$(jq -er '.paths.ci' "$inputs")" \
--version-file "$(jq -er '.paths.version' "$inputs")" \
--output "$output" --signature "$signature"
}
promote "$GSS_RECORD_DIR/a/operator-inputs.json" initial-a \
"$GSS_RECORD_DIR/a/promotion.json" "$GSS_RECORD_DIR/a/promotion.sig"
Define the matching verifier once so the normal deployment and rejection checks use the same verification path. Its optional arguments let the rejection checks substitute only the byte or key under test:
verify_release() {
inputs="$1"; release_id="$2"; attestation="$3"; signature="$4"
artifact="${5:-$(jq -er '.paths.artifact' "$inputs")}"
public_key="${6:-$GSS_RECORD_DIR/keys/release-public.pem}"
fingerprint="${7:-$GSS_TRUSTED_FINGERPRINT}"
python3 "$GSS_TOOLS" verify \
--manifest "$(jq -er '.paths.manifest' "$inputs")" --artifact "$artifact" \
--attestation "$attestation" --signature "$signature" --public-key "$public_key" \
--trusted-fingerprint "$fingerprint" --release-id "$release_id" \
--project-id "$(jq -er '.project.id' "$inputs")" \
--project-path "$(jq -er '.project.path' "$inputs")" \
--source-sha "$(jq -er '.source_sha' "$inputs")" \
--pipeline-id "$(jq -er '.pipeline.id' "$inputs")" \
--pipeline-source "$(jq -er '.pipeline.source' "$inputs")" \
--ref "$(jq -er '.pipeline.ref' "$inputs")" \
--job-id "$(jq -er '.job.id' "$inputs")" \
--job-name "$(jq -er '.job.name' "$inputs")" \
--runner-id "$(jq -er '.runner.id' "$inputs")" \
--version "$(jq -er '.version' "$inputs")" \
--builder "$(jq -er '.paths.builder' "$inputs")" \
--ci-file "$(jq -er '.paths.ci' "$inputs")" \
--version-file "$(jq -er '.paths.version' "$inputs")"
}
Prove authority and deploy A
Before the operator's first deployment, check the separation of authority. The application actor should be able to read its own identity and this release project, but it must not be able to create a protected deployment. The driver attempts one running deployment, accepts only an authorization denial, reads the actor identity again, and requires the deployment-ID inventory to remain unchanged:
python3 "$GSS_DRIVER" deny-deployment \
--project-id "$GSS_PROJECT_ID" --actor-id "$GSS_ACTOR_ID" \
--source-sha "$GSS_A_SHA" --ref main --environment local-release-lab \
--actor-token-env GITLAB_ACTOR_TOKEN \
--journal "$GSS_RECORD_DIR/actor-denial.jsonl"
A timeout leaves the outcome unknown; it isn't an authorization denial. Stop and reconcile the deployment inventory before continuing. Don't repeat a write whose result is uncertain.
With the authority check complete, deploy A in one process. The driver first requires the held operator credential's /user ID to equal GSS_RELEASE_OPERATOR_ID; failure stops before receipt reservation, a GitLab deployment write, or a Docker command. It then revalidates all acquired bytes and the promotion, creates the GitLab deployment as running, verifies again immediately before changing Docker, starts and checkpoints the restricted container, proves its mounted digest, health, and version, updates that exact deployment to success, and reads it back:
Deploy approved A
python3 "$GSS_DRIVER" deploy \
--operator-id "$GSS_RELEASE_OPERATOR_ID" \
--inputs "$GSS_RECORD_DIR/a/operator-inputs.json" \
--attestation "$GSS_RECORD_DIR/a/promotion.json" \
--signature "$GSS_RECORD_DIR/a/promotion.sig" \
--public-key "$GSS_RECORD_DIR/keys/release-public.pem" \
--trusted-fingerprint "$GSS_TRUSTED_FINGERPRINT" \
--release-id initial-a --environment local-release-lab \
--receipt "$GSS_RECORD_DIR/a/runtime.json" \
--operator-token-env GITLAB_OPERATOR_TOKEN \
--docker-context desktop-linux --journal "$GSS_RECORD_DIR/deploy-a.jsonl"
Build and deploy B
Version B shows that the same controls still hold when the application changes. Have the Owner change only version.txt from known-good-a to candidate-b. Review the diff, commit it to protected main, and require a successful default-branch push pipeline and successful build_release_fixture job. Acquire B into a new directory with the same acquire command, substituting B's exact SHA, pipeline ID, job ID, --version candidate-b, output directory b, and a new journal.
Promote B with a distinct release ID:
promote "$GSS_RECORD_DIR/b/operator-inputs.json" candidate-b \
"$GSS_RECORD_DIR/b/promotion.json" "$GSS_RECORD_DIR/b/promotion.sig"
This exercise uses stop-then-start replacement. Inspect A one last time so you know what is running, remove it by its exact receipt, and then deploy B:
python3 "$GSS_DRIVER" inspect-runtime --receipt "$GSS_RECORD_DIR/a/runtime.json" \
--docker-context desktop-linux --journal "$GSS_RECORD_DIR/inspect-a.jsonl"
python3 "$GSS_DRIVER" remove-runtime --receipt "$GSS_RECORD_DIR/a/runtime.json" \
--docker-context desktop-linux --journal "$GSS_RECORD_DIR/remove-a.jsonl"
python3 "$GSS_DRIVER" deploy \
--operator-id "$GSS_RELEASE_OPERATOR_ID" \
--inputs "$GSS_RECORD_DIR/b/operator-inputs.json" \
--attestation "$GSS_RECORD_DIR/b/promotion.json" \
--signature "$GSS_RECORD_DIR/b/promotion.sig" \
--public-key "$GSS_RECORD_DIR/keys/release-public.pem" \
--trusted-fingerprint "$GSS_TRUSTED_FINGERPRINT" \
--release-id candidate-b --environment local-release-lab \
--receipt "$GSS_RECORD_DIR/b/runtime.json" \
--operator-token-env GITLAB_OPERATOR_TOKEN \
--docker-context desktop-linux --journal "$GSS_RECORD_DIR/deploy-b.jsonl"
There is an interruption between A and B. This sequence doesn't provide blue-green deployment or traffic switching.
Reject altered bytes and an unapproved signer
Now check that approval can't be carried over to different bytes. Copy and alter B's artifact, require the same verifier to reject it before any deployment or Docker command, and then inspect B's unchanged receipt:
install -m 600 "$(jq -er '.paths.artifact' "$GSS_RECORD_DIR/b/operator-inputs.json")" \
"$GSS_RECORD_DIR/b/altered-release.pyz"
printf tampered >> "$GSS_RECORD_DIR/b/altered-release.pyz"
if verify_release "$GSS_RECORD_DIR/b/operator-inputs.json" candidate-b \
"$GSS_RECORD_DIR/b/promotion.json" "$GSS_RECORD_DIR/b/promotion.sig" \
"$GSS_RECORD_DIR/b/altered-release.pyz" \
2>"$GSS_RECORD_DIR/b/altered-rejection.txt"; then
echo 'altered artifact was accepted' >&2; exit 1
fi
grep -F 'ContractError: build manifest differs from verified inputs or artifact' \
"$GSS_RECORD_DIR/b/altered-rejection.txt"
python3 "$GSS_DRIVER" inspect-runtime --receipt "$GSS_RECORD_DIR/b/runtime.json" \
--docker-context desktop-linux --journal "$GSS_RECORD_DIR/inspect-b-after-alteration.jsonl"
Next, check the signer. Create a second Ed25519 key and a valid promotion for unchanged B using that key. Verification must reject its unapproved fingerprint while B remains healthy:
install -d -m 700 "$GSS_RECORD_DIR/unapproved-key"
python3 "$GSS_TOOLS" keygen \
--private-key "$GSS_RECORD_DIR/unapproved-key/private.pem" \
--public-key "$GSS_RECORD_DIR/unapproved-key/public.pem" \
>"$GSS_RECORD_DIR/unapproved-key/keygen.json"
promote "$GSS_RECORD_DIR/b/operator-inputs.json" unapproved-b \
"$GSS_RECORD_DIR/b/unapproved.json" "$GSS_RECORD_DIR/b/unapproved.sig" \
"$GSS_RECORD_DIR/unapproved-key/private.pem" "$GSS_RECORD_DIR/unapproved-key/public.pem"
if verify_release "$GSS_RECORD_DIR/b/operator-inputs.json" unapproved-b \
"$GSS_RECORD_DIR/b/unapproved.json" "$GSS_RECORD_DIR/b/unapproved.sig" \
"$(jq -er '.paths.artifact' "$GSS_RECORD_DIR/b/operator-inputs.json")" \
"$GSS_RECORD_DIR/unapproved-key/public.pem" "$GSS_TRUSTED_FINGERPRINT" \
2>"$GSS_RECORD_DIR/b/unapproved-signer-rejection.txt"; then
echo 'unapproved signer was accepted' >&2; exit 1
fi
grep -F 'ContractError: public key does not match the trusted release fingerprint' \
"$GSS_RECORD_DIR/b/unapproved-signer-rejection.txt"
python3 "$GSS_DRIVER" inspect-runtime --receipt "$GSS_RECORD_DIR/b/runtime.json" \
--docker-context desktop-linux --journal "$GSS_RECORD_DIR/inspect-b-after-signer.jsonl"
Keep both tests local: neither rejected case invokes deploy. Retain the verifier errors, the proofs that B's runtime remained unchanged, and the second public key and fingerprint.
At this point, you can practise incident response or continue with the ordinary rollback. For response practice, follow Cancel work, close its credential, and restore a verified release. Leave B running and retain its release records and current operator identity; that procedure performs its own recovery and cleanup. Otherwise, continue below.
Roll back with a new signed decision
A rollback is a new release decision, even when it returns to retained bytes. Create a distinct rollback promotion over A; do not reuse initial-a as the rollback authorization:
promote "$GSS_RECORD_DIR/a/operator-inputs.json" rollback-a \
"$GSS_RECORD_DIR/a/rollback.json" "$GSS_RECORD_DIR/a/rollback.sig"
python3 "$GSS_DRIVER" inspect-runtime --receipt "$GSS_RECORD_DIR/b/runtime.json" \
--docker-context desktop-linux --journal "$GSS_RECORD_DIR/inspect-b.jsonl"
python3 "$GSS_DRIVER" remove-runtime --receipt "$GSS_RECORD_DIR/b/runtime.json" \
--docker-context desktop-linux --journal "$GSS_RECORD_DIR/remove-b.jsonl"
python3 "$GSS_DRIVER" deploy \
--operator-id "$GSS_RELEASE_OPERATOR_ID" \
--inputs "$GSS_RECORD_DIR/a/operator-inputs.json" \
--attestation "$GSS_RECORD_DIR/a/rollback.json" \
--signature "$GSS_RECORD_DIR/a/rollback.sig" \
--public-key "$GSS_RECORD_DIR/keys/release-public.pem" \
--trusted-fingerprint "$GSS_TRUSTED_FINGERPRINT" \
--release-id rollback-a --environment local-release-lab \
--receipt "$GSS_RECORD_DIR/a/rollback-runtime.json" \
--operator-token-env GITLAB_OPERATOR_TOKEN \
--docker-context desktop-linux --journal "$GSS_RECORD_DIR/deploy-rollback.jsonl"
The rollback starts a new container from the retained A bytes and creates a new deployment record. It doesn't rebuild A or rewrite B's deployment history.
Close the exercise
Finish by inspecting and removing the rollback runtime. Then stop the exact environment and require its stopped readback:
python3 "$GSS_DRIVER" inspect-runtime \
--receipt "$GSS_RECORD_DIR/a/rollback-runtime.json" \
--docker-context desktop-linux --journal "$GSS_RECORD_DIR/inspect-rollback.jsonl"
python3 "$GSS_DRIVER" remove-runtime \
--receipt "$GSS_RECORD_DIR/a/rollback-runtime.json" \
--docker-context desktop-linux --journal "$GSS_RECORD_DIR/remove-rollback.jsonl"
python3 "$GSS_DRIVER" stop-environment \
--project-id "$GSS_PROJECT_ID" --environment-id "$GSS_ENVIRONMENT_ID" \
--operator-id "$GSS_RELEASE_OPERATOR_ID" \
--environment local-release-lab \
--operator-token-env GITLAB_OPERATOR_TOKEN \
--journal "$GSS_RECORD_DIR/stop-environment.jsonl"
The stop command checks the held operator credential against the same recorded numeric ID before reading or changing the environment. A different user, rejected credential, or unknown transport result stops without attempting the environment mutation.
Revoke every temporary token through the identity or Owner interface that created it. Record each token ID and require an inactive or revoked readback; unsetting a shell variable doesn't close a credential. Remove the two temporary direct Developer memberships, then read the direct and effective membership again. Destroy the exercise private keys under the organization's key-destruction procedure, retaining public keys and fingerprints when the release record requires them.
Keep the source, build, signed approval, and deployment records together. An operator should be able to identify the artifact that ran and select a retained version for recovery. Protect the public keys and approval records from unauthorized changes, apply your retention policy to downloaded artifacts and logs, and record which temporary credentials and resources were removed.
GitLab deployment records help operators find releases, but they remain mutable metadata. Use the signed approval and the running artifact to decide whether the intended software reached the environment.
05 Respond: Practise stopping, investigating, and recovering
An intervention plan becomes useful when the people responsible have practised it under representative conditions. Before granting Act with guardrails authority, agree who can stop the workflow, revoke its credentials, suspend a release, preserve records, assess impact, approve recovery, and communicate with affected owners. Make sure they can reach the systems and people they'll need during an incident.
The following GitLab.com operations cover revoking an affected credential, canceling identified pipelines, preserving incident records, and restoring a reviewed repository or policy revision. Practise them in a private project before an incident so responders know what each operation does. During an incident, coordinate with the owners of connected systems, who will need to stop work already accepted outside GitLab and revoke external credentials. Deployment recovery follows later in this section.
| Standard example control | Implementation steps |
|---|---|
| Tested kill switch | Revoke access, cancel pipelines, and recover a running release. |
| Trace impact | Capture the affected work and preserve a time-ordered record. |
| Monitor consequential actions | Plan audit coverage, preserve credential and deployment activity, and configure audit event streaming where available. An incident snapshot alone doesn't provide continuous monitoring. |
Trace deployment and response records
Complete the audit plan and assign audit and response owners. Configure audit event streaming where available, plus credential and deployment activity, with retention and access controls.
Trace one ordinary deployment and one harmless response exercise across the records. Record missing events or identities as specific integration work. Coverage across systems can only be shown by following a real event.
Set GSS_GROUP_ID to the group's numeric ID to read recent group audit events:
glab api --hostname gitlab.com "groups/${GSS_GROUP_ID}/audit_events?per_page=20" | jq '[.[] | {created_at, event_name, author_name}]'
An incident-time API export can't substitute for monitoring that was never configured. Retain the configured streams and retention, plus one deployment and one response exercise traced across them.
Prepare the response session
Start from a trusted responder's glab session, separate from the suspected identity. Confirm the identity before setting the non-secret identifiers. Record the UTC incident window, the default branch SHA observed before intervention, and the known-good revision selected by the repository or policy owner:
glab api --hostname gitlab.com user | jq '{id, username}'
export GSS_APP_ID='<numeric-application-project-id>'
export GSS_GROUP_ID='<numeric-group-id>'
export GSS_DEFAULT_BRANCH='main'
export GSS_INCIDENT_AFTER='<incident-start-in-UTC-YYYY-MM-DDTHH:MM:SSZ>'
export GSS_INCIDENT_BEFORE='<incident-end-in-UTC-YYYY-MM-DDTHH:MM:SSZ>'
export GSS_KNOWN_GOOD_SHA='<full-reviewed-commit-sha>'
Retrieving all users' project audit events requires Maintainer or greater access. Token administration depends on the token type and namespace, so use an Owner or other identity permitted by the project access token or group access token documentation. Keep token values out of the incident record. Record the token's type, numeric ID, name, namespace, scopes, bot user and expiry instead.
Before changing state, capture the branch tip and active pipeline inventory. Save the complete responses in the approved incident-record location. The filtered output gives the operator a focused view:
glab api --hostname gitlab.com \
"projects/${GSS_APP_ID}/repository/branches/${GSS_DEFAULT_BRANCH}" \
| tee branch-before.json \
| jq '{name, protected, commit_id: .commit.id}'
glab api --hostname gitlab.com --paginate \
"projects/${GSS_APP_ID}/pipelines?per_page=100" \
| tee pipelines-before.json \
| jq --slurp '[.[][] | select(.status != "success" and .status != "failed" and
.status != "canceled" and .status != "skipped") |
{id, status, ref, sha, source, web_url}]'
glab api --hostname gitlab.com --paginate \
"projects/${GSS_APP_ID}/pipelines?source=parent_pipeline&per_page=100" \
| tee child-pipelines-before.json \
| jq --slurp '[.[][] | select(.status != "success" and .status != "failed" and
.status != "canceled" and .status != "skipped") |
{id, status, ref, sha, source, web_url}]'
Treat created, waiting_for_resource, preparing, waiting_for_callback, pending, running, canceling, manual, and scheduled as work that still needs a decision. The ordinary project listing omits child pipelines, so the second query explicitly selects same-project child pipelines with source=parent_pipeline. The pipelines API documents this behavior, the current statuses and pagination. Follow bridge and trigger relationships into downstream, policy, verifier, or deployment projects and repeat both queries there, because one project query can't establish that the whole workflow has stopped.
Revoke the affected access
Set the numeric token ID so the request targets exactly the token under investigation, then choose the endpoint matching its type:
Revoke a project or group access token
export GSS_TOKEN_ID='<numeric-token-id>'
# Project access token:
glab api --hostname gitlab.com --include --method DELETE \
"projects/${GSS_APP_ID}/access_tokens/${GSS_TOKEN_ID}"
# Group access token:
glab api --hostname gitlab.com --include --method DELETE \
"groups/${GSS_GROUP_ID}/access_tokens/${GSS_TOKEN_ID}"
Confirm token revocation
A successful revoke returns HTTP 204. Send only the request for the token's actual type. The project and group APIs describe these operations. Then read the exact token back from the corresponding collection and require the matching ID to report revoked: true and active: false:
glab api --hostname gitlab.com --paginate \
"projects/${GSS_APP_ID}/access_tokens?state=inactive&per_page=100" \
| jq --slurp --argjson id "$GSS_TOKEN_ID" \
'([.[][] | select(.id == $id) |
{id, name, user_id, scopes, expires_at, active, revoked}]) as $match |
if ($match | length) == 1 then $match
else error("expected exactly one inactive token with the selected ID") end'
For a group token, substitute groups/${GSS_GROUP_ID} for projects/${GSS_APP_ID} and retain state=inactive. The slurped filter searches every returned page. Require exactly one matching result with the expected ID. An empty result or 404 is unresolved until the responder checks the inactive filter, pagination, correct namespace, token type, permissions, retention behavior, and the original revocation response. A timeout during revocation has an unknown outcome: read the token state before retrying.
The metadata readback proves that GitLab considers that token inactive. It doesn't prove that a process has discarded a cached secret, that an already-running job has stopped, or that an external service has ended an established session. Revoke or rotate other credential types through their own owner-approved procedures, then verify each affected system separately.
For a group service account, use the owning group's token endpoint. Its personal access token is distinct from a group access token. In the trusted Owner session, set the service account's owning group, user ID and exact token ID, then revoke and read it back:
export GSS_SERVICE_ACCOUNT_GROUP_ID='<owning-group-id>'
export GSS_SERVICE_ACCOUNT_ID='<service-account-user-id>'
export GSS_TOKEN_ID='<affected-personal-access-token-id>'
GSS_SERVICE_TOKEN_BASE="groups/${GSS_SERVICE_ACCOUNT_GROUP_ID}/service_accounts/${GSS_SERVICE_ACCOUNT_ID}/personal_access_tokens"
glab api --hostname gitlab.com --include --method DELETE \
"${GSS_SERVICE_TOKEN_BASE}/${GSS_TOKEN_ID}"
glab api --hostname gitlab.com --paginate \
"${GSS_SERVICE_TOKEN_BASE}?state=inactive&per_page=100" \
| jq --slurp --exit-status --argjson id "$GSS_TOKEN_ID" \
--argjson user "$GSS_SERVICE_ACCOUNT_ID" \
'[.[][] | select(.id == $id)] |
if length == 1 and .[0].user_id == $user and
.[0].revoked == true and .[0].active == false
then .[0] | {id, user_id, name, scopes, expires_at, active, revoked}
else error("selected service-account token is not confirmed closed") end'
Require DELETE 204 and the matching inactive record. If the record is absent, keep the result unresolved until its namespace, permissions and retention are reconciled. GitLab documents both operations in the service accounts API. Close the affected credential before issuing a fresh recovery credential, and retain both numeric IDs to show that recovery didn't reuse the contained token.
Cancel identified pipelines and confirm their state
For each pipeline the response owner decides must stop, record its project, ID, ref, SHA, trigger identity and downstream relationships, then cancel it:
Cancel a pipeline and read back its state
export GSS_PIPELINE_ID='<numeric-pipeline-id>'
glab api --hostname gitlab.com --include --method POST \
"projects/${GSS_APP_ID}/pipelines/${GSS_PIPELINE_ID}/cancel"
glab api --hostname gitlab.com \
"projects/${GSS_APP_ID}/pipelines/${GSS_PIPELINE_ID}" \
| jq '{id, status, ref, sha, source, web_url, finished_at}'
Wait for the selected pipeline's readback to reach canceled. HTTP 200 from the cancel endpoint alone is insufficient because GitLab documents that the endpoint returns 200 regardless of the pipeline's state. This result applies only to that pipeline. Inventory same-project child pipelines explicitly, follow parent and downstream links, and repeat the decision and state check for each affected pipeline. If the endpoint returns 429, retain the Retry-After value and follow the documented rate limit. If a job has already delivered a package, deployment, message, or external change, canceling its pipeline doesn't undo that result.
Preserve a time-ordered record
Retrieve project audit events for the incident window. GitLab requires Maintainer or greater access to retrieve all users' events; a Developer sees only events based on their own actions. The API window is UTC:
Pull project audit events for a window
glab api --hostname gitlab.com --paginate \
"projects/${GSS_APP_ID}/audit_events?created_after=${GSS_INCIDENT_AFTER}&created_before=${GSS_INCIDENT_BEFORE}&per_page=100" \
| tee audit-events.json \
| jq --slurp '[.[][] | {id, created_at, author_id, author_name,
target_id, target_type, target_details, event_name, details}]'
The audit events API provides one part of the record rather than a complete execution history. Preserve relevant commits, merge requests, pipeline and job records, job logs and artifacts, deployments, approvals, policy revisions, and branch readbacks. Add identity-provider, cloud, agent, service, and external-system records where the workflow crossed those boundaries. Keep observed facts, inferences, missing data, and unresolved targets distinct. Preserve raw records under the organization's retention and access controls; deleting a GitLab pipeline also deletes related logs and artifacts, so deletion isn't a containment step.
Restore a reviewed repository or policy revision
First compare the selected known-good revision with the current default branch and review the returned commits and diffs:
glab api --hostname gitlab.com \
"projects/${GSS_APP_ID}/repository/compare?from=${GSS_KNOWN_GOOD_SHA}&to=${GSS_DEFAULT_BRANCH}&straight=true" \
| tee recovery-compare.json \
| jq '{compare_timeout, compare_same_ref, commits:
[.commits[] | {id, title, authored_date}], diffs:
[.diffs[] | {old_path, new_path, new_file, deleted_file, renamed_file,
collapsed, too_large, diff}]}'
The complete response remains in recovery-compare.json, while the terminal view includes each returned patch in diff. If compare_timeout is true, or a diff is collapsed or too large, the repository comparison API warns that the returned diff can be incomplete. Review repository history and narrower comparisons before approving recovery. Keep the protected default branch intact rather than resetting or force-pushing it.
Inspect the working clone before preparing recovery:
git rev-parse --show-toplevel
git remote get-url origin
git status --short
Confirm that the repository root and origin URL identify the intended project and that git status --short returns no entries. Stop if the clone is dirty or points to another repository. Then prepare a recovery branch from the current default branch. The subshell stops on the first failed command:
(
set -e
git fetch origin "$GSS_DEFAULT_BRANCH"
git fetch origin "$GSS_KNOWN_GOOD_SHA"
git cat-file -e "${GSS_KNOWN_GOOD_SHA}^{commit}"
git switch --create incident-recovery "origin/${GSS_DEFAULT_BRANCH}"
git restore --source "$GSS_KNOWN_GOOD_SHA" -- \
'<reviewed-application-or-policy-file>'
git diff --check
git diff -- '<reviewed-application-or-policy-file>'
git add '<reviewed-application-or-policy-file>'
git diff --cached --check
git diff --cached
)
The cat-file check needs to succeed before the repository or policy owner reviews the staged diff. If the server doesn't allow fetching an arbitrary SHA, fetch a branch or tag that contains the approved revision and repeat the reachability check. If any preparation command fails, don't run the commit block. After the human reviewer accepts the exact staged change, commit it and push the recovery branch for a merge request through the normal protected-branch path:
git commit -m 'Restore reviewed configuration after incident'
git push --set-upstream origin incident-recovery
Rehearse these commands in a private practice project before adopting them as an incident runbook.
If the unsafe change is a self-contained commit, the owner can instead revert that commit on the recovery branch. Don't restore a whole tree merely because one file is known bad. For a security policy project, preserve its separate ownership and require its configured review; restoring file bytes without effective policy propagation isn't recovery.
After review and merge, read the default branch and the pipelines for that exact revision:
export GSS_RECOVERY_SHA="$(
glab api --hostname gitlab.com \
"projects/${GSS_APP_ID}/repository/branches/${GSS_DEFAULT_BRANCH}" \
| jq --exit-status --raw-output '.commit.id'
)"
glab api --hostname gitlab.com --paginate \
"projects/${GSS_APP_ID}/pipelines?sha=${GSS_RECOVERY_SHA}&per_page=100" \
| jq --slurp '[.[][] | {id, status, ref, sha, source, web_url}]'
Confirm that the branch SHA, effective policy or configuration, successful security result, and intended application behavior match the recovery decision. If the merge didn't start the expected pipeline, diagnose its workflow rules, CI configuration, policy scope, runner eligibility, and project settings; an absent check can't support a recovery claim. Repeat the active-pipeline and token inventories, and retain the recovery merge request, exact source and target SHAs, pipeline and report IDs, and selected result fields. A clean scan supports recovery of the tested source and configuration; it doesn't establish that a deployed environment received that artifact.
If the recovery branch already exists, stop and either reconcile its exact SHA and contents or choose a fresh incident-specific name. A push denial can be the intended protected-branch behavior. In that case, open the merge request from an authorized source branch rather than weakening protection. A conflict, stale base, failed pipeline, missing report, or policy-propagation delay leaves recovery incomplete. Preserve the failed attempt, correct the cause, and repeat the selected state and security readbacks.
Choose rollback or forward recovery based on the state you can establish. Rolling back an application won't invalidate an exposed credential, and rotating a credential won't remove a malicious source change. A controls change that admitted unsafe work may require both restoring the rule and examining everything admitted while it was weak. Verify service health, the original security condition, deployed artifact identity, external sessions, and affected access before declaring full recovery.
Practise the response with the people who would perform it during an incident, using a harmless running pipeline and a short-lived credential. Confirm that they can stop current work, identify its effects, and restore a reviewed change. Include deployment suspension, external-system containment, and communications in the service's response plan, because the repository recovery commands can't perform those actions for you.
Recover a running release
For the local deployment example, follow Cancel work, close its credential, and restore a verified release while version B is still running, before the standalone rollback and cleanup. This walks through canceling current work, revoking the affected credential, stopping the current release, and deploying retained version A with a new approval and recovery credential.
Use the protected environment's allowed deployer to stop it. Administrative access alone doesn't establish that permission. After a cancellation, check the selected pipeline and job until they reach their terminal state. If a request times out, inspect the same IDs before retrying a write.
Verify the recovered artifact's identity and service health before resuming work. Check external clients, downstream services, active sessions and affected data with their owners as well. Stopping a GitLab pipeline or local container cannot recall output another system has already accepted.
Find, fix and learn: Improve controls and revisit autonomy
Retain a usable operating baseline
Keep the records someone needs to understand a scan or review without repeating the investigation. For each onboarded application, retain its scanner profiles and project scope, the source revision, the relevant pipeline and scanner jobs, and any findings assigned for action. Record the owner and review date for exclusions or unsupported parts of the application.
- In Secure > Security configuration > Scanners, open each scanner's details and record the project's profile source, status and last scan. Use Secure > Security inventory to review coverage across the group.
- In the project's Build > Pipelines, open the pipeline for the change or default-branch revision being reviewed. Keep its URL and SHA, each relevant scanner job's outcome, and the job log needed to explain any failure or exclusion.
- Where retention requires the original scanner output, use the job's artifact browser or Build > Artifacts to download it before expiry. Keep each job's files separately. The job artifacts documentation explains access and expiration; a pipeline link alone won't preserve expired files.
- Keep real findings linked to their triage decisions and remediation merge requests. For DAP, include the review threads or assessment, the flow session when available, and the human decision. After deployment, link the fix to the artifact and environment that actually received it.
Store these records in the organization's approved access-controlled location with the required retention and protection against alteration. Missing output needs investigation; a later successful run doesn't reconstruct an earlier missing result.
Maintain the service runbook
Keep the information an operator will need to change or recover the service alongside its operating procedures:
- The service owner, policy administrator, release operator and incident contacts.
- Where application, policy, runner and deployment configuration are maintained, and who can change them.
- How to find a release's source revision, pipeline, artifact digest, approval and current deployment.
- How credentials are issued, rotated and revoked, including the responsible owner and recovery access.
- How to stop current work, suspend a release and restore an approved artifact.
- Where logs and release records are retained, who can access them and when they expire.
- Known limitations, the person responsible for each, and changes that require another review.
Turn the local release result into production work with the release and platform owners. They need to define the production artifact store and immutable reference, build provenance source, signing identity and key custody, promotion rule, deployer identity, target readback and rollback source. Exercise that actual path with an approved artifact, then connect its source revision, pipeline, provenance, digest, release decision, deployment record and runtime identity in the runbook. Until those records agree, the local signing walkthrough remains a practice result rather than production provenance.
Likewise, assign the Audit and response owners to configure the streams, retention and access needed for consequential actions in GitLab and every connected system. Trace one ordinary deployment and one harmless response exercise across those records. Record missing events or identities as specific integration work; an incident-time API export can't substitute for monitoring that was never configured.
Use your existing service-management and incident processes for these records. After an incident, measure time to containment and time to verified remediation separately because they answer different questions. Containment ends when the affected activity has stopped across the systems in scope. Verified remediation requires the corrected software or configuration to be present there, with security, functional, and health checks complete. A revoked token or merged fix alone doesn't establish recovery.
Recheck the part that changed
Use the operating baseline to choose a focused check after a change:
| Change | Practical recheck | Decision to retain |
|---|---|---|
| Scanner profile, language, dependency input, exclusions or runner | Review the affected profile and scope, then inspect scanner activity on the next normal merge-request and default-branch pipelines. Investigate missing or failed coverage. | Whether the intended sources and dependencies still receive the required scans. |
| DAP flow, agent setup, trigger or triage preset | Review the effective permissions and runner, then inspect the next review or real-finding assessment and any proposed fix with its human reviewer. | Whether the flow runs within its intended scope and its output receives the required review. |
| Application or policy membership, custom role, branch rule or policy link | Repeat the relevant paired permission checks with the actual restricted identity and trusted administrator. Inspect inherited grants as well as direct ones. | Whether the same authority separation still holds. |
| Verification or admission mechanism | Repeat the permitted change and the prohibited path affected by the change, including the target readback. | Whether admission still depends on the required independent verification. |
| Credential, task runtime or response procedure | Exercise the affected stop/revocation path and confirm its observed reach before resuming delegated work. | Which activity was stopped and which systems still need a response. |
| Artifact, promotion or deployment path | Follow the accepted artifact through the changed path and verify its digest and health in the affected environments. | Which deployments are verified and which remain unresolved. |
Keep the earlier record and create a new one for the recheck. When a formerly prohibited action succeeds, record that result before restoring the control. A later successful check doesn't erase the interval when the control was ineffective. Where the detailed procedure is still being established, keep that outcome open instead of substituting a settings inspection for a behavior check.
Review the workflow's delegated authority
Services, permissions, delivery paths, threats, product behavior, and owners all change over time. Give each workflow a maintenance owner and a review rhythm that fits its impact. Recheck after a change to policy, identity, runner, build environment, registry, deployment path, agent, tool, integration, or affected service. Also recheck after a bypass, incident, failed recovery, unexplained result, or expired exception.
Product versions matter when they change a capability the workflow relies on, but a version difference alone doesn't require repeating every assessment. Focus the review on permissions, behavior, availability, and failure modes that changed, while retaining the earlier results that still apply.
Use operating results to decide whether autonomy should expand, remain in place, or narrow. Useful signals include missing or incomplete scans, time to review urgent findings, failed boundary tests, interventions, unexplained actions, expired exceptions, deployment gaps, and recovery exercises. Read counts in context: a falling vulnerability total may reflect fixes, dismissals, or reduced scan coverage.
Keep a short decision record for the workflow. For the Foundation and each stage, link the observed result, record whether the outcome is demonstrated, and identify any gap and its owner. Then name the autonomy level those results support. A stage that isn't required for the chosen level can remain pending; a required stage can't be marked complete merely because a product feature is configured.
When considering an authority increase, compare the recorded results with the Standard's prerequisites. Exercise the additional permissions, failure cases, volume limits, and affected-system limits before enabling them. Success in preparing code changes doesn't establish permission to alter security policy, release to production, or revoke credentials.
A waived check, successful prohibited action, or failed intervention changes that decision. Restrict the workflow to authority whose prerequisites remain demonstrated. If the Foundation or Authorize is unproven, even Suggest hasn't met the Standard's prerequisites. Assign the gap, correct the policy or implementation, and repeat the relevant checks before restoring delegated authority.
Apply improvements one workflow or environment at a time. Keep the official Standard's Foundation and five stages as the outcomes being pursued, while letting the service, risk, and operating context determine the practical controls. The result should remain concrete: a clear owner, an authorized task, contained reach, trustworthy verification, the same approved software in release, and a response path that works when needed.
Retire temporary resources
When you no longer need the examples, remove the resources created only for them while keeping the service's intended configuration and existing access in place. If a request had an uncertain result, inspect the affected resource before retrying it.
- Stop further activity. Let the selected job or pipeline reach a known terminal state, or cancel only its recorded numeric ID. Preserve its source SHA, ref, status, job list, and trace before removing a branch. Follow Practise stopping, investigating, and recovering for active work.
- Close temporary credentials first. Revoke each exact personal, project, or group access token created for the practice. Read it back as revoked and inactive; a successful local logout or a deleted environment variable doesn't establish closure. Never print or retain the secret value.
- Remove temporary access and execution state. Delete only the recorded temporary branch after its current head equals the recorded exercise SHA. Remove only memberships, job-token allowlist entries, variables, or runner assignments introduced by the practice, then read the affected direct and effective state again. Use Diagnose and recover containment for the job-token and runner boundary.
- Restore trusted configuration deliberately. Compare the current policy, branch rule, CI configuration, or repository file with the recorded starting revision. Restore only the reviewed change through its normal protected path, then read the effective configuration back. Use Diagnose and recover policy authority for policy links and ownership, and Restore a reviewed repository or policy revision for file recovery. Keep the protection in place throughout cleanup.
- Check the affected result again. Confirm the intended default-branch SHA, policy relationship, allowlists, and file digests. Where the practice reached a runtime, also check the selected environment's current deployment, artifact identity, health, and required behavior. A restored repository alone doesn't establish a restored service.
- Preserve operating records. Keep the configuration revisions, release approvals and relevant pipeline, deployment and incident records under your retention policy. Retain a usable operating baseline explains which profile, pipeline, finding and review records to keep.
- Assign retained resources. If a practice project, runner, artifact, or environment remains for review, keep it private where applicable and record its owner and review or deletion date. A review date isn't an automatic deletion promise. Delete it later only after preserving required records and verifying its exact identity.
Use Change or remove a scanner profile for temporary scanning configuration and Roll back with a new signed decision for the local application. Confirm that temporary resources are gone and retained services are in their intended state. Work with the responsible owners to resolve any remaining external credentials, sessions, deployments, or affected data.
Control reference
The following controls provide the same Understand, Implement and Prove material as the interactive guide. The chapters above contain the connected procedures and their prerequisites.
F.1 Policy
Owner: Policy administrator
Coverage: Partial
Summary: Application identity can't commit, merge or unlink policy
Understand
What it protects
The people responsible for security policy manage it without giving application authors the same authority. Policy changes arrive only through a reviewed merge request in a separate, protected project.
Pass when
The policy project is linked at the application subgroup, its default branch accepts changes only through merge requests, and the application identity's attempts to commit, merge, assign or unassign the link are each refused with an explicit permission denial while the Owner's identical requests succeed.
What GitLab covers and what stays yours
GitLab supplies security policy projects, protected branches and permission-checked link mutations. Writing the actual rules, choosing their scope and checking enforcement on real application changes stays yours. Linking a policy project doesn't enable a policy by itself.
Considerations
- An enabled policy and checks on actual application changes are still needed to enforce a merge requirement.
- GitLab combines matching branch rules and generally applies the most permissive result, so one restrictive entry doesn't establish effective permissions.
- A missing button in the UI doesn't confirm that the operation is denied. Check the API response.
GitLab features
Security policy projects
| Tier | Maturity | Deployments |
|---|---|---|
| Ultimate | GA | GitLab.com, Self-Managed, Dedicated |
Linking needs the Owner role or a custom role with manage_security_policy_link. A link on a group applies to the projects below it.
Protected branches and branch rules
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
Set Allowed to push and merge explicitly to No one. Leaving it unconfigured isn't the same.
Project membership sources
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
Direct, inherited, invited-group and shared-project grants combine. Changing the direct role won't remove an ancestor grant.
Merge requests API (exact-SHA merge)
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
Passing sha makes the merge fail if the source branch moved.
Implement
Steps
Create the practice project layout
Create a private subgroup security-practice with a private applications subgroup holding practice-application, and a separate private project security-policy directly under security-practice. Inspect the Source of every membership at both subgroups and the parent.
Restrict the application test identity
Add the application test identity to security-policy with the Reporter role. Stop if it is an Owner of a governing group, a Maintainer or Developer of security-policy, or holds a custom role with manage_security_policy_link.
Protect the policy default branch
In security-policy, open Settings > Repository > Branch rules for the default branch. Set Allowed to merge to Maintainers, Allowed to push and merge to No one, leave force push off, and tighten any other rule that also matches the branch.
Link the subgroup policy project
As the trusted Owner, assign the policy project to the applications subgroup with the securityPolicyProjectAssign mutation. Read back both links: the subgroup names the policy project and the application's direct link stays null.
Enable and test a scoped policy
Create a narrowly scoped policy through the policy editor, review its generated merge request, merge it through the protected branch, and confirm its enabled scope. Check one allowed and one rejected application change before relying on it.
Confirm inherited policy and permissions
Open Secure > Policies on applications and practice-application. Both should name Practice - security policy project. Repeat the permission checks after any change to group membership or custom roles.
Commands
Confirm identity and the policy project in each session
export GSS_APP_PATH='<your-group>/security-practice/applications/practice-application'
export GSS_POLICY_ID='<numeric-policy-project-id>'
export GSS_SUBGROUP_PATH='<your-group>/security-practice/applications'
glab api --hostname gitlab.com user | jq '{id, username}'
glab api --hostname gitlab.com "projects/${GSS_POLICY_ID}" \
| jq '{id, path_with_namespace, default_branch}'
Assign the policy project to the subgroup (Owner)
export GSS_ASSIGN_POLICY='mutation($path:String!,$policy:ProjectID!){securityPolicyProjectAssign(input:{fullPath:$path,securityPolicyProjectId:$policy}){errors}}'
export GSS_POLICY_GID="gid://gitlab/Project/${GSS_POLICY_ID}"
glab api --hostname gitlab.com --include graphql \
--raw-field query="$GSS_ASSIGN_POLICY" \
--raw-field path="$GSS_SUBGROUP_PATH" \
--raw-field policy="$GSS_POLICY_GID"
Prove
What proves it
Paired requests: the same harmless commit, merge and link change succeed for the Owner and fail with a permission denial for the application identity, and the default branch and links read back unchanged after each denial.
Review cadence
On change to membership, custom roles, branch rules or the policy link
API read checks
F.1-policy-branch-rule
Reads
The policy default branch's rules in Settings > Repository > Branch rules, including every rule whose exact name or wildcard matches it.
Passes when
Allowed to merge is Maintainers, Allowed to push and merge is No one, force push is off, and no other matching rule restores broader access.
F.1-subgroup-link-holds
Reads
The GraphQL securityPolicyProject field on the applications group and on practice-application, queried as the Owner.
Passes when
The subgroup names GSS_POLICY_GID and the application's direct link is null.
Behaviour checks
F.1-app-identity-commit-denied
Does
Post the same harmless commit (a new policy-ownership-check.txt on a fresh branch, no policy YAML) first as the application identity, then as the Owner.
Expect
The application request gets an explicit permission denial and the branch returns 404. The Owner's identical request returns 201.
F.1-app-identity-merge-denied
Does
With the merge request at detailed_merge_status: mergeable, attempt the exact-SHA merge as the application identity, then as the Owner.
Expect
The application merge is denied, the request stays open with merge_commit_sha: null, and the default branch is unchanged. The Owner's merge returns 200 and state: merged.
F.1-app-identity-unassign-denied
Does
Run securityPolicyProjectUnassign on the subgroup as the application identity.
Expect
HTTP succeeds with mutation: null and one top-level permission error at ["securityPolicyProjectUnassign"]. The subgroup link still names the policy project.
Manual checks
F.1-policy-rules-enabled
Produce
The enabled policy, its merge request and its scope, plus one allowed and one rejected application change.
Why manual
The link proves who administers policy, not what the policy enforces.
Command
glab api --hostname gitlab.com "projects/${GSS_POLICY_ID}/repository/branches/main" | jq '{name, commit_id: .commit.id}'
Evidence to retain
/tmp/policy-authority-commit.json
F.2 Audit
Owner: Audit owner
Coverage: Partial
Summary: One recent task traced from request to deployment
Understand
What it protects
The Standard's target is an immutable record connecting task to deployment, including agent and model identities, prompts, reasoning steps, tool calls and actions. Missing coverage is made explicit and limits the workflow's authority.
Pass when
One recent task is traced through GitLab and external records that can actually be retrieved, carrying the task, actor, source revision, pipeline or flow session, artifact and deployment identifiers. Each missing record has an owner and a system that will produce it.
What GitLab covers and what stays yours
GitLab project history, pipelines, deployments, approvals and audit events supply parts of the account. They don't automatically expose an agent's internal execution or activity in connected systems. Retention, alteration protection and external records are yours.
Considerations
- A boundary log can improve attribution; it doesn't fill in execution details that were never captured.
- Audit event coverage, retention and streaming destinations vary by tier and offering.
- Treat missing required coverage as an Audit gap when deciding autonomy.
GitLab features
Audit events
| Tier | Maturity | Deployments |
|---|---|---|
| Premium | GA | GitLab.com, Self-Managed, Dedicated |
Retrieving all users' project events needs Maintainer or above; a Developer sees only their own.
Audit event streaming
| Tier | Maturity | Deployments |
|---|---|---|
| Ultimate | GA | GitLab.com, Self-Managed, Dedicated |
An incident-time export can't substitute for streaming that was never configured.
Job artifacts
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
Download scanner output before it expires. A pipeline link alone won't preserve expired files.
Implement
Steps
Inventory records for a recent action
Work backward from a recent action. List the records you can retrieve, how they connect, and who could alter or delete them.
Inspect agent and external records
Check what your agent runtime and external services actually provide: agent and model identity, prompts, tool calls and actions.
Assign missing records and retention
Assign an owner to each missing record and name the system that can produce it. Configure retention and access there.
Trace one task across systems
Trace one recent task through GitLab and external records. Carry the task, actor, source revision, pipeline or flow session, artifact and deployment identifiers into the delivery-path record.
Protect retained records and limit authority
Store retained records in an approved access-controlled location, protected against alteration. If records can't yet be connected, keep Audit open and limit the workflow's authority.
Commands
Pull project audit events for a window
Pull project audit events for a window
Prove
What proves it
A written trace of one recent task that links every identifier from request to deployment, with each gap named, owned and assigned to a producing system.
Review cadence
Before raising autonomy, and on change to the agent runtime or connected systems
API read checks
F.2-audit-events-readable
Reads
Project audit events for a recent window, as a Maintainer or above.
Passes when
Events return for the window and include the actors and targets the trace expects.
Manual checks
F.2-one-task-traced
Produce
A trace of one recent task across GitLab and external records, with the task, actor, revision, pipeline or flow session, artifact and deployment identifiers.
Why manual
No single system holds the whole account; someone has to connect the records and name what's missing.
F.2-gap-owners
Produce
A list of missing records, each with an owner, a producing system and its retention.
Why manual
A gap with no owner stays open indefinitely.
Command
glab api --hostname gitlab.com --paginate "projects/${GSS_APP_ID}/audit_events?per_page=100" | jq --slurp 'add | length'
Evidence to retain
audit-events.json
F.3 Ownership
Owner: Service owner
Coverage: Your process
Summary: Named owners, delivery path recorded, runbook current
Understand
What it protects
Every role in the workflow has a named, accountable person, including the authority to stop it. These responsibilities apply to agents and service accounts as well as people.
Pass when
The service owner, policy administrator, runner owner, security reviewer and release operator are named, with backups and the person who can stop the workflow. Authorship and independent approval have separate decision makers. The delivery path and service runbook are recorded and current.
What GitLab covers and what stays yours
GitLab records memberships and roles, but who owns an outcome is an organizational decision. Recording the path, the owners and the runbook is your process.
Considerations
- One person may fill several operational roles, but authorship and approval of that author's change need separate decision makers.
- Success in one workflow doesn't justify more autonomy in another. Keep their assessments separate.
GitLab features
Project membership sources
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
Inspect the Source column for inherited and shared grants at every level.
Subgroups
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
A private subgroup still inherits access and settings from its ancestors.
Implement
Steps
Choose a representative service
Select one real service whose owners can identify its normal source, pipeline, artifact and deployment path. Use it as the thread through the assessment.
Trace the actual delivery path
Follow a recent instance of the work, not the intended architecture. Trace request, source, build, verification, artifact storage, deployment and operation, including human, service and agent identities and every crossing into another project, runner, registry, cloud account or third-party service.
Record delegated authority and gaps
Record what is delegated, what the workflow can reach, who owns the outcome, what protects the path today and what remains uncertain. Give every missing item an owner.
Assign operational and response owners
Name the service owner, policy administrator, runner owner, security reviewer and release operator before assigning permissions. Record who takes over when an owner is unavailable and who can stop the workflow.
Maintain the service runbook
Maintain the service runbook: owners and contacts, where each configuration lives and who can change it, how to find a release's revision, pipeline, digest and approval, how credentials are issued and revoked, how to stop and restore, where records live, and known limitations.
Prove
What proves it
A delivery-path record and service runbook that another operator could use to find the owners, the running artifact and the stop path without asking anyone.
Review cadence
On change to owners, the delivery path or the affected service
API read checks
F.3-effective-members
Reads
Direct and effective members of the application and policy projects, and their governing groups.
Passes when
Every grant matches the recorded intended access; no identity holds authority the record doesn't name.
Manual checks
F.3-delivery-path-recorded
Produce
The starting record: delegated work, reach, outcome owners, current protections and open questions, with an owner for each gap.
Why manual
The actual path comes from following a recent change, not from a settings export.
F.3-runbook-current
Produce
The service runbook with owners, configuration locations, release lookup, credential lifecycle, stop and restore procedures, record locations and known limitations.
Why manual
An operator needs it during an incident, when the people who know may be unavailable.
Command
glab api --hostname gitlab.com --paginate "projects/${GSS_APP_ID}/members/all?per_page=100" | jq --slurp '[.[][] | {username, access_level}]'
1.1 Agent inventory
Owner: Agent or flow owner
Coverage: Partial
Summary: Every enabled agent and flow has a named human owner
Understand
What it protects
You know every agent, flow, integration and service account that can act in the workflow, and each one has a named human owner.
Pass when
The inventory lists every enabled agent and flow from AI > Agents and AI > Flows at group and project level, the workflows that use them and a named owner. Custom items record their selected version and who can update it. Integrations and service accounts outside the catalog are included.
What GitLab covers and what stays yours
GitLab shows enabled agents and flows and their definitions in the AI Catalog. Integrations and service accounts that aren't in the catalog, and the owner of each entry, are yours to add.
Considerations
- GitLab-managed foundational agents and flows don't use the same version-pinning model as custom items.
GitLab features
AI Catalog
| Tier | Maturity | Deployments |
|---|---|---|
| Premium | GA | GitLab.com, Self-Managed, Dedicated |
Inspect each item's definition and managing project. Record the selected version for custom items.
Service accounts
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
Include service accounts that act without a catalog entry.
Implement
Steps
Inventory enabled agents and flows
Open the group's and project's AI > Agents and AI > Flows pages. Record which items are enabled, the workflows that use them and the person responsible for each.
Inspect definitions, versions and ownership
Use the AI Catalog to inspect each definition and managing project. For custom items, record the selected version and who can update it.
Include integrations and service accounts
Add integrations and service accounts that aren't represented in the catalog to the same inventory.
Assign owners or disable entries
Give every entry without an owner one, or disable it.
Prove
What proves it
An inventory that matches what GitLab shows as enabled, with no entry lacking a named owner.
Review cadence
On change to an agent, flow, trigger or integration
API read checks
1.1-service-accounts-listed
Reads
The group's service accounts.
Passes when
Every service account appears in the inventory with an owner.
Manual checks
1.1-inventory-owned
Produce
The inventory reconciled against AI > Agents and AI > Flows at group and project level.
Why manual
Some enabled toggles and external integrations have no single readable API.
Command
Reconcile service accounts with the inventory
1.2 Agent identity
Owner: Workflow owner
Coverage: Partial
Summary: Each automated action traces to its human initiator
Understand
What it protects
Another operator can identify the human who started an agent and the identity that executed it, and the agent can reach no more than both of them are allowed to.
Pass when
For a runner-executed DAP flow, both the initiating user's and the service account's memberships are inspected, and the flow session and resulting commit or merge request are recorded so the human initiator and the automated action can be identified. Agentic Chat authorization is inspected separately.
What GitLab covers and what stays yours
Composite identity limits runner-executed flows to the intersection of the initiator's and service account's permissions. Agentic Chat in the UI and IDE doesn't use this mechanism, and keeping the initiator separate from the approver is your process.
Considerations
- A service account's involvement doesn't make a change independently reviewed. Keep the initiating author separate from the human who approves the result.
- Inspect other projects both identities can access, not only the target.
GitLab features
Composite identity
| Tier | Maturity | Deployments |
|---|---|---|
| Premium | GA | GitLab.com, Self-Managed, Dedicated |
Applies to runner-executed DAP flows. Agentic Chat uses a different authorization model.
Service accounts
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
Implement
Steps
Inspect flow identity memberships
For each runner-executed flow, inspect the initiating user's and the service account's memberships, including other projects they can both access.
Connect flow sessions to changes
Record the flow session and the resulting commit or merge request so another operator can identify the human initiator and the automated action.
Inspect Agentic Chat execution credentials
For Agentic Chat in the UI and IDE, inspect where its tools execute and which credentials they use. Don't assume composite identity applies.
Confirm independent change approval
Confirm that the person who approves an agent's change is not the person who initiated it.
Prove
What proves it
A flow session linked to its initiator, executing identity and resulting change, with an approver who is neither.
Review cadence
On change to a flow, its service account or the initiator's memberships
API read checks
1.2-mr-author-recorded
Reads
The agent-authored merge request's author and commit.
Passes when
The executing identity is recorded and differs from the approver.
Manual checks
1.2-flow-session-traced
Produce
One flow session linked to its initiating user, service account and resulting commit or merge request.
Why manual
The link between session and human isn't a single API field.
Command
Read the merge request author and commit
1.6 Secrets management
Owner: Credential owner
Coverage: Partial
Summary: Every credential has an owner, scope, expiry and revocation path
Understand
What it protects
Each task receives only the access its next action needs, from an approved store, and every credential can be found and revoked when access ends.
Pass when
Every credential the workflow uses is recorded with its issuer, owner, purpose, reachable systems, expiry and revocation procedure, without its value. Release and policy-administration credentials sit outside application-controlled jobs, and revocation has been read back as inactive.
What GitLab covers and what stays yours
GitLab provides Secrets Manager, external secret providers and token revocation APIs. Choosing the store, scoping each credential and deciding who can request it is yours.
Considerations
- Masked values can still be disclosed by malicious job code. Protected variables limit availability to protected refs; they don't protect a secret from untrusted code allowed to run there.
- Unsetting a shell variable doesn't close a credential. Revoke it and read it back.
GitLab features
GitLab Secrets Manager
| Tier | Maturity | Deployments |
|---|---|---|
| Premium | GA | GitLab.com, Self-Managed |
External secret providers
| Tier | Maturity | Deployments |
|---|---|---|
| Premium | GA | GitLab.com, Self-Managed, Dedicated |
Choose the integration for the actual executor and review who can request each secret.
Masked, hidden and protected CI/CD variables
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
Project Maintainers administer project variables.
Service account token revocation
| Tier | Maturity | Deployments |
|---|---|---|
| Premium | GA | GitLab.com, Self-Managed, Dedicated |
A service account's personal access token is distinct from a group access token.
Implement
Steps
Record credential ownership and lifecycle
For each credential, record issuer, owner, purpose, reachable systems, expiry and revocation procedure. Never record the value.
Scope credentials to the task
Give a task only the access its next action needs. Keep release and policy-administration credentials out of application-controlled jobs.
Review access to the approved store
Use the organization's approved store, such as Secrets Manager or an external provider, and review who can request each secret before supplying it to a flow.
Inspect inherited CI/CD variables
Review Settings > CI/CD > Variables in the project and its ancestors. Record key, source, scope, type, Protected flag and visibility, not values. Don't use the variables API in a shared recording; it returns values.
Check the credential trust boundary
Keep a consequential credential out of the application project unless the identity controlling CI configuration, ref eligibility and runner execution is inside that credential's trust boundary.
Revoke the exact token and verify
When access ends, revoke the exact token and require a readback showing revoked: true and active: false.
Commands
Revoke a project or group access token
Revoke a project or group access token
Prove
What proves it
A credential register with no values, plus a revocation readback for each credential retired during the exercise.
Review cadence
On change to a credential, task runtime or response procedure
API read checks
1.6-token-revoked
Reads
The inactive token collection for the namespace, filtered to the exact token ID.
Passes when
Exactly one match with revoked: true and active: false.
Manual checks
1.6-credential-register
Produce
Issuer, owner, purpose, reachable systems, expiry and revocation procedure for every credential the workflow uses.
Why manual
Credentials outside GitLab don't appear in any GitLab API.
Command
glab api --hostname gitlab.com --paginate "projects/${GSS_APP_ID}/access_tokens?state=inactive&per_page=100" | jq --slurp '[.[][] | {id, name, active, revoked}]'
2.1 Isolated execution
Owner: Runner owner
Coverage: Partial
Summary: Permitted task works; prohibited access fails for the intended reason
Understand
What it protects
The task runs where an application Maintainer can't replace the controls, with only the filesystem, privileges, network routes and resources it needs.
Pass when
The workflow's jobs run only on an eligible runner administered outside the application project. A permitted job checks out and uploads its artifact, prohibited network connections are denied, and inspection of the actual runner and containers matches the intended configuration.
What GitLab covers and what stays yours
GitLab lets you separate runner administration, restrict pipeline variables and limit job-token access. The executor, kernel separation, egress limits and secret delivery are your platform's to supply and test.
Considerations
- Containers share the host kernel. These settings aren't suitable isolation for arbitrary hostile code or production secrets.
- A tag selects eligible runners; it doesn't prove which runner executed the job.
- GitLab-hosted runners are disposable but allow public outbound traffic, passwordless
sudoand privileged Docker-in-Docker.
GitLab features
Runner scope
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
An application Maintainer can create, edit, pause and remove project runners. Treat those as application-controlled.
GitLab-hosted runners
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com |
A fresh VM per job, deleted after. Outbound internet is permitted.
Restrict pipeline variables
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
Once set to no one allowed, only an Owner can change it.
CI/CD job token allowlist
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
Controls GitLab resources only. It isn't a network allowlist or egress control.
Runner security
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
Treat Docker socket access as trusted host authority.
Implement
Steps
Inventory project settings and offered runners
Record the project settings and every runner GitLab can offer the project. Reconcile the API list with Settings > CI/CD > Runners and record each runner's owner, scope, executor, tags, protected setting and untagged-job setting.
Restrict pipeline variable overrides
In Settings > CI/CD > Variables, set Minimum role to use pipeline variables to no one allowed unless the workflow has a reviewed need. Read back ci_pipeline_variables_minimum_override_role: no_one_allowed.
Limit job token access
In Settings > CI/CD > Job token permissions, keep the allowlist on, remove every entry the workflow doesn't need, and leave Allow Git push requests to the repository off. Repeat in every private target project, including security-policy.
Confine a task without network access
For work that needs no credentials or network, follow the isolated-task procedure: read-only root and mounts, non-root user, dropped capabilities, no-new-privileges, no network, a small tmpfs workspace and resource limits.
Configure a dedicated GitLab runner
For a GitLab job, follow the dedicated-runner procedure: a paused group runner administered by the platform owner, pinned images, no pulls or services, non-root build, internal Docker network and an HTTPS proxy to GitLab only.
Bind required jobs to trusted runners
Before adopting the runner for the selected application, bind its required jobs to the trusted runner and remove or constrain alternates. Include scheduled, triggered, parent-child and policy pipelines, and the actual DAP execution path.
Commands
Record project settings and offered runners
Record project settings and offered runners
Read back job-token scope and allowlists
Read back job-token scope and allowlists
Prove
What proves it
A permitted job that completes on the intended runner, paired with denied cross-project and network access whose cause you've isolated, plus readbacks of the runner, variables and job-token settings.
Review cadence
On change to a runner, task runtime, allowlist or variable
API read checks
2.1-pipeline-variables-closed
Reads
ci_pipeline_variables_minimum_override_role on the application project.
Passes when
no_one_allowed, unless a reviewed need is recorded.
2.1-job-token-scope
Reads
Inbound job-token scope and the project and group allowlists, paginated, on the application and each target.
Passes when
inbound_enabled: true and every entry is needed. The target's lists exclude the application and its ancestors.
Behaviour checks
2.1-job-token-cross-project-denied
Does
Run a job that reads its own README.md and a private target's README.md with CI_JOB_TOKEN, after confirming the application identity can read the target directly.
Expect
The same-project read returns 200 with the Owner's digest. The cross-project read returns 403 or 404, and the target's SHA and digest are unchanged.
2.1-local-task-confined
Does
Run the reviewed task container with the isolated-task procedure and inspect its configuration as well as its output.
Expect
The useful task completes, external access fails for the intended network reason, and writes stay inside the temporary workspace.
2.1-runner-egress-denied
Does
Run the dedicated-runner job, then inspect its actual runner and containers.
Expect
Checkout and artifact upload succeed through the proxy; prohibited connections are denied.
Manual checks
2.1-runner-ownership
Produce
The runner's owner, scope, executor, tags, eligible projects and operating boundary.
Why manual
Who administers a runner decides whether the boundary survives an untrusted Maintainer.
Command
glab api --hostname gitlab.com "projects/${GSS_APP_ID}" | jq '{ci_pipeline_variables_minimum_override_role, ci_push_repository_for_job_token_allowed}'
Evidence to retain
allowed.txtdenied.txt
2.2 Sanctioned tools and access paths
Owner: Agent or flow owner
Coverage: Partial
Summary: One permitted tool action works and a prohibited one is refused
Understand
What it protects
The agent can use only the tools, connections and GitLab access paths the task needs, and those limits hold on the path where the work actually runs.
Pass when
The tools and external connections the agent can use are inventoried and configured on its actual execution path. One permitted tool action and one representative prohibited action have been run and recorded, and job-token access is limited to the projects the workflow requires.
What GitLab covers and what stays yours
Agent tool governance and the job-token allowlist let you restrict tools and GitLab access. Whether a restriction holds in a given client or background flow, and what to do when it can't, is yours to test.
Considerations
- An interactive approval prompt can't control an unattended action unless the execution path supports that decision.
- If the product or client can't enforce the restriction, remove the tool from the delegated path, wrap it in an enforceable control, or keep authority below the level that needs it.
GitLab features
Agent tool governance
| Tier | Maturity | Deployments |
|---|---|---|
| Premium | Beta | GitLab.com, Self-Managed, Dedicated |
Check supported clients and background-flow behavior before relying on it.
Flow execution environment
| Tier | Maturity | Deployments |
|---|---|---|
| Premium | GA | GitLab.com, Self-Managed, Dedicated |
A dedicated runner used for the example job isn't automatically the executor for every enabled flow.
CI/CD job token allowlist
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
Prefer a project entry. A group entry includes future projects anywhere below it.
Implement
Steps
Inventory tools and external connections
Inventory the tools and external connections the agent can use, and the flow's execution environment and project setup.
Configure supported agent tool permissions
Configure permissions with agent tool governance where available, and examine its supported clients and background-flow behavior.
Restrict access on target projects
Limit job-token access on the target projects, not only the application. The target's allowlist controls inbound access, and the application Maintainer can change the application's own list.
Test permitted and prohibited tool actions
Run one permitted tool action and one representative prohibited action on the actual path, and record the effective settings.
Prove
What proves it
Effective tool and access settings on the real execution path, with a permitted action that works and a prohibited one that's refused.
Review cadence
On change to a flow, agent setup, trigger or tool
API read checks
2.2-allowlist-minimal
Reads
The job-token project and group allowlists on each target.
Passes when
Only entries the workflow requires remain.
Behaviour checks
2.2-prohibited-tool-refused
Does
Attempt a tool action outside the sanctioned set on the agent's actual execution path.
Expect
The action is refused by an enforced control, not by a broken runner or missing file.
Manual checks
2.2-tool-inventory
Produce
The tools and connections each agent can use, and the restriction applied to each.
Why manual
Some clients and external tools have no readable setting.
Command
glab api --hostname gitlab.com --paginate "projects/${GSS_APP_ID}/job_token_scope/allowlist?per_page=100" | jq --slurp '[.[][] | .path_with_namespace]'
2.4 Trusted dependencies
Owner: Dependency owner
Coverage: Your process
Summary: Builds pull only from permitted registries and mirrors
Understand
What it protects
Packages and images come only from sources you control before they reach the build. Finding vulnerable dependencies later is a separate job.
Pass when
Permitted registries, mirrors, image references and outbound destinations are configured on the real build path. One permitted dependency fetch succeeds and a representative prohibited fetch fails.
What GitLab covers and what stays yours
Controlling what enters a build depends on your registries, mirrors and network routing. Dependency scanning reports vulnerable dependencies; enabling it doesn't install a dependency firewall or enforce registry routing.
Considerations
- Enabling SCA doesn't control what enters the build.
- A pinned image digest doesn't receive newer security fixes automatically. Review a replacement before changing it.
GitLab features
Dependency scanning (SBOM-based analyzer)
| Tier | Maturity | Deployments |
|---|---|---|
| Ultimate | GA | GitLab.com, Self-Managed, Dedicated |
Reports vulnerable dependencies. It doesn't block fetches.
Implement
Steps
Review dependency sources and destinations
With the runner owner, review package registries, image registries, mirrors and outbound destinations.
Inspect manifests, lockfiles and permissions
Check dependency manifests and lockfiles, the permitted registry endpoints, and who can change them.
Configure approved sources and pinned images
Configure permitted registries, mirrors, image references and destinations on the real build path. Pin images by digest.
Test permitted and prohibited dependency fetches
Run one permitted dependency fetch and one representative prohibited fetch, and record the effective settings.
Commands
Pull and check the digest-pinned runtime image
export GSS_CONTEXT='desktop-linux'
export GSS_IMAGE='python@sha256:f77ac9e44ae96ef2c90b8053ea08c31f8be030f824196b0ae4db6d462c84e51f'
docker --context "$GSS_CONTEXT" pull --platform linux/arm64 "$GSS_IMAGE"
docker --context "$GSS_CONTEXT" image inspect "$GSS_IMAGE" | jq -e \
--arg image "$GSS_IMAGE" '
length == 1 and .[0].Os == "linux" and .[0].Architecture == "arm64" and
(.[0].RepoDigests | index($image)) != null'
Prove
What proves it
Effective registry and destination settings on the build path, with a permitted fetch that works and a prohibited fetch that fails.
Review cadence
On change to a dependency input, registry or runner
Behaviour checks
2.4-public-fetch-denied
Does
From the build path, fetch a package from a registry outside the permitted set.
Expect
The fetch fails because of the routing or registry control, while a permitted fetch succeeds.
Manual checks
2.4-sources-recorded
Produce
Permitted registries, mirrors, image references and outbound destinations, and who can change them.
Why manual
These settings live in your registries and network, outside GitLab.
Command
docker --context desktop-linux image inspect "$GSS_IMAGE" | jq '.[0].RepoDigests'
3.3 Policy in the execution path
Owner: Security reviewer
Coverage: Partial
Summary: Tests and scanners run for the same SHA; required checks reach admission
Understand
What it protects
Required scans and tests run on the change being reviewed, and their results feed a merge decision that the change's author can't route around.
Pass when
SAST, dependency scanning and secret detection profiles are attached to the selected project. For an ordinary merge request and its resulting default-branch revision, the application test and each scanner job are present and individually successful with reports. Required checks are connected to the admission decision.
What GitLab covers and what stays yours
Security configuration profiles enable scanners without editing each .gitlab-ci.yml, and policies can apply them centrally. Connecting results to a merge gate an untrusted Maintainer can't bypass isn't supplied by profiles or DAP flows alone.
Considerations
- Profile scanner jobs can use
allow_failure: true, so the pipeline can stay green when a scanner fails. Inspect each job and report. - Profiles aren't inherited through the group hierarchy. Apply them explicitly to future projects.
- A clean result doesn't prove that unsupported languages, other branches or the deployed artifact were examined.
GitLab features
Scanner Enablement Wizard
| Tier | Maturity | Deployments |
|---|---|---|
| Ultimate | GA | GitLab.com, Self-Managed, Dedicated |
Use Advanced setup. Quick setup applies default profiles to every uncovered project in the group.
Security configuration profiles
| Tier | Maturity | Deployments |
|---|---|---|
| Ultimate | GA | GitLab.com, Self-Managed, Dedicated |
The secret-detection profile also enables push protection.
SAST
| Tier | Maturity | Deployments |
|---|---|---|
| Free (Ultimate for profiles, MR widget and vulnerability report) | GA | GitLab.com, Self-Managed, Dedicated |
Dependency scanning (SBOM-based analyzer)
| Tier | Maturity | Deployments |
|---|---|---|
| Ultimate | GA | GitLab.com, Self-Managed, Dedicated |
Needs a supported lockfile or dependency graph export.
Secret push protection
| Tier | Maturity | Deployments |
|---|---|---|
| Ultimate | GA | GitLab.com, Self-Managed, Dedicated |
The legacy project toggle can read Not enabled while an applied profile supplies the Git-push trigger.
Security inventory
| Tier | Maturity | Deployments |
|---|---|---|
| Ultimate | GA | GitLab.com, Self-Managed, Dedicated |
Evaluates coverage from the most recent completed default-branch pipeline.
Implement
Steps
Apply default security scanner profiles
In the group, open Secure > Security configuration > Scanners, select Enable scanners > Advanced setup, choose the selected project, and apply the default SAST, Dependency scanning and Secret detection profiles.
Align application tests with profile scanners
Merge an explicit merge request rule into the existing .gitlab-ci.yml so the application tests run in the same merge request pipeline as the profile scanners. Keep existing stages, jobs, includes and source gating.
Verify jobs for both source revisions
Open an ordinary merge request. For its head SHA, confirm the test job and each scanner job are present and individually successful with reports. Repeat for the resulting default-branch SHA.
Review scanner configuration at its source
Review existing CI, included configuration and policies. Change scanner settings at their origin, and remove redundant legacy includes through review once profiles are authoritative.
Check scanner coverage after the pipeline
After the next default-branch pipeline, check the Unprotected projects, Needs attention and Stale scans cards and each scanner's Source, Status and Last scan.
Identify the push protection source
For push protection, inspect the applied profile's triggers and the legacy toggle separately, and record which source the project relies on.
Record verification evidence and decision ownership
Record what Verify accepted (SHA, target state, jobs and reports, review, policy revision, decision owner) and who can connect that result to the actual merge and release path.
Commands
Align application tests with profile scanners
Align application tests with profile scanners
Prove
What proves it
Pipeline records for one merge request head and its default-branch revision showing the test job and every selected scanner job individually successful with reports, and a record of what Verify accepted.
Review cadence
Every merge request, plus on change to a profile, language, dependency input, exclusion or runner
API read checks
3.3-jobs-present-per-sha
Reads
Jobs for the merge request head pipeline and the resulting default-branch pipeline.
Passes when
The application test and SAST, dependency scanning and secret detection jobs are present and individually success, not inferred from the pipeline status.
3.3-no-stale-scans
Reads
Secure > Security configuration > Scanners details for each scanner.
Passes when
The project shows the applied profile in Source, a healthy Status and a recent Last scan. Stale means absent from three consecutive default-branch pipelines.
Manual checks
3.3-verify-acceptance-record
Produce
Source SHA, target state, required jobs and reports, DAP or human review, policy revision and decision owner.
Why manual
Release needs to know exactly what Verify accepted.
Command
glab api --hostname gitlab.com "projects/${GSS_APP_ID}/pipelines/${GSS_PIPELINE_ID}/jobs?per_page=100" | jq '[.[] | {name, status, allow_failure}]'
3.4 Protected checks
Owner: Policy administrator
Coverage: Partial
Summary: The application actor can't alter scanners, rules or the policy link
Understand
What it protects
The checks a change must pass are administered outside the authority of the people and agents whose changes they check.
Pass when
Policy administration is separated and its branch protected (see F.1). For the selected application, you've checked whether the application actor can change policy selection, scanner configuration, rules, variables, runner execution, report contents, approval eligibility, merge settings or branch protections, and each path found is closed or recorded as open.
What GitLab covers and what stays yours
Security policy projects separate policy management from application projects. That separation holds only when effective permissions preserve it, including inherited roles and who can link or unlink.
Considerations
- Scanner profiles, DAP flows and separate policy ownership don't by themselves provide a merge gate resistant to an application Maintainer. Keep that requirement open.
- A green pipeline, named approver or signed artifact can't replace an independent admission design.
GitLab features
Security policy projects
| Tier | Maturity | Deployments |
|---|---|---|
| Ultimate | GA | GitLab.com, Self-Managed, Dedicated |
Protected branches and branch rules
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
Include every matching rule and its source.
Restrict pipeline variables
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
Implement
Steps
Establish independent policy administration
Complete F.1: separate policy administration, protect its branch and link it at the subgroup.
Inspect the application Maintainer's authority
Treat the application Maintainer as untrusted for the admission decision. List what that account can edit on the project, runner and job-token pages, without changing anything just to test the UI.
Check controls outside application administration
As the trusted Owner, check controls outside the application role: group-runner administration, the policy project's variables and allowlist, protected policy refs and the policy link.
Move control administration outside application roles
If an application Maintainer can replace, retag, share or reconfigure a required runner, check or credential, move its administration outside that role before relying on it.
Prove
What proves it
A list of every path by which the application actor could alter a required check, each closed and tested, or recorded as an open gap with an owner.
Review cadence
On change to membership, roles, branch rules, policy link or the admission mechanism
API read checks
3.4-policy-link-intact
Reads
Group and project securityPolicyProject fields.
Passes when
The subgroup still names the policy project after every membership change.
Behaviour checks
3.4-bypass-attempt
Does
Through the same admission path, attempt a representative bypass found in the permission review, after showing a clean change completes.
Expect
The target remains unchanged, and the denial isn't caused by an unrelated failure.
Manual checks
3.4-alteration-paths
Produce
Each setting the application actor can change that affects a required check, and its status.
Why manual
Effective permissions come from many sources and need human review.
Command
glab api --hostname gitlab.com graphql --raw-field query="$GSS_LINK_QUERY" --raw-field group="$GSS_SUBGROUP_PATH" --raw-field project="$GSS_APP_PATH"
3.5 Separation of duties
Owner: Security reviewer
Coverage: Partial
Summary: Agent proposals pass independent human review
Understand
What it protects
An agent's review, triage or fix informs a human decision; it never substitutes for it. The approver is independent of the author, human or agent.
Pass when
DAP Security Review threads, false-positive assessments and proposed fixes each receive a recorded human decision. Approval rules require someone other than the initiating author, and the application actor can't add an approver, change the rule or reach the target another way.
What GitLab covers and what stays yours
Security Review Flow, SAST false positive detection and Agentic SAST Vulnerability Resolution help people act on findings, and approval rules support independent review. Whether the reviewer is actually independent, given every alternate write path, is yours to check.
Considerations
- Security Review findings aren't added to the Vulnerability Report or counted by merge request approval policies, and the flow never approves.
- A false-positive assessment doesn't justify dismissal on its own.
- A named reviewer isn't independent if the author can add another eligible approver, change the rule or push directly to the target.
GitLab features
Security Review Flow
| Tier | Maturity | Deployments |
|---|---|---|
| Ultimate | Beta | GitLab.com, Self-Managed, Dedicated |
Runs only when Duo Security Review is assigned as a reviewer, and consumes GitLab Credits.
SAST false positive detection
| Tier | Maturity | Deployments |
|---|---|---|
| Ultimate | GA | GitLab.com, Self-Managed, Dedicated |
Configure push rules to permit the flow's service account.
Agentic SAST vulnerability resolution
| Tier | Maturity | Deployments |
|---|---|---|
| Ultimate | GA | GitLab.com, Self-Managed, Dedicated |
Opens a merge request; doesn't approve or merge it.
Security Analyst Agent
| Tier | Maturity | Deployments |
|---|---|---|
| Ultimate | GA | GitLab.com, Self-Managed, Dedicated |
A chat assistant for investigation, not an assigned reviewer.
Dependency scanning auto-remediation
| Tier | Maturity | Deployments |
|---|---|---|
| Ultimate | Beta | GitLab.com, Self-Managed, Dedicated |
Generated jobs are untagged, need privileged mode and ignore .gitlab-ci.yml.
Merge request approval rules
| Tier | Maturity | Deployments |
|---|---|---|
| Premium | GA | GitLab.com, Self-Managed, Dedicated |
Free supports optional approvals, which don't block merging.
Implement
Steps
Enable GitLab Duo and intended flows
At the top-level group, an Owner turns on GitLab Duo and the Agent Platform, then enables Allow flow execution, Allow foundational flows and the intended flows in Settings > GitLab Duo.
Review Duo Security Review findings
Assign Duo Security Review as a reviewer on a merge request. Check each thread against the authorization model and tests, record the SHA, note and threads, and reassign after a correction.
Independently assess SAST false positive detection
Turn on SAST false positive detection in project Settings > General > GitLab Duo. Read each assessment with the code and call paths, and record an independent human reason for confirming, dismissing or deferring.
Review Agentic SAST resolution changes
Review an Agentic SAST resolution merge request as an ordinary change: inspect the diff, confirm its pipeline and scan for the head SHA, run focused tests, and use normal reviewers and protected-branch rules.
Inspect approval and branch rules
Inspect Settings > Merge requests > Merge request approvals and the rules on the actual merge request, then every matching branch rule in Settings > Repository > Branch rules.
Test legitimate changes and representative bypasses
Show a legitimate clean change completes, then attempt a representative bypass through the same path, including direct pushes, force pushes, tokens and privileged automation.
Prove
What proves it
Agent output paired with a recorded human decision, and an approval path that refuses the author's own approval and every alternate write path you found.
Review cadence
Every merge request, plus on change to approval rules, flow setup or reviewer membership
API read checks
3.5-approver-not-author
Reads
Approvals on the merge request and its author.
Passes when
At least one required approver differs from the author and the initiating user.
Behaviour checks
3.5-self-approval-refused
Does
As the author, attempt to approve and merge the change, and try an alternate write path found in the review.
Expect
Each attempt is refused and the target branch is unchanged.
Manual checks
3.5-dap-decisions-recorded
Produce
For each Security Review thread, false-positive assessment and agent-proposed fix, the human decision and its reason.
Why manual
Agent output is a prompt for judgment; the decision is a person's.
3.5-risk-exceptions
Produce
Each exception's owner, reason, compensating action, expiry and recheck trigger.
Why manual
An exception may authorize proceeding but doesn't satisfy Verify.
Command
glab api --hostname gitlab.com "projects/${GSS_APP_ID}/merge_requests/${GSS_MR_IID}/approvals" | jq '{approved, approved_by: [.approved_by[].user.username]}'
4.2 Provenance and signing
Owner: Release operator
Coverage: Partial
Summary: Exact build acquired; release decision signed against its digest
Understand
What it protects
The operator approves particular bytes from a particular build, and that decision is bound to the artifact by a signature whose trust doesn't come from the material being verified.
Pass when
The exact build is acquired from a successful default-branch push pipeline and job, with the runner, job archive, manifest and source files recorded. The release decision is signed with a key whose fingerprint was recorded through the release-approval channel before signing.
What GitLab covers and what stays yours
GitLab records pipelines, jobs, runners and artifacts. The signing identity, key custody, promotion rule and SLSA provenance are yours; the local signing example isn't full SLSA provenance.
Considerations
- The example's local key and shared Docker host aren't a production design.
- The build doesn't consume scanner-profile or DAP results and doesn't establish a security-verification gate.
GitLab features
Jobs and job artifacts APIs
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
Retain the complete job archive with the extracted artifact and manifest.
Runners API
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
Record the runner that actually built the artifact.
SLSA level 3 provenance attestations
| Tier | Maturity | Deployments |
|---|---|---|
| Ultimate | Experiment | GitLab.com |
The guide's example doesn't produce SLSA provenance.
Implement
Steps
Prepare a protected release project
Use a fresh private release project. Protect main for the named Owner only, set pipeline variables to No one allowed, keep job-token pushes off, and record project, user and environment IDs.
Commit the reviewed build configuration
Commit the reviewed .gitlab-ci.yml, build_fixture.py, release_tools.py and version.txt from the connected-release example through the Owner path.
Identify the exact successful build
Record A's full SHA, pipeline ID and job ID. Confirm a successful default-branch push pipeline with exactly one successful build_release_fixture job.
Acquire and verify the build inputs
Run the driver's acquire step. It checks each credential's numeric identity, reads the runner, downloads the exact archive, extracts only the expected artifacts and writes operator-inputs.json.
Generate and record the release key
Generate an exercise-only Ed25519 key and record its fingerprint through the release-approval channel before signing.
Sign a distinct promotion for A
Promote A with the exact identities in operator-inputs.json and a distinct release ID.
Commands
Acquire exact build A
python3 "$GSS_DRIVER" acquire \
--project-id "$GSS_PROJECT_ID" --project-path "$GSS_PROJECT_PATH" \
--owner-id "$GSS_OWNER_ID" --operator-id "$GSS_RELEASE_OPERATOR_ID" \
--source-sha "$GSS_A_SHA" --pipeline-id "$GSS_A_PIPELINE_ID" \
--job-id "$GSS_A_JOB_ID" --job-name build_release_fixture \
--version known-good-a --output-dir "$GSS_RECORD_DIR/a" \
--owner-token-env GITLAB_OWNER_TOKEN \
--operator-token-env GITLAB_OPERATOR_TOKEN \
--journal "$GSS_RECORD_DIR/acquire-a.jsonl"
Create the release key and record its fingerprint
Create the release key and record its fingerprint
Prove
What proves it
An acquisition record tying the artifact to its source SHA, pipeline, job and runner, and a signed promotion over those identities with an independently recorded fingerprint.
Review cadence
On change to the artifact, promotion or deployment path
API read checks
4.2-build-identity
Reads
operator-inputs.json and the pipeline and job through the API.
Passes when
Successful default-branch push pipeline, one successful build_release_fixture job, and matching runner and source identities.
Manual checks
4.2-fingerprint-recorded
Produce
The trusted fingerprint, recorded through the release-approval channel before signing.
Why manual
Trust must come from outside the material being verified.
4.2-production-plan
Produce
The production artifact store, immutable reference, provenance source, signing identity and key custody, promotion rule, deployer and rollback source.
Why manual
The local example is practice, not production provenance.
Command
jq '{source_sha, pipeline: .pipeline.id, job: .job.id, runner: .runner.id, version}' "$GSS_RECORD_DIR/a/operator-inputs.json"
Evidence to retain
operator-inputs.jsonpromotion.jsonpromotion.sigkeygen.jsonacquire-a.jsonl
4.3 Verify before deploy
Owner: Release operator
Coverage: Your process
Summary: Altered bytes and an unapproved signer are rejected before deploy
Understand
What it protects
Approval can't be carried over to different bytes or a different signer, and only the release deployer can deploy.
Pass when
The application actor's deployment attempt is denied with the deployment inventory unchanged. The deployer's run verifies again immediately before changing the runtime, and an altered artifact and a valid promotion from an unapproved key are both rejected before any deployment or Docker command while the running release stays healthy.
What GitLab covers and what stays yours
Protected environments limit who can deploy. Checking the digest and signature against an independent trust reference immediately before deployment is your release tooling's job.
Considerations
- A timeout leaves the outcome unknown; it isn't an authorization denial. Reconcile before retrying.
- Re-inviting a user doesn't restore a removed user-specific deploy permission.
- Stop-then-start replacement isn't blue-green deployment or traffic switching.
GitLab features
Protected environments
| Tier | Maturity | Deployments |
|---|---|---|
| Premium | GA | GitLab.com, Self-Managed, Dedicated |
Allow deployment only by the configured release deployer.
Environments API
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
The REST field is tier; deployment_tier is the CI keyword.
Implement
Steps
Protect the release environment
Create environment local-release-lab with tier testing, protect it, and allow deployment only by the release service account or authorized human.
Verify the application actor cannot deploy
Run deny-deployment as the application actor. Accept only an authorization denial and require the deployment-ID inventory to be unchanged.
Deploy A with repeated verification
Deploy A in one process: the driver checks the operator's identity, revalidates bytes and promotion, creates a running deployment, verifies again before changing Docker, proves the mounted digest, health and version, then marks it success.
Reject an altered artifact before deployment
Copy and alter B's artifact, and require the same verifier to reject it before any deployment or Docker command.
Reject an unapproved signing key
Sign a valid promotion for unchanged B with a second key, and require verification to reject its unapproved fingerprint while B stays healthy.
Commands
Deploy approved A
Prove
What proves it
A denied deployment by the application actor, a deployment of A verified immediately before start, and two local rejections (altered bytes and unapproved signer) with B unchanged.
Review cadence
On change to the artifact, promotion or deployment path
Behaviour checks
4.3-actor-deploy-denied
Does
Run deny-deployment as the application actor against local-release-lab.
Expect
An authorization denial, the actor's identity read again, and an unchanged deployment-ID inventory.
4.3-altered-bytes-rejected
Does
Append bytes to a copy of B's artifact and run the verifier.
Expect
ContractError: build manifest differs from verified inputs or artifact, and B's receipt unchanged.
Script
verify_release
4.3-unapproved-signer-rejected
Does
Sign a valid promotion for unchanged B with a second key and run the verifier.
Expect
Rejected for the unapproved fingerprint; B stays healthy.
Command
python3 "$GSS_DRIVER" inspect-runtime --receipt "$GSS_RECORD_DIR/b/runtime.json" --docker-context desktop-linux --journal "$GSS_RECORD_DIR/inspect-b.jsonl"
Standalone check
The shared verifier
verify_release() {
inputs="$1"; release_id="$2"; attestation="$3"; signature="$4"
artifact="${5:-$(jq -er '.paths.artifact' "$inputs")}"
public_key="${6:-$GSS_RECORD_DIR/keys/release-public.pem}"
fingerprint="${7:-$GSS_TRUSTED_FINGERPRINT}"
python3 "$GSS_TOOLS" verify \
--manifest "$(jq -er '.paths.manifest' "$inputs")" --artifact "$artifact" \
--attestation "$attestation" --signature "$signature" --public-key "$public_key" \
--trusted-fingerprint "$fingerprint" --release-id "$release_id" \
--project-id "$(jq -er '.project.id' "$inputs")" \
--source-sha "$(jq -er '.source_sha' "$inputs")" \
--version "$(jq -er '.version' "$inputs")"
# ...plus the remaining pipeline, job, runner and path identities
}
Evidence to retain
runtime.jsonactor-denial.jsonlaltered-rejection.txtdeploy-a.jsonl
4.4 Immutable references
Owner: Release operator
Coverage: Partial
Summary: Deploy and rollback carry the digest, never a name
Understand
What it protects
Every deployment and rollback names the exact digest that was approved, so a moved tag or rebuilt artifact can't slip in.
Pass when
The artifact digest is carried through deployment of A and B and through rollback. Rollback is a new signed decision over retained A bytes, with a new deployment record. For a registry, tag protection and overwrite restrictions are configured.
What GitLab covers and what stays yours
GitLab supports protected container tags and records deployments. Carrying the digest through every step, and treating rollback as a new decision, is your release process.
Considerations
- GitLab deployment records are mutable metadata. Use the signed approval and the running artifact to decide what reached the environment.
- The local example doesn't configure registry tag protection.
GitLab features
Protected container tags
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed |
Deployments API
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
Records help operators find releases but remain mutable.
Implement
Steps
Build and acquire candidate B
Have the Owner change only version.txt to candidate-b, commit through protected main, and acquire B into a new directory.
Promote B and replace A
Promote B with a distinct release ID. Inspect A, remove it by its exact receipt, then deploy B.
Roll back with a new promotion
For rollback, create a distinct rollback-a promotion over A. Don't reuse initial-a. Deploy it as a new container and deployment record without rebuilding A.
Protect registry tags from overwrites
For a container registry, configure tag protection and overwrite restrictions.
Commands
Roll back with a new signed decision
promote "$GSS_RECORD_DIR/a/operator-inputs.json" rollback-a \
"$GSS_RECORD_DIR/a/rollback.json" "$GSS_RECORD_DIR/a/rollback.sig"
python3 "$GSS_DRIVER" remove-runtime --receipt "$GSS_RECORD_DIR/b/runtime.json" \
--docker-context desktop-linux --journal "$GSS_RECORD_DIR/remove-b.jsonl"
Prove
What proves it
Deployment and rollback records whose digests match the signed promotions, with rollback recorded as its own decision.
Review cadence
On change to the artifact, promotion or deployment path
API read checks
4.4-deployments-listed
Reads
Deployments for local-release-lab, newest first.
Passes when
One record each for A, B and rollback-A, all by the release deployer.
Manual checks
4.4-digest-chain
Produce
Source, build, signed approval and deployment records for each release kept together.
Why manual
An operator must be able to identify what ran and pick a retained version for recovery.
Command
glab api --hostname gitlab.com "projects/${GSS_PROJECT_ID}/deployments?environment=local-release-lab&order_by=id&sort=desc" | jq '[.[] | {id, status, sha}]'
Evidence to retain
rollback.jsonrollback.sigremove-b.jsonl
5.1 Monitor consequential actions
Owner: Audit and response owners
Coverage: Partial
Summary: Streams configured; one deployment traced across them
Understand
What it protects
Consequential actions in GitLab and every connected system are recorded continuously, not reconstructed after an incident.
Pass when
Audit and response owners have configured streams, retention and access for consequential actions in GitLab and every connected system. One ordinary deployment and one harmless response exercise are traced across those records, and missing events are recorded as integration work.
What GitLab covers and what stays yours
GitLab supplies audit events and audit event streaming. Agent runtime, cloud and external-system records, and the joins between them, are yours.
Considerations
- An incident snapshot alone doesn't provide continuous monitoring.
- An incident-time API export can't substitute for monitoring that was never configured.
GitLab features
Audit event streaming
| Tier | Maturity | Deployments |
|---|---|---|
| Ultimate | GA | GitLab.com, Self-Managed, Dedicated |
Audit events
| Tier | Maturity | Deployments |
|---|---|---|
| Premium | GA | GitLab.com, Self-Managed, Dedicated |
Implement
Steps
Assign audit and response owners
Complete the audit plan in F.2 and assign Audit and response owners.
Configure activity records and retention
Configure audit event streaming where available, plus credential and deployment activity, with retention and access controls.
Trace deployment and response records
Trace one ordinary deployment and one harmless response exercise across the records. Record missing events or identities as specific integration work.
Prove
What proves it
A configured stream and a trace of one deployment and one response exercise across GitLab and connected systems.
Review cadence
On change to the agent runtime, connected systems or streaming destinations
Manual checks
5.1-streams-traced
Produce
Configured streams and retention, plus one deployment and one response exercise traced across them.
Why manual
Coverage across systems can only be shown by following a real event.
Command
Trace deployment and response records
5.2 Tested kill switch
Owner: Response owner
Coverage: Partial
Summary: Credential revoked, pipeline canceled and release stopped in a drill
Understand
What it protects
The people responsible can stop current work, close its credentials and suspend a release, and have practised doing it under representative conditions.
Pass when
In a practice project, responders revoke the affected token and read it back as inactive, cancel identified pipelines and read each back as canceled (including child and downstream pipelines), and stop the running release through the environment's allowed deployer. Who can stop, revoke, suspend, preserve, assess, approve recovery and communicate is agreed in advance.
What GitLab covers and what stays yours
GitLab supplies token revocation, pipeline cancellation and protected environments. Stopping work already accepted outside GitLab, revoking external credentials and communicating with owners are yours.
Considerations
- The cancel endpoint returns
200regardless of pipeline state. Wait for the readback to reachcanceled. - Revocation metadata doesn't prove that a process discarded a cached secret, a running job stopped, or an external session ended.
- Canceling a pipeline doesn't undo a package, deployment or message it already delivered.
GitLab features
Group and project access tokens
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
A successful revoke returns 204.
Service account token revocation
| Tier | Maturity | Deployments |
|---|---|---|
| Premium | GA | GitLab.com, Self-Managed, Dedicated |
Use the owning group's endpoint.
Pipelines API
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
The ordinary listing omits child pipelines; query source=parent_pipeline too.
Protected environments
| Tier | Maturity | Deployments |
|---|---|---|
| Premium | GA | GitLab.com, Self-Managed, Dedicated |
Administrative access alone doesn't establish deploy permission.
Implement
Steps
Agree response authority before granting autonomy
Before granting Act with guardrails, agree who can stop the workflow, revoke credentials, suspend a release, preserve records, assess impact, approve recovery and communicate with owners.
Capture state from a trusted session
From a trusted responder session separate from the suspected identity, confirm identity and capture the branch tip and active pipeline inventory, including child pipelines.
Revoke access before issuing recovery credentials
Revoke the exact token by type and read it back as revoked: true, active: false. Close it before issuing any recovery credential.
Cancel selected pipelines and verify completion
Cancel each pipeline the response owner selects, and wait for its readback to reach canceled. Follow bridge and trigger links into downstream projects.
Rehearse containment and recovery together
Rehearse connected response: cancel one running job, revoke the release credential, contain B, and recover A with a fresh decision and credential.
Commands
Cancel a pipeline and read back its state
Cancel a pipeline and read back its state
Prove
What proves it
A practised drill with readbacks: the token inactive, every selected pipeline canceled, and the release stopped by its allowed deployer.
Review cadence
Rehearsed before Act with guardrails, and on change to a credential, runtime or response procedure
API read checks
5.2-token-inactive
Reads
The inactive token collection filtered to the revoked ID.
Passes when
Exactly one match with revoked: true and active: false.
5.2-pipelines-canceled
Reads
Each selected pipeline, plus same-project child pipelines.
Passes when
Every selected pipeline reads canceled.
Behaviour checks
5.2-connected-response-drill
Does
Follow the connected-response procedure with a harmless running job and a short-lived credential.
Expect
The job is canceled, the release credential revoked, B contained, and A recovered under a fresh decision.
Manual checks
5.2-response-roles
Produce
Who can stop, revoke, suspend, preserve, assess, approve recovery and communicate, and how to reach them.
Why manual
A kill switch is only as fast as the person who can use it.
Command
glab api --hostname gitlab.com "projects/${GSS_APP_ID}/pipelines/${GSS_PIPELINE_ID}" | jq '{id, status}'
Evidence to retain
branch-before.jsonpipelines-before.json
5.3 Trace impact
Owner: Response owner
Coverage: Partial
Summary: Time-ordered record preserved and a reviewed revision restored
Understand
What it protects
Responders can establish what the affected work touched and restore a reviewed state without weakening protection.
Pass when
The affected work is captured before changing state, a time-ordered record is preserved across GitLab and crossed boundaries, and a known-good revision is restored through a reviewed recovery merge request with its branch SHA, effective policy, security result and service health confirmed.
What GitLab covers and what stays yours
GitLab supplies audit events, the compare API and protected merge paths. Identity-provider, cloud, agent and external-system records, and the judgment of what's affected, are yours.
Considerations
- Deleting a GitLab pipeline also deletes its logs and artifacts, so deletion isn't a containment step.
- A clean scan supports recovery of the tested source; it doesn't show a deployed environment received that artifact.
- Rolling back won't invalidate an exposed credential, and rotating a credential won't remove a malicious change.
GitLab features
Audit events API
| Tier | Maturity | Deployments |
|---|---|---|
| Premium | GA | GitLab.com, Self-Managed, Dedicated |
One part of the record, not a complete execution history.
Repository compare API
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
If compare_timeout is true or a diff is collapsed, the diff can be incomplete.
Implement
Steps
Record the incident window and revisions
Record the UTC incident window, the default-branch SHA before intervention, and the known-good revision chosen by the repository or policy owner.
Preserve records across affected systems
Retrieve project audit events for the window, and preserve commits, merge requests, pipelines, job logs, artifacts, deployments, approvals and policy revisions. Add records from every crossed boundary.
Separate observed facts from uncertainty
Keep observed facts, inferences, missing data and unresolved targets distinct.
Restore through a reviewed recovery branch
Compare the known-good revision with the current branch, prepare a recovery branch, and merge it through the protected path after review. Don't reset or force-push the default branch.
Verify the revision and recovered service
Read back the branch SHA and the pipeline for that revision. Confirm effective policy, security result, service health and deployed artifact identity before declaring recovery.
Commands
Capture the branch tip before changing state
glab api --hostname gitlab.com \
"projects/${GSS_APP_ID}/repository/branches/${GSS_DEFAULT_BRANCH}" \
| tee branch-before.json \
| jq '{name, protected, commit_id: .commit.id}'
Prove
What proves it
A time-ordered record that separates fact from inference, and a recovery merge request whose readbacks match the recovery decision.
Review cadence
Rehearsed before Act with guardrails, and after every incident
API read checks
5.3-recovery-readback
Reads
The default branch and the pipeline for the recovery merge commit.
Passes when
Branch SHA, effective policy and a successful security result match the recovery decision.
Manual checks
5.3-time-ordered-record
Produce
GitLab and external records for the window, with facts, inferences, missing data and unresolved targets kept distinct.
Why manual
Impact crosses systems no single API covers.
Command
glab api --hostname gitlab.com "projects/${GSS_APP_ID}/repository/compare?from=${GSS_KNOWN_GOOD_SHA}&to=${GSS_DEFAULT_BRANCH}" | tee recovery-compare.json | jq '{compare_timeout, commits: [.commits[].id]}'
Evidence to retain
audit-events.jsonrecovery-compare.jsonbranch-before.json
L.1 Lessons feed policy
Owner: Service owner
Coverage: Your process
Summary: Each change rechecked; autonomy matches demonstrated stages
Understand
What it protects
Every change, bypass and incident leads to a focused recheck and an explicit decision about whether the workflow's autonomy expands, holds or narrows.
Pass when
The workflow has a maintenance owner and review rhythm. After each change, the matching recheck is run and recorded alongside the earlier record. A short decision record links the observed result for the Foundation and each stage, names any gap and its owner, and states the autonomy level those results support.
What GitLab covers and what stays yours
GitLab keeps the records the review reads. Deciding when to recheck and what autonomy the results support is yours.
Considerations
- A later successful check doesn't erase the interval when a control was ineffective.
- A falling vulnerability total may reflect fixes, dismissals or reduced scan coverage.
- Success in preparing code changes doesn't establish permission to alter policy, release to production or revoke credentials.
GitLab features
Security inventory
| Tier | Maturity | Deployments |
|---|---|---|
| Ultimate | GA | GitLab.com, Self-Managed, Dedicated |
Review coverage across the group.
Job artifacts
| Tier | Maturity | Deployments |
|---|---|---|
| Free | GA | GitLab.com, Self-Managed, Dedicated |
Download original scanner output before expiry.
Implement
Steps
Retain the operating baseline
Retain an operating baseline: profiles and scope, source revision, pipeline and scanner jobs, original output before expiry, and findings linked to triage decisions and remediation merge requests.
Recheck the controls affected by change
After a change, run the matching recheck: scanner or runner change, DAP flow change, membership or policy-link change, admission change, credential or runtime change, or artifact and deployment change.
Preserve earlier and new evidence
Keep the earlier record and create a new one. When a formerly prohibited action succeeds, record it before restoring the control.
Record demonstrated controls and supported autonomy
Keep a decision record: for the Foundation and each stage, link the observed result, mark it demonstrated or not, name any gap and its owner, then name the autonomy level those results support.
Restrict authority when prerequisites fail
When a check is waived, a prohibited action succeeds or an intervention fails, restrict the workflow to authority whose prerequisites still hold. Exercise new permissions, failure cases and volume and system limits before raising autonomy.
Prove
What proves it
Recheck records paired with earlier ones, and a current decision record whose autonomy level matches the stages actually demonstrated.
Review cadence
On every change, bypass, incident, failed recovery or expired exception
Manual checks
L.1-decision-record
Produce
Per stage: observed result, demonstrated or not, gap and owner; then the supported autonomy level.
Why manual
Autonomy is a judgment over evidence, not a setting.
L.1-recheck-log
Produce
Each change with its recheck and retained decision.
Why manual
The interval when a control failed must stay visible.
Command
glab api --hostname gitlab.com "projects/${GSS_APP_ID}/pipelines?ref=main&per_page=5" | jq '[.[] | {id, sha, status}]'
Notes
-
GitLab audit-event features, event coverage, retention, and streaming destinations vary by tier and offering. See Audit events for current availability and supported event types. ↩
-
Security policy projects and their enforcement features are available in GitLab Ultimate across GitLab.com, Self-Managed, and Dedicated. See Security policy projects for current prerequisites, permissions, inheritance, and ownership behavior. ↩
-
Required merge request approvals are available in Premium and Ultimate. GitLab Free supports optional approvals, which don't block merging. See Merge request approvals for current behavior and availability. ↩