GitLab Issue Bot for Isochronal Heads-up Monitoring

About

This bot can be used to periodically create issues in a GitLab project. It uses an arbitrary set of issue templates and a schedule configuraiton to create matching issues.

gibihm was developed at Tecids e.V. for the scenario of managing infrastructure in a GitLab project, and the need for creating issues / to-dos for periodic maintenance tasks

The name

Man bräuchte ein Tool, in das man Templates mit Checklisten und so 'ne Art crontab schmeißt, und dann gib ihm!

In English, freely translated:

One could use a tool to throw templates with checklists and some kind of crontab at, and off it goes!

Usage

General

The bot's configuration lives entirely inside the project the bot will be used in. To start using the bot in a project, invite the bot user to the project. The bot user is a regular GitLab user.

Add templates and a schedule configuration to your repository, as described below. You can find an example project in the example/ directory.

Defining tasks

Tasks are defined as issue templates. For every kind of tasks that has to be scheduled, a template has to be created. Ideally, the template contains a good description on what has to be done, including a checklist of action items for the task's completion.

Scheduling tasks

The schedule is a YAML document living either at .gitlab/issue_schedule.yaml or .issue_schedule.yaml. It must contain an array of dictionaries, each containing the following keys:

Key Description Default

template Base filename (without .md) of the issue template to
use

title Title for the issue to create

assignee User name of responsible user

due Date expression (parsable by in one week dateparser
when task is due

labels Array of labels to assign to the created issue

confidential Set created issue as confidential false

schedule A crontab-like @weekly schedule defining when the task has to be scheduled

tag Short tag to identify issues related to this task Same as template

Configuration

The bot is configured through environment variables.

Variable Description Default

GIBIHM_API_URL URL of GitLab v4 API endpoint Value of CI_API_V4_URL GIBIHM_API_TOKEN Access Token with api and read_user scopes

Installation

You can either use the bot from a Docker image directly in GitLab CI (see below), or install it whereever you want and run it

Installing and running using pip

Installation from PyPI using pip and running is straightforward:

pip3 install gibihm

export GIBIHM_API_URL=https://gitlab.example.com
export GIBIHM_API_TOKEN=Foo_Bar_Token

gibihm

Installing and running using Docker

The bot is also available using Docker:

docker pull natureshadow/gibihm
docerk run \
    -e GIBIHM_API_URL=https://gitlab.example.com-it \
    -e GIBIHM_API_TOKEN=Foo_Bar_Token \
    natureshadow/gibihm 

Running for a single project

Normally, the bot will operate on all projects its user is a member of.

You can pass it a numeric project ID using the --project-id command-line argument to run for only one project.

Running from project CI

If you do not want to use a site-wide installation, but rather add the bot to a single project, you can configure and run it directly in GitLab CI.

A minimal .gitlab-ci.yml looks like this:

schedule_issues:
  only:
    - schedules
  image: natureshadow/gibihm
  script: [ "true" ]

In your project settings. add the GIBIHM_API_TOKEN variable.

You can then use GitLab's Pipeline schedules to periodically run the bot and schedule your issues.