Automate Documentation on GitLab
GitLab is a well-known platform that allows a team to manage projects, to create documentation, pipelines, repositories and more.
It can be used to manage the project’s Sprints and to replace other tools such as Trello or Jira.
When utilized from “end-to-end” during the development cycle, it allows some automatizations, such as to generate documentation or a changelog based on requirements collected and developed during the process.
This article aims to demonstrate how to use the project’s issues or User Stories to generate a changelog, a Wiki page or “readme” file that can be delivered to costumers automatically.
- Java 11
- We have a milestone that is “Sprint 1” and it has issues associated with it, as you can check here.
- We have a README.md file representing a changelog file that will be packed with the application and deployed somewhere, through the pipeline. This file would be mapped to an URL inside the application and it would be available to the costumers through a link.
Setup the integration
On your GitLab profile, go to “Settings” and then “Access Tokens”. Generate an access token with all the checkboxes checked. Click on “Create personal access token” and copy the value of the field “Your new personal access token”.
This token will be used to authenticate on GitLab through a Java application using the library GitLab4J.
Using GitLab4J we will retrieve the latest milestone (it should be the first on the list), read its issues, labels and notes and if they are closed, we will create a new commit on README.md file and a Wiki page.
Let’s inspect the code on my GitHub project that does that.
- Method “generateDocumentation” reads the milestones and its issues.
- Method “getChangelogMessagesFromIssues” reads the issues and its details.
- Method “printIssuesLabels” just print issues’ labels. But it could be used for some filtering, for example, only issues with label “public” should be exported to the documentation.
- Method “printIssuesNotes” retrieves all the comments related to the issue to add them to documentation.
- Method “createCommit” commits to the repository.
After running the code, a Wiki page is created, as can be observed on the image below.
Also, a new commit was made and the README.md file was updated.
It is possible to read commit messages and add them to the documentation if needed.
When GitLab is used to control Sprints and project’s requirements, it is possible to retrieve information from it and automatize the documentation only by reading the issues’ information.
If the User Stories or issues are well organized and written, no extra effort is needed to achieve this goal.
A simple Java code and GitLab4J library can digest information and thus, a project’s documentation can be automated.