Metadata-Version: 2.1
Name: nittymcpick
Version: 1.1.3
Summary: GitLab bot for custom linting tools to comment MRs
Home-page: https://github.com/priv-kweihmann/nittymcpick
Author: Konrad Weihmann
Author-email: kweihmann@outlook.com
License: UNKNOWN
Description: |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
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Description-Content-Type: text/x-rst
