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.
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. ↩