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 thepublic
requirement is currently hardcoded). -
At this time the property needs to be defined in addition to
artifacts
. A later iteration will have GitLab treatpublish
as an additionalartifacts
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
- Open a Project in GitLab, then navigate to the Pipeline Editor (e.g. http://localhost:3000/root/html/-/ci/editor)
- Enter the below pipeline definition and confirm the pipeline is valid:
pages:
script:
- echo "foo"
artifacts:
paths:
- dist
publish: dist
- Change the name of the job to anything other than
pages
. Confirm that the pipeline is now invalid. - With the name still something other than
pages
, remove thepublish
property and confirm the pipeline is valid again. - To confirm backwards compatibility, rename the job back to
pages
, this time without thepublish
property. Renameartifact.paths[0]
topublic
. Confirm the job is still valid. (It will also be valid with a value other thanpublic
, but the Pages deployment won't work).
Full Validation
- Ensure your Pages installation is running locally.
- 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:
- Commit the
.gitlab-ci.yml
file. Ensure the pipeline is running. - Verify that the pipeline succeeds.
- 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)