Skip to content

[FEATURE] GitLab: support subgroup-scoped policy discovery (team-level apm-policy), not only the top-level group #2753

Closed

Description

@rrazvd

Is your feature request related to a problem? Please describe.

On GitLab, org-policy auto-discovery is anchored exclusively to the top-level group: APM takes the first path segment of the project remote and looks for <top-level-group>/apm-policy (nested subgroup scopes are explicitly not searched, per the Policy Files docs and the fix in #2566 / PR #2662, shipped in v0.29.0).

This is a problem for large organizations where the top-level group is shared across many independent teams and departments. Consider a project whose remote is:

gitlab.com/acme/dept-a/area-1/team-x/my-project

The first segment is acme — the whole company. To have any policy enforced at apm install time, it would have to be published at acme/apm-policy, which would govern every team and department under acme, not just the one that owns the project. A team that only wants to govern its own projects (under .../team-x) has no supported way to scope a policy to its subgroup.

The practical effect today: apm install prints No org policy found for this project, apm audit --ci reports No org policy found ...; enforcement skipped, and CI stays green while none of the team's dependency/MCP/compilation rules are ever enforced — a false sense of security.

Describe the solution you'd like

Subgroup-aware policy discovery on GitLab. When resolving a project's org policy, APM should walk up the group hierarchy from the project's immediate parent to the top-level group, looking for an apm-policy project at each level, and apply the closest one found (composing with ancestors via the existing extends: chain). For example, for a remote like gitlab.com/acme/dept-a/area-1/team-x/my-project, APM would probe, in order:

acme/dept-a/area-1/team-x/apm-policy
acme/dept-a/area-1/apm-policy
acme/dept-a/apm-policy
acme/apm-policy

This mirrors how GitLab itself scopes settings (CI/CD variables, runners, etc.) hierarchically by group/subgroup, and lets a team enforce policy over just its own projects without owning company-wide governance.

Describe alternatives you've considered

  • Top-level <company>/apm-policy only: rejected — it would impose one team's rules on the entire organization.
  • An explicit override env var (e.g. APM_GITLAB_POLICY_GROUP=<full/sub/group>) pointing discovery at a specific subgroup: acceptable as a minimal first step, but note that a similar APM_GITLAB_POLICY_ROOT_GROUP override was added and then removed in PR fix: harden GitLab policy discovery (supersedes #2605, closes #2566) #2662 ("remove the unsupported root-group override"), so the design tradeoffs here need revisiting.
  • apm audit --ci --policy ./apm-policy.yml pointing at a repo-local file in CI: a common workaround, but --policy is audit-only and is not wired through apm install, so install-time enforcement is still skipped and the policy isn't shared/discovered across the team's other repos.
  • --no-policy: disables enforcement entirely — not acceptable for a governance use case.

Additional context

Activity

  1. added
    area/audit-policyapm-policy.yml schema, custom_checks, install-time enforcement.
    area/enterpriseAir-gapped/GHE configurability, registry proxy, rulesets, adoption playbook.
    status/acceptedHuman scope approval; verify the issue's approval record and review contact before work.
    status/triagedAutomated advice completed; deduplication only. Not human approval; silence is not approval.
    on Sep 8, 2026
  2. github-actions commented on Sep 8, 2026

    @github-actions

    Triage decision

    accept

    Proposed labels

    theme/governance
    area/enterprise
    area/audit-policy
    type/feature
    status/accepted
    

    Milestone

    null

    Suggested next action

    Extend the GitLab integrator's group-resolution path to walk parent subgroups when resolving policy configuration, matching GitHub's org-level policy inheritance.

    Suggested issue comment

    Good catch -- this is a real parity gap. GitHub org-level policy correctly walks up to org scope, but the GitLab integrator only checks the immediate namespace, so nested subgroups (a very common GitLab structure) silently fall back to no policy instead of inheriting from a parent group.
    
    Accepting this as a bug/parity fix in the GitLab integrator's policy-resolution path.

    Per-lens notes (collapsed)

    DevX UX Expert -- User-Need Reviewer

    Silent policy fallback (no error, no warning) is the worst failure mode for a governance feature -- an enterprise relying on subgroup-level policy would not know it isn't being enforced. Worth confirming whether the fix should also emit a diagnostic when a subgroup has no resolvable policy at any level, rather than silently allowing.

    Supply Chain Security Expert -- Risk-Surface Reviewer

    This is a governance/policy-enforcement gap, not a new capability surface -- fixing it tightens enforcement (more subgroups now correctly inherit policy) rather than loosening it, so low risk to implement, but worth a regression test asserting subgroup policy resolution walks the full ancestor chain to prevent silent re-regression.

    OSS Growth Hacker -- Contributor-Tone Reviewer

    Not activated -- enterprise/internal governance parity fix, not a growth or adoption-facing surface.

    Python Architect -- Architecture Reviewer

    Bounded fix within the GitLab integrator (BaseIntegrator pattern); walking the subgroup ancestor chain mirrors the existing GitHub org-resolution logic already in the codebase, so this is a parity fix rather than a new architectural surface -- no needs-design gate required.

    Doc Writer -- Documentation Reviewer

    Not activated as blocking; if the enterprise governance guide documents policy inheritance today, it should be checked for GitLab-specific caveats once fixed.

    APM CEO -- Triage Arbiter

    Clear parity bug in enterprise governance with an obvious, bounded fix path (mirror the existing GitHub inheritance logic). Accept, no milestone assigned this run.

    {
      "decision": "accept",
      "decision_detail": "",
      "theme": "theme/governance",
      "areas": ["area/enterprise", "area/audit-policy"],
      "type": "type/feature",
      "status": "status/accepted",
      "priority": null,
      "preserved_labels": [],
      "milestone": null,
      "next_action": "Extend the GitLab integrator's group-resolution path to walk parent subgroups when resolving policy configuration, matching GitHub's org-level policy inheritance.",
      "comment_markdown": "Good catch -- this is a real parity gap. GitHub org-level policy correctly walks up to org scope, but the GitLab integrator only checks the immediate namespace, so nested subgroups (a very common GitLab structure) silently fall back to no policy instead of inheriting from a parent group.\n\nAccepting this as a bug/parity fix in the GitLab integrator's policy-resolution path."
    }

    Triage status: agentic proposal pending human ratification.
    Silence is approval. Maintainers can:

    • Override any label or milestone above by editing it directly --
      human edits are authoritative and will not be reverted on
      subsequent runs.
    • Re-trigger triage by applying the status/needs-triage label, or
      by removing status/triaged to enroll the issue in the next
      daily sweep.

    Posted by the Triage Panel workflow. See packages/apm-triage-panel for the panel skill.

    Generated by Triage Panel · copilot · auto · 141.1 AIC · ⌖ 20.3 AIC · ⊞ 14.1K · ◷

  3. danielmeppiel commented on Sep 12, 2026

    @danielmeppiel
    Collaborator

    At the lead maintainer's direction, the current acceptance of this item is withdrawn as part of APM's roadmap and contribution reset. Previous acceptance labels or comments must not be treated as approval to start or continue substantive implementation for inclusion in APM.

    Thank you for the work and ideas already contributed. Our small maintainer team needs to agree supported scope and review capacity before inviting more implementation. This is not a rejection of the proposal or a judgment of your work, and it does not undo completed work or erase its history.

    Please follow the contribution rules: a responsible human maintainer needs to record the bounded scope, acceptance criteria and review contact on the issue before substantive work resumes. Existing issue discussion, assignments and contributions remain available for that decision. Trivial typo and broken-link corrections retain their standing preapproval.

  4. added
    triage/recommendedAutomated advice completed; not human scope approval.
    and removed
    status/triagedAutomated advice completed; deduplication only. Not human approval; silence is not approval.
    on Sep 12, 2026
  5. danielmeppiel commented on Oct 20, 2026

    @danielmeppiel
    Collaborator

    Thank you for explaining the team-level governance need and for the work in #2933.

    Confirmed product direction: team policies may only tighten applicable ancestor policies. A closer subgroup policy must not silently replace a company or department baseline. For example, selecting a team policy that omits an ancestor's blocked package source must not make that source allowed again. Tighten-only merging of explicit extends chains is not sufficient if discovery leaves the applicable ancestor out of the chain.

    This resolves the authority direction, not the implementation design. Before implementation is accepted, the bounded contract still needs to define how applicable or expected ancestors are identified, how teams without an applicable ancestor policy are handled, what unreadable or ambiguous-404 results mean, and how install and audit expose the effective source and chain. Prefer existing policy and merge mechanisms over a new governance framework; do not claim certainty about inaccessible private policies.

    This is not fresh implementation acceptance or approval of #2933's closest-wins semantics. The issue stays open. Preserve the contribution and prior history; do not restart blocked delivery or substantive implementation without separately agreed scope, acceptance criteria and review capacity.


    Generated by apm-strategy. This comment is AI-generated and may contain errors.

  6. danielmeppiel commented on Oct 20, 2026

    @danielmeppiel
    Collaborator

    Decision: approve
    Area: project
    Scope: Add bounded GitLab subgroup-policy composition to existing automatic policy discovery. For the current project's GitLab host, port and namespace ancestry, discover the existing conventionally named policy project at each ancestor namespace and combine the policies from company toward team using the existing tighten-only merger. An applicable, readable ancestor remains effective even when a closer policy omits extends; a team policy works alone when no ancestor policy is discovered. When none is discovered, preserve existing no-policy handling rather than making policy globally mandatory. Preserve supported explicit extends composition without adding reference syntax; extends: org continues to mean the top-level policy. The nearest discovered policy is the leaf for the existing raw-byte policy.hash contract, not a replacement for ancestor restrictions. Keep existing explicit policy overrides and policy-disable routes outside this automatic-discovery change. GitLab 404 remains absence for optional convention-based candidates, with the explicit limitation that GitLab can conceal an unreadable private policy as 404; supported governed CI must have read access across the applicable policy namespaces. A missing explicitly required extends parent remains an incomplete chain, not optional absence.
    Done when: Installed-CLI regressions demonstrate company-only, team-only, company-plus-team, multiple subgroup levels, missing intermediate policies and an empty or weaker child without losing ancestor restrictions. Install and audit must use the same effective policy and expose its ordered, credential-redacted source chain through existing diagnostics/status surfaces. Non-404 access, transport or parse failures during hierarchical composition must not result in applying a weaker partial chain, including under warn defaults; usable complete cached policy may follow existing stale-cache rules rather than dropping a layer. Preserve host/port credential isolation, cycle rejection, the existing five-policy limit across the composed distinct-policy chain, existing explicit-parent protections, and duplicate-ancestor handling without false cycles or duplicate fetches. Preserve leaf-only hash semantics: mismatches always fail closed, a changed selected leaf never silently repins, and docs explain that this is not an aggregate-chain hash. Cover valid cached/offline operation and refresh failures without network access in cache-only mode or silent omissions. Fetch work must be bounded by namespace ancestry plus the bounded extends chain, using existing transport/cache owners and no new concealment probes. Update the relevant policy docs, usage resources and compatibility note, including the 404/read-access limitation and changed leaf-selection/pin implications. Any existing PR, including #2933, must be evaluated against this contract rather than treated as already approved.
    Out of scope: Closest-wins replacement of an ancestor, new policy schema or override-selector environment variables, new credential stores/providers or permission-inspection framework, concealed-private-policy detection, new extends reference grammar, aggregate policy hashing, lifting the five-policy limit, discovery beyond the current namespace ancestry, GitHub/ADO discovery redesign, unrelated audit/resolver/rollback work, weakened validation or credential boundaries, reassignment, release promises, PR approval or merge authorization, automated implementation dispatch, or restarting blocked delivery without fresh bounded execution authorization.
    Review contact: Daniel Meppiel (@danielmeppiel)

  7. danielmeppiel commented on Oct 20, 2026

    @danielmeppiel
    Collaborator

    Accepted with complete bounded scope, recorded here. This supersedes the earlier direction-only hold. The issue remains open because delivery is outstanding, not because product scope is undecided.

    Discover policies along the project's GitLab namespace ancestry and combine them with the existing tighten-only merger. Company and department restrictions survive even when a team omits extends. Support team-only policy and retain existing handling when none exists. This is not closest-wins replacement.

    Completion requires real installed-CLI evidence, install/audit agreement, visible source provenance, and preserved failure, pin, cache/offline, host/cycle and five-policy protections. The scope explicitly documents GitLab's ambiguous 404/read-access limitation and retains leaf-only policy.hash semantics without silently repinning.

    No new policy syntax, selector environment variables, credential framework or other-forge redesign is accepted. I am the review contact. Preserve #2933 and its contributor history, but evaluate it against this contract; its current head is not approved. Normal technical review remains, but another product-design approval is not required within this scope. No release promise, reassignment, merge authorization or automatic blocked-delivery restart is implied.


    Generated by apm-strategy. This comment is AI-generated and may contain errors.

  8. added
    status/acceptedHuman scope approval; verify the issue's approval record and review contact before work.
    and removed
    status/deferredNot invited for implementation now; no release commitment.
    on Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/audit-policyapm-policy.yml schema, custom_checks, install-time enforcement.area/enterpriseAir-gapped/GHE configurability, registry proxy, rulesets, adoption playbook.pillar/governPillar: policy, trust, audit and supply-chain integritystatus/acceptedHuman scope approval; verify the issue's approval record and review contact before work.triage/recommendedAutomated advice completed; not human scope approval.type/featureNew capability, new flag, new primitive.

    Type

    No type

    Projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions