From ecddde665ce9314d4e39733499c140184e5bc630 Mon Sep 17 00:00:00 2001 From: janis Date: Wed, 14 Jun 2023 11:09:02 +0200 Subject: [PATCH 1/5] Add the documentation about the new root folder config This updates the documentation to reflect the new ability to customize the pages root folder, effectively enabling that feature in GitLab. Changelog: added --- doc/user/project/pages/introduction.md | 26 +++++++++++++++++++++++-- doc/user/project/pages/public_folder.md | 6 ++++-- 2 files changed, 28 insertions(+), 4 deletions(-) diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 73bfe018a7d3a8..164de47545ccd2 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -23,8 +23,6 @@ In brief, this is what you need to upload your website in GitLab Pages: 1. Domain of the instance: domain name that is used for GitLab Pages (ask your administrator). 1. GitLab CI/CD: a `.gitlab-ci.yml` file with a specific job named [`pages`](../../../ci/yaml/index.md#pages) in the root directory of your repository. -1. A directory called `public` in your site's repository containing the content - to be published. 1. GitLab Runner enabled for the project. ## GitLab Pages on GitLab.com @@ -278,6 +276,30 @@ instead. Here are some examples of what happens given the above Pages site: When `public/data/index.html` exists, it takes priority over the `public/data.html` file for both the `/data` and `/data/` URL paths. +## Customizing the default folder + +By default, GitLab Pages expects the files that should be accessible by +the browser to be in a root-level folder called `public`. With GitLab 16.10 +we've added the ability to change that folder by adding a `publish` +property to your Pages job configuration inside `.gitlab-ci.yml`. The +following example would use a folder named `dist` instead: + +```yaml +pages: + script: + - npm run build + artifacts: + paths: + - dist + publish: dist +``` + +**Why do I need to specify both `artifacts.paths` and `publish`?** +This example instructs GitLab to upload a folder named `dist` to the +job's artifacts and then, of those artifacts, to publish `dist` with Pages". +You could use this to store other artifacts (e.g. build verification files) +that should not be accessible via Pages. + ## Known issues For a list of known issues, see the GitLab [public issue tracker](https://gitlab.com/gitlab-org/gitlab/-/issues?label_name[]=Category%3APages). diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md index 6ee8ea17aee106..586416853e5fe2 100644 --- a/doc/user/project/pages/public_folder.md +++ b/doc/user/project/pages/public_folder.md @@ -6,9 +6,11 @@ group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Pages public folder **(FREE)** +# GitLab Pages public folder (up to v16.10) **(FREE)** -All the files that should be accessible by the browser must be in a root-level folder called `public`. +For GitLab Pages versions <= 16.0 all files that should be accessible by +the browser must be in a root-level folder called `public`. For newer +versions you can [change the folder using the `publish` property inside your pages job config](introduction.md#customizing-the-default-folder). Follow these instructions to configure the `public` folder for the following frameworks. -- GitLab From 76310ea8786039894f14d1e3c70086378294bf4a Mon Sep 17 00:00:00 2001 From: janis Date: Thu, 15 Jun 2023 15:26:30 +0200 Subject: [PATCH 2/5] Apply reviewer suggestions --- doc/user/project/pages/introduction.md | 25 ++++++++++++++----------- doc/user/project/pages/public_folder.md | 6 ++---- 2 files changed, 16 insertions(+), 15 deletions(-) diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 164de47545ccd2..c2943549052383 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -276,13 +276,17 @@ instead. Here are some examples of what happens given the above Pages site: When `public/data/index.html` exists, it takes priority over the `public/data.html` file for both the `/data` and `/data/` URL paths. -## Customizing the default folder +## Customize the default folder -By default, GitLab Pages expects the files that should be accessible by -the browser to be in a root-level folder called `public`. With GitLab 16.10 -we've added the ability to change that folder by adding a `publish` -property to your Pages job configuration inside `.gitlab-ci.yml`. The -following example would use a folder named `dist` instead: +> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/859) in GitLab 16.1. + +By default, the [artifact](../../../ci/jobs/job_artifacts.md) folder +that contains the static files of your site needs to have the name `public`. + +To change that folder name to any other value, add a `publish` property to your +`pages` job configuration in `.gitlab-ci.yml`. + +The following example publishes a folder named `dist` instead: ```yaml pages: @@ -294,11 +298,10 @@ pages: publish: dist ``` -**Why do I need to specify both `artifacts.paths` and `publish`?** -This example instructs GitLab to upload a folder named `dist` to the -job's artifacts and then, of those artifacts, to publish `dist` with Pages". -You could use this to store other artifacts (e.g. build verification files) -that should not be accessible via Pages. +Note that you must specify the directory to be deployed with Pages both +as an artifact, and under the `publish` directive, if using a folder name other +than `public`. The reason you need both is that you can define multiple paths +as artifacts, and GitLab doesn't know which one you want to deploy. ## Known issues diff --git a/doc/user/project/pages/public_folder.md b/doc/user/project/pages/public_folder.md index 586416853e5fe2..68023b87560c47 100644 --- a/doc/user/project/pages/public_folder.md +++ b/doc/user/project/pages/public_folder.md @@ -6,11 +6,9 @@ group: Knowledge info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- -# GitLab Pages public folder (up to v16.10) **(FREE)** +# GitLab Pages public folder **(FREE)** -For GitLab Pages versions <= 16.0 all files that should be accessible by -the browser must be in a root-level folder called `public`. For newer -versions you can [change the folder using the `publish` property inside your pages job config](introduction.md#customizing-the-default-folder). +> With GitLab 16.1 we introduced the ability to configure the published folder in `.gitlab-ci.yml`, so you longer need to change your framework config. For more information, see how to [set a custom folder to be deployed with Pages](introduction.md#customize-the-default-folder). Follow these instructions to configure the `public` folder for the following frameworks. -- GitLab From c801b02195705f27fcce244248efc1d0eb01ec01 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 16 Jun 2023 10:48:25 +0000 Subject: [PATCH 3/5] Apply 1 suggestion(s) to 1 file(s) --- doc/user/project/pages/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index c2943549052383..0ade8fee40f80f 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -299,7 +299,7 @@ pages: ``` Note that you must specify the directory to be deployed with Pages both -as an artifact, and under the `publish` directive, if using a folder name other +as an artifact, and under the `publish` property, if using a folder name other than `public`. The reason you need both is that you can define multiple paths as artifacts, and GitLab doesn't know which one you want to deploy. -- GitLab From 607bd76f3e5b833a7fb49f52467ea1c7a689fad7 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Tue, 20 Jun 2023 08:43:02 +0000 Subject: [PATCH 4/5] Apply 1 suggestion(s) to 1 file(s) --- doc/user/project/pages/introduction.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 0ade8fee40f80f..b4493383b331c6 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -298,9 +298,9 @@ pages: publish: dist ``` -Note that you must specify the directory to be deployed with Pages both -as an artifact, and under the `publish` property, if using a folder name other -than `public`. The reason you need both is that you can define multiple paths +If you're using a folder name other than `public`you must specify +the directory to be deployed with Pages both as an artifact, and under the +`publish` property. The reason you need both is that you can define multiple paths as artifacts, and GitLab doesn't know which one you want to deploy. ## Known issues -- GitLab From 49715c65a674949b9fcfbc1a9e091cca8bfdb74e Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Tue, 20 Jun 2023 11:00:04 +0200 Subject: [PATCH 5/5] Document the environment variable --- doc/administration/pages/index.md | 21 +++++++++++++++++++++ doc/user/project/pages/introduction.md | 8 +++++++- 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index e86726524d068b..459a4dcc6a388c 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -590,6 +590,27 @@ gitlab_pages['redirects_max_path_segments'] = 50 gitlab_pages['redirects_max_rule_count'] = 2000 ``` +## Use environment variables + +You can pass an environment variable to the Pages deamon, for example +to enable a feature flag. + +For example, to enable the configurable directory feature: + +1. Edit `/etc/gitlab/gitlab.rb`: + + ```ruby + gitlab_pages['env'] = { + 'FF_CONFIGURABLE_ROOT_DIR' => "true" + } + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + ## Activate verbose logging for daemon Follow the steps below to configure verbose logging of GitLab Pages daemon. diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index b4493383b331c6..1aef5bd304019f 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -278,7 +278,13 @@ for both the `/data` and `/data/` URL paths. ## Customize the default folder -> [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/859) in GitLab 16.1. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-pages/-/merge_requests/859) in GitLab 16.1 with a Pages flag named `FF_CONFIGURABLE_ROOT_DIR`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/1073) in GitLab 16.1. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the Pages feature flag](../../../administration/pages/index.md#use-environment-variables) +`FF_CONFIGURABLE_ROOT_DIR="true"`. On GitLab.com, this feature is available. By default, the [artifact](../../../ci/jobs/job_artifacts.md) folder that contains the static files of your site needs to have the name `public`. -- GitLab