[FF] ci_spec_include_own_context - resolve spec:include in the declaring file context

Summary

Roll out the fix currently behind the ci_spec_include_own_context feature flag, introduced in !249592 (merged).

With the flag on, a spec:include location resolves against the context of the file that declares spec, not the file that added the include: keyword.

The flag is a beta flag. The measurement period plus holding GitLab Self-Managed and GitLab Dedicated back is longer than the two month lifespan of a derisk flag, and an on-premise install needs a way to turn the change off.

Note

Process and guidance live in the docs. This issue is just the commands and a place to track the rollout. "Rolling out" means incrementally enabling the flag on GitLab.com to validate stability. It is not the same as releasing the feature, which happens when the flag is removed. Feature flag controls · Feature flag lifecycle

What could go wrong?

The flag changes behavior that some pipelines already depend on. Two cases:

  1. A consumer project that overrides an upstream template's inputs by placing a file at the path the upstream uses. That stops working.
  2. A local location inside a file fetched with include:remote or include:template. It currently reads from the project running the pipeline. With the flag on it reports that there is no repository to resolve against.

During a percentage rollout the flag is evaluated with the project that runs the pipeline, so every file in one pipeline gets the same answer. Across pipelines it varies: a template in one project can resolve one way for a consumer inside the rollout percentage and the other way for a consumer outside it. Expect reports of the form "your template broke for us but not for them". Enabling for named projects or groups first avoids this.

Blast radius is measured before enabling. !249592 (merged) ships a log line that fires only for the files the flag would change. Query on event: ci_spec_include_diverging_context. The payload also has the caller project_id, the location, the include_type, and the declaring_project_id.

Rollout

Do not enable until the log data is in.

  1. Wait at least two weeks after !249592 (merged) reaches production.
  2. Query the event token above. Count distinct projects.
    1. https://log.gprd.gitlab.net/app/r/s/RGTW9 - logs
    2. Lens visualisation
  3. If usage is low or absent, start the percentage rollout below. If usage is high, stop and reassess on #590532.

GitLab Self-Managed and GitLab Dedicated stay off until the next major version, so anyone relying on the old behavior gets a clear upgrade boundary instead of a mid-cycle change.

Run all production /chatops in #production. Background: incremental rollout process, feature actors.

Non-production

/chatops gitlab run feature set ci_spec_include_own_context 50 --actors --dev --pre --staging --staging-ref


/chatops gitlab run feature set ci_spec_include_own_context true --dev --pre --staging --staging-ref

Production - percentage rollout (wait at least 15 min between steps, watch dashboards):

/chatops gitlab run feature set ci_spec_include_own_context <percentage> --actors

Or target specific actors instead:

/chatops gitlab run feature set --project=gitlab-org/gitlab,gitlab-org/gitlab-foss ci_spec_include_own_context true


/chatops gitlab run feature set --group=gitlab-org,gitlab-com ci_spec_include_own_context true


/chatops gitlab run feature set --user=oyakovenko-ext ci_spec_include_own_context true

Before global rollout

Confirm the relevant gotchas before going to 100%. See enabling a feature for GitLab.com:

Cleanup

Remove the flag once deemed stable. See cleaning up. Remove the flag, its YAML definition, and the log line added for the measurement, then:

/chatops gitlab run release check <merge-request-url> <milestone>


/chatops gitlab run feature delete ci_spec_include_own_context --dev --pre --staging --staging-ref --production

Rollback

/chatops gitlab run feature set ci_spec_include_own_context false                                         # production


/chatops gitlab run feature set ci_spec_include_own_context false --dev --pre --staging --staging-ref     # non-production


/chatops gitlab run feature delete ci_spec_include_own_context --dev --pre --staging --staging-ref --production  # remove entirely
Edited by Oleg Yakovenko