ghstat 0.3.1
Command-line application to get or set github commit status.
License: MIT
Keywords: github,status,api,json,client,ci,rest,bamboo,travis,jenkins,teamcity,command

.. image:: https://img.shields.io/pypi/v/ghstat.svg
   :target: https://pypi.python.org/pypi/ghstat
   :alt: Latest Version

.. image:: https://pypip.in/license/ghstat/badge.svg
   :alt: License

.. image:: https://img.shields.io/pypi/dm/ghstat.svg
   :target: https://pypi.python.org/pypi/ghstat
   :alt: Downloads

.. image:: https://landscape.io/github/jquast/ghstat/master/landscape.svg
   :target: https://landscape.io/github/jquast/ghstat/master
   :alt: Code Health

============
Introduction
============

This command-line application is mainly for continuous build and
integration environments.  It allows providing all of the details
necessary to mark the status of a commit.  For pull requests, it
may read "All is Well" or "Merge with Caution" with an optional
hyperlink to the CI build server, and optional description of
the build failure.

This is done using the Github v3 API.

This is not a very serious package, there are not any plans to advance
it further. It was authored because existing github python client
packages such as *pygithub3* did not offer the ability to communicate
with the 'statuses' api endpoints, and it is preferred to provide
well-readable command-line arguments in the build script than to use
curl directly.

Installation
------------

The stable version of this package is maintained on pypi, install using pip::

    pip install ghstat

Generate a personal access token, https://github.com/settings/applications,
enabling scope *repo:status* and *public_repo* or *private_repo*, respectively.

Use this token for the `--token` parameter, or as the environment variable ``GITHUB_APP_TOKEN``

Examples
--------

Failing a build on github.com::

    ghstat.py set --token 0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d \
                  --commit 72b74be0de46392a05d8f470b64272b8036e63f8 \
                  --user jquast --repo ghstat --state success

Retrieving the status of a commit as json data to stdout::

   ghstat.py get --token 0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d \
                 --commit 72b74be0de46392a05d8f470b64272b8036e63f8 \
                 --user jquast --repo ghstat

Linking to a private bamboo and github enterprise account::

    ghstat.py set --token 0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d0d \
                  --commit 0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a \
                  --user jquast \
                  --repo ghstat \
                  --state success \
                  --description 'build successful' \
                  --target-url 'https://bamboo.mycorp.com/browse/PROJ-BUILD10-1' \
                  --base-url 'https://github.mycorp.com/api/v3/'

Others
------

githubdate_: Same thing, only it uses an .ini file instead of cmd-line parameters.

Changes
-------

0.3.1
  * New API argument, --context="ci/teamcity" to `distinguish multiple 
    sources <https://developer.github.com/changes/2014-03-27-combined-status-api/>`_.
    Contributed by `@kad <https://github.com/kad>`_ in `PR 3
    <https://github.com/jquast/ghstat/pull/3>`_

0.3.0
  * For descriptions of length greater than 140, truncate and emit a warning
    to standard error. It will be changed to a length of 140 ending in text
    marker `` (...)``.

0.2.0
  * Support python 3
  * Support token as environment value ``GITHUB_APP_TOKEN``
  * Resolve IndexError when retrieving status for a commit without any.

0.1.0
  * Initial release to pypi

.. _githubdate: https://github.com/brunobord/githubdate/