.. bb:reporter:: GitHubCommentPush

GitHubCommentPush
+++++++++++++++++

.. py:currentmodule:: buildbot.plugins.reporters

.. code-block:: python

    from buildbot.plugins import reporters, util

    context = Interpolate("bb/%(prop:buildername)s")
    c['services'].append(reporters.GitHubCommentPush(token='githubAPIToken', context=context))

:class:`GitHubCommentPush` publishes a comment on a GitHub PR using `GitHub Review Comments API <https://developer.github.com/v3/pulls/comments/>`_.

It requires a GitHub API token in order to operate.
By default, the reporter will only comment at the end of a build unless a custom build report generator is supplied.

You can create a token from your own `GitHub - Profile - Applications - Register new application <https://github.com/settings/applications>`_ or use an external tool to generate one.

.. py:class:: GitHubCommentPush(token, context=None, generators=None, baseURL=None, verbose=False)

    :param string token: Token used for authentication. (can be a :ref:`Secret`)
    :type context: renderable string
    :param context: Passed to GitHub to differentiate between statuses.
        A static string can be passed or :class:`Interpolate` for dynamic substitution.
        The default context is ``buildbot/%(prop:buildername)s``.
    :type generators: list of IReportGenerator instances
    :param generators: A list of report generators that will be used to generate reports to be sent by this reporter.
        Currently the reporter will consider only the report generated by the first generator.
    :param string baseURL: Specify the github API endpoint if you work with GitHub Enterprise
    :param boolean verbose: If True, logs a message for each successful status push

Here's a complete example of posting build results as a github comment:

.. code-block:: python

    @util.renderer
    @defer.inlineCallbacks
    def getresults(props):
        all_logs=[]
        master = props.master
        steps = yield props.master.data.get(
            ('builders', props.getProperty('buildername'), 'builds',
            props.getProperty('buildnumber'), 'steps'))
        for step in steps:
            if step['results'] == util.Results.index('failure'):
                logs = yield master.data.get(("steps", step['stepid'], 'logs'))
                for l in logs:
                    all_logs.append('Step : {0} Result : {1}'.format(
                                        step['name'], util.Results[step['results']]))
                    all_logs.append('```')
                    l['stepname'] = step['name']
                    l['content'] = yield master.data.get(("logs", l['logid'], 'contents'))
                    step_logs = l['content']['content'].split('\n')
                    include = False
                    for i, sl in enumerate(step_logs):
                        all_logs.append(sl[1:])
                    all_logs.append('```')
        return '\n'.join(all_logs)

    generator = BuildStatusGenerator(message_formatter=MessageFormatterRenderable(getresults))
    c['services'].append(GitHubCommentPush(token='githubAPIToken', generators=[generator]))