Retrieving Raw Files via GitLab API
In my company, we use Checkstyle to enforce our internal Java conventions. The Checkstyle configuration file used to be hosted on our public GitHub repository, but since we use self-hosted GitLab internally, we figured it made sense to host it there. However, we couldn’t find an easy way to retrieve raw files having the following requirements in mind:
- The file should be retrievable through a single GET request so we can use the URL in Maven’s Checkstyle Plugin
- The URL should be pretty — without cryptic IDs so it can be clearly visible which GitLab the configuration file is hosted on, what is the file’s location within the project, and which tag/branch/commit we are referring
The GitLab API does give some hints, however we had to do quite a bit of digging to pinpoint a proper format of the URL.
The first step is to create a Personal Access Token that will be used to authenticate to the API. Since we use Jenkins, we normally create a dedicated Jenkins user that is added to most projects, and this user is also used for accessing the Checkstyle configuration. We created a token under this user, as shown in the below screenshot:
Make sure to write down the token, as there is no way to retrieve it later. You can only revoke it when and if needed.
Once you have the token, you can form the URL as follows:
https://[GITLAB_URL]/api/v4/projects/[PROJECT_NAME_OR_ID]/repository/files/[FILE_PATH]/raw?ref=[TAG_OR_BRANCH_OR_COMMIT]&private_token=[PRIVATE_ACCESS_TOKEN]
Note that the file path must be URL encoded, meaning that you will use config%2fcheckstyle.xml if your file is stored in the repository as config/checkstyle.xml, for example. The same applies for project name if you will use it instead of the ID; you must URL encode it.
