README
i3-status-gitlab
Build status monitor for gitlab-ci and i3-status.
This module for i3-status displays the build status from your Gitlab Ci Server projects. Projects without builds or pending or running builds will be ignored.
Table of content
Installation
cd ~/my-i3-status # go to the directory you installed i3-status in
npm install --save i3-status-gitlab
Example configurations
You need to provide the url to your gitlab server and a private token. See token config how to retrieve your private token.
Show build status for all accessible projects
This config will show the status of all projects you can access and are a member of with the gitlab token you provided.
- name: gitlab
module: i3-status-gitlab
interval: 300 # refresh each 5 minutes
label: ci
projectUrl: https://git.yourserver.tld
url: https://git.yourserver.tld/api/v3
token: 'secretToken' #see below how to get one
If you want to show all projects you have read access to define:
- name: gitlab
module: i3-status-gitlab
[...]
memberOnly: false
Show build status for a single project
This config will show the status of a single project only.
- name: gitlab
module: i3-status-gitlab
interval: 300 # refresh each 5 minutes
label: 'Project A'
projectUrl: https://git.yourserver.tld
url: https://git.yourserver.tld/api/v3
token: 'secretToken' #see below how to get one
project: 23 #change to your project id
Show build status for a set of projects
This config will show the status of multiple projects.
- name: gitlab
module: i3-status-gitlab
interval: 300 # refresh each 5 minutes
label: 'ci'
projectUrl: https://git.yourserver.tld
url: https://git.yourserver.tld/api/v3
token: 'secretToken' #see below how to get one
project:
- 23 #change to your project ids
- 24
- 25
How to determine the projects id
Login to your gitlab server and open https://git.yourserver.tld/api/v3/projects/?simple=true&page=1&per_page=999999 in a browser. Then search for your project name and find the "id": text in front of the search result.
Configuration values
Common configuration values like label and interval are described in the i3-status documentation
projectUrl
mandatory. Provide the URL of your gitlab server start page.
url
mandatory. Provide the URL of your gitlab server api, e.g. https://git.yourserver.tld/api/v3. The url should not end with a slash.
token
mandatory. You need to register a private token for this module. Login to your gitlab server and open the profile settings. Under access tokens create a new personal access token with a name like i3-status.
The token allows access to your projects on gitlab. You should encrypt the value to make more secure. The i3-status documentation tells you how to do this.
project
Project can be
- empty. In this case all projects you have access to are monitored. You can use the memberOnly flag to only show projects you are a member of.
- single id. Only one specific project is monitored
- list of ids. All specified projects are monitored.
memberOnly
This flag is only used if you don't specify any value for project. Instead of reading all accessible projects only the projects you are a member of are read. Default is false.
Modify the output
When you activate the colorize option a successful build state is shown in green and a failed build state in red.
colorize: true
You can define the texts and colors for successful and failed builds. The default text is for successful and for failed builds.
success:
color: '#AAFFAA'
text: all systems are go
failure:
color: '#FFAAAA'
text: hudson, we have a problem
Modify the reporter
If you click on the status a popup will appear (if you added the i3-status-reporter-html, see i3-status documentation). You can modify the output of the reporter. The following example will show all build projects ordered by the projects name.
report:
dots: true # display circles in front of the projects name, default = true
showSuccess: true # show failed and successfull builds, default = false
sortByName: true # sort the projects by name, default = false