OpenAPI documentation generation with registry enabled causes contributor pipeline failures

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

• Close this issue

Summary

When generating OpenAPI documentation with bin/rake gitlab:openapi:generate on a local development environment with container registry enabled, extra registry scopes are injected into the documentation. This causes the openapi-doc-check job in CI pipelines to fail when such documentation is committed.

Steps to reproduce

1. Have local GDK with container registry enabled in gdk.yml
2. Run bin/rake gitlab:openapi:generate
3. Commit and push the changes to a branch
4. Observe the openapi-doc-check job failure in the pipeline

Problem details

The generated doc/api/openapi/openapi_v2.yaml file incorrectly contains extra read_registry and write_registry scopes in API endpoints such as postApiV4ProjectsIdAccessTokensSelfRotate. This only happens when the registry is enabled locally, leading to inconsistent documentation generation between different development environments.

Impact

• Pipeline failures in the openapi-doc-check job
• Developers need to manually clean up the scopes after generation
• Inconsistent documentation between environments

Evidence

• Example failing pipeline: https://gitlab.com/gitlab-community/gitlab/-/jobs/9598695594
• Example fix commit (removing the extra scopes): !185065 (a166cee7)

Workaround

To generate OpenAPI documentation that will pass CI checks, developers need to:

1. Disable the registry in gdk.yml:

   registry:
     enabled: false

2. Run GDK reconfigure:

   gdk reconfigure

3. Then generate the OpenAPI documentation:

   bin/rake gitlab:openapi:generate

This ensures the documentation won't contain the extra registry scopes that cause pipeline failures.