# 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

## 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 [dateparser](https://github.com/scrapinghub/dateparser) when task is due | `in one week` |
| `labels`   | Array of labels to assign to the created issue |    |
| `confidential` | Set created issue as confidential | `false` |
| `schedule` | A [crontab](https://linux.die.net/man/5/crontab)-like schedule defining when the task has to be scheduled | `@weekly`  |
| `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:

```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:

```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:

```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.
