DocC: GitLab Pages Workflow

A while ago I wrote an article about how to use GitHub Actions to automatically build and publish your DocC documentation to GitHub Pages. While there is plenty of documentation on how to do this with GitHub, there aren't many resources on how to do this with GitLab.

In this article I'll walk you through a setup to automatically build a new version of your documentation once your main branch is updated.

This article assumes that you already have a Swift package with DocC documentation and a GitLab repository with a .gitlab-ci.yml file set up.

Preparing your Repository

First of all we need to enable GitLab Pages for our repository. This can be done in the Settings tab under General > Visibility, project features, permissions > Pages.

Now we jump right into our .gitlab-cy.yml file and add a new stage called deploy:

stages:
  - ... # other stages
  - deploy # <-- make sure to add this stage

We also define some variables so that we can easily change them later on if needed:

variables:
  SCHEME: "MyPackage" # <-- change this to your scheme name
  DESTINATION: "generic/platform=iOS" # <-- change this to your desired destination
  BASE_PATH: "my-package" # <-- Usually a lowercased version of your package name
  OUTPUT_PATH: "./public" # <-- change this to your desired output path

Creating the Workflow

Now we can create the actual job that builds our documentation and publishes it to GitLab Pages every time our main branch is updated.

The job must be named pages in order to work. GitLab Pages will automatically pick up this job and publish the output folder as a static website.

pages: # <-- important: this job needs to be named "pages"
  ... # configure your build environment
  stage: deploy 
  # build the documentation using xcodebuild docbuild:
  script: 
    - |
      set -o pipefail && \
      xcodebuild clean docbuild \
        -scheme $SCHEME \
        -destination $DESTINATION \
        OTHER_DOCC_FLAGS="--transform-for-static-hosting \
          --hosting-base-path $BASE_PATH \
          --output-path $OUTPUT_PATH" \
      | xcbeautify
  # add the public folder as an artifact
  artifacts:
    paths:
      - public 
  # only run this when the main branch is updated
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

As you can see we use xcodebuild docbuild to build our documentation and pass in our environment variables we created earlier. We also pipe the output to xcbeautify to make the output more readable. This is not required but highly recommended. You can install xcbeautify using brew install xcbeautify.

You can also use the swift-docc-plugin to build your documentation. However this only supports macOS deployment targets for now. See the official documentation for more information.

We then add our output folder as an artifact. GitLab Pages will then automatically publish this folder once the job succeeds.

Finally we add a rule to only run this job when the main branch is updated.

Accessing the Documentation

Once the job succeeds, you can access your documentation by navigating to the Deploy tab in your repository and clicking on the Pages section.

There you should see a link to your published documentation.

However you need to append <BASE_PATH>/documentation/<SCHEME>/ to the url to access your documentation.

Note that both the BASE_PATH and SCHEME are case-sensitive and need to be lowercased.

Conclusion

That's it! You successfully deployed your DocC documentation to GitLab Pages for your team to access. Make sure to add the link to the documentation to your README.md file so that everyone can easily find it.

If you have any questions or feedback, feel free to reach out to me on X (formerly Twitter) and also make sure to follow me there to stay up to date with my latest articles.

You might want to checkout my corresponding article on how to automatically build and publish your DocC documentation to GitHub Pages too.

In case you found this article helpful, please consider sharing it with others. Thanks for reading!