nittymcpick 1.2.0
GitLab bot for custom linting tools to comment MRs

|Build status| |PyPI version| |Python version| |Downloads| |Language
grade: Python|

nittymcpick
===========

Your friendly nitpicking GitLab bot

Purpose
-------

This bot does run custom linting tools on receiving a webhook from
GitLab and reporting back its findings as comments to the merge request
diff

Prerequisites
-------------

-  python 3.6+
-  GitLab CE/EE

Setup
-----

Install tool to a machine
~~~~~~~~~~~~~~~~~~~~~~~~~

This machine has to be reachable by the GitLab server via network. In
the following we will assume a local installation on the GitLab Server
itself (``127.0.0.1``)

-  Install via pypi

   .. code:: shell

      pip3 install nittymcpick

Create a GitLab user
~~~~~~~~~~~~~~~~~~~~

-  Go to GitLab with an account that can create users (e.g. ``root``)

   -  **admin/users/new**

      -  **Name** = Nitty McPick
      -  **Username** = nittymcpick
      -  **Email** = foo@localhost (or any other non-exisiting mail
         address)
      -  **Access Level** = Regular

   -  **admin/users/nittymcpick/impersonation_tokens**

      -  **Name** = e.g. Nitty McPick Bot
      -  **Scopes** = **api**, **read_repository**
      -  **IMPORTANT** copy the content of **Your New Impersonation
         Token**

Add bot to the project
~~~~~~~~~~~~~~~~~~~~~~

-  Goto Gitlab with an account that can change project settings

   -  **[username]/[project]/-project_members/**

      -  search **Nitty McPick** at \**GitLabd member or Email address\*
      -  click **Invite**
      -  Change level **Nitty McPick** from **Guest** to **Reporter**

Create a GitLab webhook
~~~~~~~~~~~~~~~~~~~~~~~

-  Goto Gitlab with an account that can change project settings

   -  \**[username]/[project]/-/settings/integrations

      -  **URL**: http://127.0.0.1:8888
      -  **Trigger**: Merge requests events
      -  **SSL verification**: uncheck the box
      -  Click on **Add webhook**

Create a configuration for the bot
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Create a json file like shown at
`config.json.sample <config.json.sample>`__. The file can contain any
number of items

``linter`` section
^^^^^^^^^^^^^^^^^^

+------------+---------------------------------------------------------+
| attribute  | description                                             |
+============+=========================================================+
| name       | name of the linting tool                                |
+------------+---------------------------------------------------------+
| path       | absolute path of binary of the linting tool             |
+------------+---------------------------------------------------------+
| args       | list of additional arguments to be passed to the linter |
+------------+---------------------------------------------------------+
| ret_regex  | regular expression for evaluation of the output of the  |
|            | linter (see `Return Regex <#return-regex>`__)           |
+------------+---------------------------------------------------------+
| tweaks.lin | Add number of lines to the reported output line number  |
| e_count_ad |                                                         |
| just       |                                                         |
+------------+---------------------------------------------------------+
| tweaks.sin | Run each matching file in a single linter instance,     |
| gle_file_e | otherwise all files will be run by a single instance    |
| xec        |                                                         |
+------------+---------------------------------------------------------+

``matches`` section
^^^^^^^^^^^^^^^^^^^

========= ===================================================
attribute description
========= ===================================================
pattern   Regular expression for files that should be checked
========= ===================================================

Return Regex
''''''''''''

The regular expression to extract all the needed data should contain the
following named groups

-  ``severity`` - for the severity of the finding (optional)
-  ``line`` - Line where the findings occured
-  ``message`` - A meaningful message
-  ``file`` - The file where the of the finding

Run the tool
~~~~~~~~~~~~

.. code:: text

   usage: nittymcpick [-h] [--token TOKEN] [--onlynew] [--nowip] [--host HOST]
                      [--port PORT] [--botname BOTNAME]
                      config

   Your friendly linting bot for gitlab

   positional arguments:
     config             config file

   optional arguments:
     -h, --help         show this help message and exit
     --token TOKEN      Access token to use (default:GL_ACCESS_TOKEN from
                        environment)
     --onlynew          Comment only on changes (default:false)
     --nowip            Ignore WIP merge requests (default:false)
     --host HOST        IP to bind to (default:127.0.0.1)
     --port PORT        Port to bind to (default:8888)
     --botname BOTNAME  Username of the bot in GitLab
                        (default:NITTY_MCPICK_USERNAME from env or 'nittymcpick')

e.g. run

.. code:: shell

   export GL_ACCESS_TOKEN=<Impersonation Token from gitlab>
   nittymcpick config.json

now everytime a merge request is opened or changed the tool will run all
the configured linting tools. On a finding it would comment directly to
the MR like this

.. code:: text

   Nitty McPick @nittymcpick · just now
   Reporter

   mytool found a potential error - the code is absolutely insecure

Docker
------

There is an already prepared container available under
``privkweihmann/nittymcpick:latest``

A word on security
------------------

It is heavily advised to run the bot on the gitlab server itself, as
currently only ``http://`` as a webhook protocol is supported.

PRs to enable ``https://`` as welcome!

.. |Build status| image:: https://github.com/priv-kweihmann/nittymcpick/workflows/Python%20package/badge.svg
.. |PyPI version| image:: https://badge.fury.io/py/nittymcpick.svg
   :target: https://badge.fury.io/py/nittymcpick
.. |Python version| image:: https://img.shields.io/pypi/pyversions/nittymcpick
   :target: https://img.shields.io/pypi/pyversions/nittymcpick
.. |Downloads| image:: https://img.shields.io/pypi/dm/nittymcpick
   :target: https://img.shields.io/pypi/dm/nittymcpick
.. |Language grade: Python| image:: https://img.shields.io/lgtm/grade/python/g/priv-kweihmann/nittymcpick.svg?logo=lgtm&logoWidth=18
   :target: https://lgtm.com/projects/g/priv-kweihmann/nittymcpickv/context:python