An Overview of the Statuses API in github3.py

GitHub's Statuses API is one of the more popular recent additions to GitHub's large and all-encompassing API. This API allows you to create and list statuses like those created by popular Continuous Integration services (e.g., Jenkins, Travis CI, etc.). github3.py provides unfettered access to these functions and the following should help explore that functionality.

Listing Statuses Associated with a Reference


In [1]:
import github3


repository = github3.repository('sigmavirus24', 'github3.py')

With a repository object, we can now retrieve the statuses from a number of different commit-like objects which we can retrieve using the repository's commit method.


In [2]:
commit = repository.commit('9df71a9772d5f43e332c855a32d4689f28289989')
tag = repository.commit('0.9.3')
branch = repository.commit('stable/0.9')

Each of these bindings now hold a reference to a different RepoCommit object and each has a statuses method. We can retrieve statuses about each reference and print them.


In [3]:
for ref in (commit, tag, branch):
    print('Showing statuses for "{0.sha}" ({0.html_url})'.format(ref))
    for status in ref.statuses():
        print("    State: {0.state}; Description: {0.description}; Context: {0.context}".format(status))


Showing statuses for "9df71a9772d5f43e332c855a32d4689f28289989" (https://github.com/sigmavirus24/github3.py/commit/9df71a9772d5f43e332c855a32d4689f28289989)
    State: success; Description: The Travis CI build passed; Context: continuous-integration/travis-ci
    State: pending; Description: The Travis CI build is in progress; Context: continuous-integration/travis-ci
    State: pending; Description: The Travis CI build is in progress; Context: continuous-integration/travis-ci
Showing statuses for "52a3f30e05cf434285e775979f01f1a8355049a7" (https://github.com/sigmavirus24/github3.py/commit/52a3f30e05cf434285e775979f01f1a8355049a7)
    State: success; Description: The Travis CI build passed; Context: continuous-integration/travis-ci
    State: success; Description: The Travis CI build passed; Context: continuous-integration/travis-ci
    State: pending; Description: The Travis CI build is in progress; Context: continuous-integration/travis-ci
    State: pending; Description: The Travis CI build is in progress; Context: continuous-integration/travis-ci
    State: pending; Description: The Travis CI build is in progress; Context: continuous-integration/travis-ci
    State: pending; Description: The Travis CI build is in progress; Context: continuous-integration/travis-ci
Showing statuses for "6e97462ade3d8855644296e7a44b5463c7b222a6" (https://github.com/sigmavirus24/github3.py/commit/6e97462ade3d8855644296e7a44b5463c7b222a6)
    State: success; Description: The Travis CI build passed; Context: continuous-integration/travis-ci
    State: pending; Description: The Travis CI build is in progress; Context: continuous-integration/travis-ci
    State: pending; Description: The Travis CI build is in progress; Context: continuous-integration/travis-ci

Listing Combined Status Associated with a Reference


In [1]:
import github3


repository = github3.repository('sigmavirus24', 'github3.py')

With a repository object, we can now retrieve the statuses from a number of different commit-like objects which we can retrieve using the repository's commit method.


In [2]:
commit = repository.commit('9df71a9772d5f43e332c855a32d4689f28289989')
tag = repository.commit('0.9.3')
branch = repository.commit('stable/0.9')

Each of these bindings now hold a reference to a different RepoCommit object and each has a status method. We can retrieve the combined status about each reference and print them.


In [3]:
for ref in (commit, tag, branch):
    print('Showing combined status for "{0.sha}" ({0.html_url})'.format(ref))
    combined_status = ref.status()
    print("    State: {0.state}; Total count: {0.total_count}".format(combined_status))
    print("    Statuses:")
    for status in combined_status.statuses:
        print("        State: {0.state}; Description: {0.description}; Context: {0.context}".format(status))


Showing combined status for "9df71a9772d5f43e332c855a32d4689f28289989" (https://github.com/sigmavirus24/github3.py/commit/9df71a9772d5f43e332c855a32d4689f28289989)
    State: success; Total count: 1
    Statuses:
        State: success; Description: The Travis CI build passed; Context: continuous-integration/travis-ci
Showing combined status for "52a3f30e05cf434285e775979f01f1a8355049a7" (https://github.com/sigmavirus24/github3.py/commit/52a3f30e05cf434285e775979f01f1a8355049a7)
    State: success; Total count: 1
    Statuses:
        State: success; Description: The Travis CI build passed; Context: continuous-integration/travis-ci
Showing combined status for "c4c3fc3ea3b56152303a1a856d7d7fe220b9b8b4" (https://github.com/sigmavirus24/github3.py/commit/c4c3fc3ea3b56152303a1a856d7d7fe220b9b8b4)
    State: failure; Total count: 1
    Statuses:
        State: failure; Description: The Travis CI build failed; Context: continuous-integration/travis-ci/push

Creating a Status for a Reference


In [1]:
import github3
import os

g = github3.login(os.environ['GH_USERNAME'], os.environ['GH_PASSWORD'])
repository = g.repository('sigmavirus24', 'github3.py')

With our repository object, we can now create a status for an arbitrary commit using the create_status method.


In [2]:
status = repository.create_status(sha='020cfe6422e3b2a0a5ff985c9e1c0aa921555bd8',
                                  state='success',
                                  description='Documentation status',
                                  context='default')
print('Status {0.state} for context {0.context} with description {0.description}'.format(status))


Status success for context default with description Documentation status

We now have a "success" status defined on our commit and can retrieve it by listing statuses (as described above).