Automatize Documentation on GitLab

Using Java and GitLab4J

Photo by Annie Spratt on Unsplash

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.

Technical stack

• Java 11
• GitLab4J

GitLab Structure

• 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.

Milestone Sprint 1

Sprint 1 and its issues

README.md file representing the changelog file visible to the customer

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.

Generate an access token on GitLab

Generated access token

Hands-on

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.

Results

After running the code, a Wiki page is created, as can be observed on the image below.

Wiki page with Sprint’s and issues’ details

Also, a new commit was made and the README.md file was updated.

Automatized commit

Commit content

It is possible to read commit messages and add them to the documentation if needed.

Conclusions

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.