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
• Example configurations
  • Show build status for all accessible projects
  • Show build status for a single project
  • Show build status for a set of projects
  • How to determine the projects id
• Configuration values
  • projectUrl
  • url
  • token
  • project
  • memberOnly
• Modify the output
• Modify the reporter

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