1

I have a library with multiple Git branches where I would like to generate an HTML documentation for every branch. Unfortunately, even making sub-directories named like their branch, the pipeline of each branch seems to replace the whole public directory instead of doing additive folder additions.

Is there a way to have each branch contribute to the page without erasing the content contributed by other branches ? Thank you

EDIT with the page generation stage:

pages: image: norionomura/jazzy tags: - ruby script: - swift build - sourcekitten doc --spm-module Lilas > lilas.json - jazzy --clean --min-acl internal --sourcekitten-sourcefile lilas.json --output public artifacts: paths: - public only: - develop
Improve this question
2
  • Can you please provide us a preview of your pipeline ? Commented Oct 30, 2018 at 19:22
  • @AndréDS Do you mean the ci file ? I edited my question with the relevant stage. Commented Oct 31, 2018 at 12:18

2 Answers 2

Reset to default
1

Using cache is the right direction, but the solution needs some side features to be fully satisfying.

With below solution, from GitLab Pages per branch : the no-compromise hack to serve preview pages , you can have these features :

  • main content is exposed on $CI_PAGES_URL and the path is configurable with $CURRENT_CONTENT_PATH
  • Per-branch preview content is exposed on $CI_PAGES_URL/preview, with a homepage to easily navigate to branches content
  • Path to root preview folder is configurable with $EPHEMERAL_BRANCHES_PATH variable to hide preview content by obfuscation
  • Generated pages are associated with environments to take advantage of auto-cleaning on branch deletion
  • To avoid disturbing already existing environments, pages environment are placed under a pages folder
  • If main content has not been generated in current cache, or if the cache has been deleted, an error is triggered, to avoid accidental deletion
  • Deletion job can be triggered manually with any cache path as input, to clean outdated data
  • Code can safely be added to an existing project pipeline without causing trouble with already existing jobs
  • The workflow:rules can be deleted if you already have your own, or updated to match your flow
  • The job must be named pages and the artifact must be a public folder to be deployed to GitLab Pages (or you can use the pages:publish keyword)
workflow: rules: # disable tag pipelines and duplicate MR pipelines - if: $CI_COMMIT_BRANCH variables: EPHEMERAL_BRANCHES_PATH: preview # subpath to ephemeral branches content for preview, anything will work pages: stage: build image: alpine:3.18 cache: key: gitlab-pages paths: [public] before_script: # default available 'tree' app in alpine image does not work as intended - apk add tree # CURRENT_CONTENT_PATH is defined in rules, different between main branch and ephemeral branches - mkdir -p public/$CURRENT_CONTENT_PATH && ls public/$CURRENT_CONTENT_PATH/.. - | # avoid deleting main branch content when cache has been erased if [ "$CI_COMMIT_BRANCH" != "$CI_DEFAULT_BRANCH" ] && [ ! -d public/$CI_DEFAULT_BRANCH ]; then echo -e "💥\e[91;1m Unable to retrieve $CI_DEFAULT_BRANCH generated files from cache ; please regenerate $CI_DEFAULT_BRANCH files first\e[0m" exit 1 fi - rm -rf public/$CURRENT_CONTENT_PATH || true # remove last version of current branch script: - ./generate-my-html.sh --output build-docs || true # insert here your code that generates documentation - mv --verbose build-docs public/$CURRENT_CONTENT_PATH - cd public/$EPHEMERAL_BRANCHES_PATH - tree -d -H '.' -L 1 --noreport --charset utf-8 -T "Versions" -o index.html # generate a root HTML listing all previews for easier access environment: name: pages/$CI_COMMIT_BRANCH action: start url: $CI_PAGES_URL/$CURRENT_CONTENT_PATH on_stop: pages-clean-preview rules: # 'main branch' is exposed at GitLab Pages root - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH variables: CURRENT_CONTENT_PATH: "." # other (short-lived) branches generation are exposed in 'EPHEMERAL_BRANCHES_PATH/branch-name-sanitized' sub path - variables: CURRENT_CONTENT_PATH: $EPHEMERAL_BRANCHES_PATH/$CI_COMMIT_REF_SLUG artifacts: paths: [public] expire_in: 1h pages-clean-preview: stage: build image: alpine:3.18 cache: key: gitlab-pages paths: [public] variables: GIT_STRATEGY: none # git files not available after branch deletion FOLDER_TO_DELETE: preview/$CI_COMMIT_BRANCH # an indirection to allow arbirtraty deletion when launching this job script: - rm -rf public/$FOLDER_TO_DELETE environment: name: pages/$CI_COMMIT_BRANCH action: stop rules: - if: $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH when: manual allow_failure: true
Improve this answer
Sign up to request clarification or add additional context in comments.

Comments

0

Try prepending the following to your .gitlab-ci.yml:

cache: key: "$CI_JOB_NAME" paths: - public

Adding a cache step will tell GitLab to keep the specified paths across builds—each new build will see what the previous ones have produced. The key element causes GitLab to keep the cache across branches, rather than keep a separate branch for each cache.

Of course this has the side effect that your pipelines will no longer start off with a fresh public dir—rather, it will contain whatever the last pipeline left in there. Everything any of your pipelines ever places in public will stay there until explicitly deleted or overwritten—you will need to handle that in some way if the set of artifacs changes between builds.

(Haven’t tried this myself yet, but this is how I understand it works.)

Improve this answer

Comments

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.