Gatsby's documentation for using Gitlab CI/CD not in sync with Gitlab's template file (./.gitlab-ci.yml)

[ronalde]

LS,

Like Gitlab user @ethanmdavidson discusses on gatsby's starter project in gitlab (in https://gitlab.com/pages/gatsby/-/issues/8), adding the (or a?) Gatsby CI/CD template to an existing Gitlab repository doesn't work.

Steps to reproduce

1. create a new empty Gitlab repo
2. Click + Set up CI/CD
3. Choose Gatsby under Pages in the 'Apply a template' dropdown.

This pulls in the following file contents for ./.gatsby-ci.yml:

# This file is a template, and might need editing before it works on your project.
image: node:latest

# This folder is cached between builds
# http://docs.gitlab.com/ee/ci/yaml/README.html#cache
cache:
  paths:
    - node_modules/

pages:
  script:
    - yarn install
    - ./node_modules/.bin/gatsby build --prefix-paths
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Main problem: this won't build!

This won't build/is invalid, like stated in Gatsby's documentation page on using gitlab ci (in https://github.com/gatsbyjs/gatsby/blob/master/docs/docs/deploying-to-gitlab-pages.md) and fixed in #22572 (one year ago):

--- @theabove/.gitlab-ci.yml
+++ @upstream/.gitlab-ci.yml

cache:
  paths:
    - node_modules/
+    - public/
+    - .cache/

Additional problem

Apart from that, it's seems completely detached from (upstream) Gatsby's documentation page on using Gitlab CI.

Current situation (2021-03-28)

Current diff between the contents for the file in the documentation and the contents used by gitlab (using the method 'Setup CI/CD' like described above):

--- /tmp/template/gitlab/.gitlab-ci.yml	2021-03-28 12:26:23.431682769 +0200
+++ /tmp/template/gatsby/.gatsby-ci.yml	2021-03-28 12:24:57.288453210 +0200
@@ -1,19 +1,22 @@
-## copied from gitlab
-## using the instructions from the Gatsby documentation
+## extracted from
+## https://raw.githubusercontent.com/gatsbyjs/gatsby/master/docs/docs/deploying-to-gitlab-pages.md
 image: node:latest
 
 # This folder is cached between builds
-# http://docs.gitlab.com/ee/ci/yaml/README.html#cache
+# https://docs.gitlab.com/ce/ci/yaml/README.html#cache
 cache:
   paths:
     - node_modules/
+    # Enables git-lab CI caching. Both .cache and public must be cached, otherwise builds will fail.
+    - .cache/
+    - public/
 
 pages:
   script:
-    - yarn install
+    - npm install
     - ./node_modules/.bin/gatsby build --prefix-paths
   artifacts:
     paths:
       - public
-  rules:
-    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+  only:
+    - master

Proposed fix

1. Make and maintain a single .gitlab-ci.yml template file in Gatsby's documentation's directory, for example in https://github.com/gatsbyjs/gatsby/blob/master/docs/docs/deploying-to-gitlab-pages.yml
2. Pull in the contents of that file in the documentation file somehow, replacing the appropriate current content
3. Set up Gatsby's Gitlab repositories to pull in the file created in 1.
4. Set up Gitlab's CI templates logic to pull in the file created in 1.

[ronalde]

@laurieontech Please have a look at #30514 because your improvements of the (sample) contents of ./gitlab-ci.yml in your documentation page, are not used in Gitlab's Gatsby templates. So this enhancement/finding (from one year ago!) is not (even) used in current Gitlab Gatsby CI template, which uses an (even) older variant, which of cource won't build, as you found out here.

Originally posted by @ronalde in #22572 (comment)

[ronalde]

Also see https://gitlab.com/gitlab-org/gitlab/-/issues/220680#note_382758257, in which a related issue is addressed, which results from the detached development flows.