GitLab CI Trusted Publisher Docs Are Misleading in Regards to Workflow File Path

[crgwbr]

The trusted publisher docs describe the workflow file path field for Gitlab as follows:

The file path of the publishing workflow, relative to the project's root. This file should exist in the project configured above (external workflows are not supported).

In the security considerations page, the docs add:

The claims defined in an OIDC token are bound to the workflow, meaning that a workflow defined at foo.yml in org/repo cannot impersonate a workflow defined at bar.yml in org/repo.
[…]
Trust the correct workflow: you shouldn't trust every workflow to upload to PyPI; instead, you should isolate responsibility to the smallest (and least-privileged) possible separate workflow. We recommend naming this workflow release.yml.

This makes it seem like the workflow file path field should be set to a the YML file that's included from the top-level .gitlab-ci.yml file. For example, if a project had .gitlab-ci.yml as the top-level CI config, and from that file included ci/release.yml, you would think that workflow file path should be set to ci/release.yml.

However, this isn't the case. The warehouse code compares workflow file path to the path in the ci_config_ref_uri field of the Gitlab CI JWT claim. This field is defined in Gitlab's documentation as follows:

ci_config_ref_uri: The ref path to the top-level pipeline definition, for example, gitlab.example.com/my-group/my-project//.gitlab-ci.yml@refs/heads/main. Introduced in GitLab 16.2. This claim is null unless the pipeline definition is located in the same project.

Thus, since the claim contains the path to the top-level pipeline definition, even if all the release steps are contained in the ci/release.yml, the workflow file path in PyPI must be set to .gitlab-ci.yml to actually work.

[woodruffw]

Thanks for the report @crgwbr!

Yeah, this looks like a mistake in our documentation: ci_config_ref_uri is always going to reference the top-level CI definition (which is typically .gitlab-ci.yml, but can be configured to something different).

I think the docs there were probably copied over from GitHub Actions and its concept of multiple independent workflows in individual files. For GitLab, we should probably just suggest .gitlab-ci.yml as the default workflow path and remove the "minimal scoping" suggestion (since AFAIK GitLab is entirely YAML inclusion based and doesn't have the ability to separate permissions by include).

CC @facutuesca

[facutuesca]

PR open here: #15921