How to auto deploy doxygen documentation on Gitlab pages

Introduction to deploy doxygen documentation on Gitlab

Gitlab pages service provides a great deployment toolset to auto generate documentation and auto publish changes to the project web page through continuous integration pipelines that can be triggered when several actions occur. This is useful when, for example, you have project that generates documentation with Doxygen (others docs tools are also supported). A script can be added to the repository root directory to compile the documentation from source code comments, generate html version of the docs, and auto upload the result to the corresponding Gitlab page of the project.

Generating doxygen documentation for gitlab project

Create script

Create a new file named: .gitlab-ci.yml in the root directory of your Gitlab project. Use the following template:

image: alpine

pages:
  script:
  - apk update && apk add doxygen graphviz ttf-freefont
  - doxygen docs/doxygen.conf
  - mv docs/html/ public/
  artifacts:
    paths:
    - public
  only:
  - feature/add-gitlab-pages-support

Keywords:

image: the name of the Docker image that is present in the local Docker Engine (list all images with docker images) or any image that can be found at Docker Hub.
pages: tells the script the deploy action will be on gitlab pages
script: instructions steps to be performed on Gitlab's project container
artifacts: job artifacts are a list of files and directories created by a job once it finishes.
only: branch where the action will be triggered. This means if you push commits to any other branch the action won't happen. This is usually set to master to generate only documentation and update it when a stable version, tag and release are published to master branch.

Trigger pipeline

Add the file to the branch you are using (in this example branch is called feature/add-gitlab-pages)

git add .gitlab-ci.yml
git push origin feature/add-gitlab-pages-support

The action will be triggered once the push action ends.

Check pipeline status

Once the push action has finished the auto-deploy process will start automatically, you can check the progress at the CI/CD tab in project settings.

In this tab you will find the information of the latest execution CI/CD pipelines that were executed or that are in progress.

The status column identifies if the job ended successfully or not, if you click it, the log status can be reviewed.

Success: If the pipeline ended correctly you will get a log similar to the following:

Fail: If the pipeline ended with errors you can click the Failed Jobs tab to review the log and check what caused the failure.

Where is the page deployed?

The link for the page can be found at Settings->Pages

Here a custom domain can also be configured, otherwise default gitlab page will be used.

❯