Only rebuild documentation when source has changed

Migrated issue

Reported by: jonathan1055

Related to !447 (merged)

Problem/Motivation

From this thread https://drupal.slack.com/archives/C51GNJG91/p1739624656083539 I realised that the rules for contrib pages are different from what we have in Gitlab Templates own pages job.

The rules for running the Contrib pages job are

  rules:
    - *skip-pages-rule
    - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH
      when: never
    - exists:
        - mkdocs.yml
      when: on_success

This only checks the branch name and that a mkdocs specification file exists, it does not check that a push has triggered the pipeline. This means we are wasting resources by rebuilding and deploying pages on every scheduled pipeline even when the docs source has not been changed. Also the pages and deploy jobs are running unnecessarily in downstream pipelines - https://git.drupalcode.org/project/keycdn/-/pipelines/444579

For Gitlab Templates pages that rule is different:

  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CI_PIPELINE_SOURCE == "push" && $CI_PROJECT_ROOT_NAMESPACE == "project"
      changes:
        - docs/**/*
        - mkdocs.yml 

which means that the documentation is only rebuilt when a change to any page is being committed to the default branch.

Original thread about rebuilding site from scratch in #drupal-infrastructure (these links don't always work)
https://app.slack.com/client/T06GX3JTS/C51GNJG91
https://drupal.slack.com/archives/C51GNJG91/p1739624656083539

Discussion in #gitlab-templates-development
https://app.slack.com/client/T06GX3JTS/C08CJ9K74MB
https://drupal.slack.com/archives/C08CJ9K74MB/p1739788321405979

Proposed resolution

Use conditional checks on pipieline source and changed docs files, similar to what is done in Gitlab Templates own job. The rule would also check that the push is on the default branch, and that the mkdocs.yml file exists:

    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CI_PIPELINE_SOURCE == "push" && $CI_PROJECT_ROOT_NAMESPACE == "project"
      exists:
        - mkdocs.yml
      changes:
        - docs/**/*
        - mkdocs.yml

Remaining tasks

  • Enhance the rule [done]
  • Update the documentation [done]
  • Complete the testing scenarios [done]

Testing

  1. Push a change that has a docs edit - the pages job should run - yes it does
  2. Push a commit that only changes mkdocs.yml - the job runs as required
  3. Push a change that does not include a doc edit - the job correctly does not run
  4. Check scheduled pipeline does not run pages - correct, on Tues 20th there was no pages job
  5. UI pipeline - there is no pages job
  6. Project is running pipelines but has no documentation files. Then a docs folder and mkdocs.yml file are added - the pages job is run as expected
  7. Project has an existing docs folder only. There is no pages job
  8. Project has an existing docs folder and mkdocs.yml file but is not running CI. Then a CI file is added. The job is not run

Related issue: Issue #3426311

Edited by drupalbot