Add a "publish" instruction to the pages job

What does this MR do and why?

This MR adds the new property publish to the CI config of a Pages Job.

Why is this change being made?

The full context: &10126

TL;DR: Currently the static files that GitLab Pages exposes need to be an artifact that contains a folder named public. Since artifacts are a generic pipeline feature (not specific to pages) they will happily accept any path. But Pages itself is more strict and will only expose files if they're in a root folder named public. This info is not included in the pipeline validation. This has always caused a lot of confusion.

But rather than simply adding a pipeline validation, this MR is the first step in removing the requirement altogether.

How is it implemented?

This MR introduces the publish property as part of a pages job.

This is a single string where users can specify the path to the pages root folder. This does no longer have to be public

Caveats

• At this time the property does not have any effect. A later MR will store this information as a pages_deployment property and expose it with the internal Pages API for GitLab Pages to utilise (where the public requirement is currently hardcoded).

• At this time the property needs to be defined in addition to artifacts. A later iteration will have GitLab treat publish as an additional artifacts path entry.

Why is this not behind a feature flag?

Because at this time, it does not change existing behaviour. In fact, it does not change any behaviour at all except pipeline validation. The risk of failure introduced by adding the FF overhead is equal to or even greater than the risk of introducing this feature directly, so I've made the conscious decision to not add a FF.

Documentation

This feature will remain undocumented until the actual functionality has been implemented both in the Rails backend and GitLab Pages.

Examples

Before

# .gitlab-ci.yml
pages:
  script:
    - echo "foo"
  artifacts:
    paths:
      - public

After

# .gitlab-ci.yml
pages:
  script:
    - echo "foo"
  artifacts:
    paths:
      - dist
  publish: dist

How to set up and validate locally

Quick validation

1. Open a Project in GitLab, then navigate to the Pipeline Editor (e.g. http://localhost:3000/root/html/-/ci/editor)
2. Enter the below pipeline definition and confirm the pipeline is valid:

pages:
  script:
    - echo "foo"
  artifacts:
    paths:
      - dist
  publish: dist

3. Change the name of the job to anything other than pages. Confirm that the pipeline is now invalid.
4. With the name still something other than pages, remove the publish property and confirm the pipeline is valid again.
5. To confirm backwards compatibility, rename the job back to pages, this time without the publish property. Rename artifact.paths[0] to public. Confirm the job is still valid. (It will also be valid with a value other than public, but the Pages deployment won't work).

Full Validation

1. Ensure your Pages installation is running locally.
2. Add any HTML file at public/index.html. Example: https://gitlab.com/pages/plain-html

Go through steps 2, 4 and 5 of the "Quick validation" and each time do the following:

1. Commit the .gitlab-ci.yml file. Ensure the pipeline is running.
2. Verify that the pipeline succeeds.
3. In step 5 you should also see a successful pages deployment (to see the pages deployment's URL, go to Settings > Pages)

MR acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

• I have evaluated the MR acceptance checklist for this MR.

Resolves #398143 (closed)