feat(gitlab): a hub inside the group of its targets (security.writer_on_hub: guard)

[AlexeyShalaev]

Closes #24.

A GitLab hub can now live in the group that holds its targets. The writer, a member of that group, then reaches the hub, and GitLab cannot lower an inherited role on one project. With security.writer_on_hub: guard in hub.yml, touchmark verifies that the writer cannot get content onto the hub's default branch, instead of requiring that it cannot see the hub. The default, refuse, keeps today's behaviour, messages included.

One addition to the issue: the CI file comes from the default branch

A merge request pipeline runs the CI file of its source branch. A writer that pushes to a maintainer's merge request could rewrite .gitlab-ci.yml to drop the plan that refuses its push, and "Pipelines must succeed" would pass. So the guard also requires the hub's CI/CD configuration file to be <file>@<hub path>:<default branch> (or <file>@<hub path>).

Checked live on CE 18.11.12:

• with the pin, a writer's push of its own CI file ran main's jobs, and the pipeline failed;
• without the pin, it ran the writer's file, and the pipeline passed;
• a [skip ci] push left the merge blocked;
• Developers and Reporters see ci_config_path and the merge checks;
• protected tags are shown to Maintainers only (403 to the writer), so doctor --hub-token grades them.

What changes

• Config. security.writer_on_hub: refuse (default) or guard, in the schema and the reference.

• doctor. Under guard, a writer that sees the hub gets hub-guard instead of hub-hidden, from the new optional platform.HubGuard (GitLab):

  • fail:
    • the writer is Maintainer or above;
    • the default branch is unprotected;
    • a matching rule lets the writer push or merge (most permissive rule, wildcards, user allows);
    • the CI file is not pinned;
    • merges do not wait for a successful pipeline, or count a skipped one;
  • warn: other protected branches, or protected tags, the writer may push to or create;
  • unknown: a group allow whose members the writer cannot read.

  Other drivers report unknown. doctor --hub-token grades the same settings with a maintainer's token.

• plan. In a GitLab hub merge request pipeline whose default branch's hub.yml says guard, plan exits 2 when:

  • the merge request was opened by the writer or one of its known_authors;
  • either of them pushed to its source branch since the branch was created;
  • plan cannot tell (fail closed).

  The pushes come from the source project's push events (MergeRequestPushes, the new optional platform.MergeRequestAuditor), which name who pushed, also after someone else re-runs the pipeline. The setting, writer and known authors come from the default branch, so the merge request cannot turn the guard off.

• setup gitlab. Under guard:

  • a hub inside the group of targets is accepted;
  • writer-guard replaces writer-hidden (fails for a Maintainer writer);
  • merge-checks turns on Pipelines must succeed and off skipped pipelines;
  • ci-config pins the CI file, keeping a custom file name;
  • the final check grades hub-guard.

Tests

• Unit:
  • the GitLab driver against the fake, one test per condition: wildcard rule, user allow, group allow, Developers merging, unprotected default, protected tag, unreadable tags, settings;
  • the push events (before and after the branch's creation, an unseen fork);
  • doctor's aggregation and the hub-token grading;
  • plan's guard (author, pusher, unknown pushes, the merge request's own hub.yml turning it off, the default branch turning it off, no auditor, an anonymous reader);
  • setup in guard mode, and PinnedCIConfig.
• Live: TestWriterOnHub (e2e GitLab).
  • doctor gives hub-guard ok.
  • The person's merge request plans clean.
  • The writer's push of its own CI file to it is caught by main's plan.
  • A merge request the writer opens is caught.
  • Unpinning the CI file fails hub-guard.

Docs

• the security model ("A writer on the hub");
• the agents page;
• getting started on GitLab;
• the setup and doctor guides;
• the threat model (a new row, and T3);
• e2e.