gibihm 0.1.1.post2
GitLab Issue Bot for Isochronal Heads-up Monitoring
License: Apache-2.0
Requires Python: >=3.9,<4.0

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. <https://www.teckids.org>`__ 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 <https://docs.gitlab.com/ee/user/project/description_templates.html>`__.
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     |
|                 | `dateparser <http                         | week``       |
|                 | s://github.com/scrapinghub/dateparser>`__ |              |
|                 | when task is due                          |              |
+-----------------+-------------------------------------------+--------------+
| ``labels``      | Array of labels to assign to the created  |              |
|                 | issue                                     |              |
+-----------------+-------------------------------------------+--------------+
| ``confidential``| Set created issue as confidential         | ``false``    |
|                 |                                           |              |
+-----------------+-------------------------------------------+--------------+
| ``schedule``    | A                                         | ``@weekly``  |
|                 | `crontab <htt                             |              |
|                 | ps://linux.die.net/man/5/crontab>`__-like |              |
|                 | schedule defining when the task has to be |              |
|                 | scheduled                                 |              |
+-----------------+-------------------------------------------+--------------+
| ``tag``         | Short tag to identify issues related to   | Same as      |
|                 | this task                                 | ``template`` |
|                 |                                           |              |
+-----------------+-------------------------------------------+--------------+

Configuration
~~~~~~~~~~~~~

The bot is configured through environment variables.

+----------------------+----------------------+----------------------+
| Variable             | Description          | Default              |
+======================+======================+======================+
| ``GIBIHM_API_URL``   | URL of GitLab v4 API | Value of             |
|                      | endpoint             | ``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:

.. code:: shell

   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:

.. code:: shell

   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:

.. code:: yaml

   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 <https://docs.gitlab.com/ee/ci/pipelines/schedules.html>`__ to
periodically run the bot and schedule your issues.