toxicbuild.integrations package


toxicbuild.integrations.exceptions module

exception toxicbuild.integrations.exceptions.AppDoesNotExist[source]

Bases: Exception

exception toxicbuild.integrations.exceptions.AppExists[source]

Bases: Exception

exception toxicbuild.integrations.exceptions.BadRepository[source]

Bases: Exception

exception toxicbuild.integrations.exceptions.BadRequestToGithubAPI[source]

Bases: Exception

exception toxicbuild.integrations.exceptions.BadSignature[source]

Bases: Exception

toxicbuild.integrations.github module

This module implements the integration with Github. It is a GithubApp that reacts to events sent by github webhooks and informs about build statuses using checks.


# When a new installation is created on github we must create a
# installation here.

install = await GithubInstallation.create(github_install_id, user)

# When a push happens or a pull request is created or synchronized
# we update the code here.

await install.update_repository(github_repo_id)

# When a check is rerequested we request a build
await install.repo_request_build(github_repo_id, branch, named_tree)

For information on how to setup the integration, see Integration with Github

class toxicbuild.integrations.github.GithubApp(*args, **kwargs)[source]

Bases: toxicbuild.core.utils.LoggerMixin, mongomotor.document.Document

A GitHub App. Only one app per ToxicBuild installation.

exception DoesNotExist

Bases: mongoengine.errors.DoesNotExist

exception MultipleObjectsReturned

Bases: mongoengine.errors.MultipleObjectsReturned

coroutine classmethod app_exists()[source]

Informs if a github app already exists in the system.

coroutine classmethod create_installation_token(installation)[source]

Creates a auth token for a given github installation

Parameters:installation – An instance of GitHubInstallation
coroutine create_token()[source]

Creates a new token for the github api.


Returns the url for the github app api.

coroutine classmethod get_app()[source]

Returns the app instance. If it does not exist, create it.

coroutine get_jwt_token()[source]

Returns the jwt token for authentication on the github api.

coroutine is_expired()[source]

Informs if the jwt token is expired.

coroutine set_expire_time(exp_time)[source]

Sets the expire time for the jwt token

coroutine set_jwt_token(jwt_token)[source]

Sets the jwt auth token.

validate_token(signature, data)[source]

Validates the incomming data in the webhook, sent by github.


The id of the app in github.


A field wrapper around MongoDB’s ObjectIds.


When auth token for the github api. expires. It must be in UTC


The auth token for the github api.

objects = QuerySet

The private key you generated in github.


The token used to sign the incomming request in the webhook. This must be set in the github app creation page.

class toxicbuild.integrations.github.GithubCheckRun(*args, **kwargs)[source]

Bases: toxicbuild.master.plugins.MasterPlugin

A plugin that creates a check run reacting to a buildset that was added, started or finished.

coroutine run(sender, info)[source]

Runs the plugin.

  • sender – The Repository that is running the plugin.
  • info – The information that is being sent.
events = ['buildset-added', 'buildset-started', 'buildset-finished']

Events that trigger the plugin.


The GithubInstallation that owns the plugin

name = 'github-check-run'

The name of the plugin

no_list = True
run_name = 'ToxicBuild CI'

The name displayed on github.

type = 'notification'

The type of the plugin. This is a notification plugin.

class toxicbuild.integrations.github.GithubInstallation(*args, **kwargs)[source]

Bases: toxicbuild.core.utils.LoggerMixin, mongomotor.document.Document

An installation of the GitHub App. Installations have access to repositories and events.

exception DoesNotExist

Bases: mongoengine.errors.DoesNotExist

exception MultipleObjectsReturned

Bases: mongoengine.errors.MultipleObjectsReturned


alias of GithubApp

coroutine classmethod create(github_id, user)[source]

Creates a new github app installation. Imports the repositories available to the installation.

  • github_id – The installation id on github
  • user – The user that owns the installation.
coroutine delete(*args, **kwargs)[source]

Deletes the installation from the system

coroutine get_repo(repo_full_name)[source]

Get the repository (if available to the installation) from the github api.

Parameters:github_repo_id – The full name of the repository on github.
coroutine import_repositories()[source]

Imports all repositories available to the installation.

coroutine import_repository(repo_info, clone=True)[source]

Imports a repository from GitHub.

Parameters:repo_info – A dictionary with the repository information.
coroutine list_repos()[source]

Lists all respositories available to an installation. Returns a list of dictionaries with repositories’ information

coroutine remove_repository(github_repo_id)[source]

Removes a repository from the system.

Parameters:github_repo_id – The id of the repository in github.
coroutine repo_request_build(github_repo_id, branch, named_tree)[source]

Requests a new build.

  • github_repo_id – The id of the repository in github.
  • branch – The name of the branch to build.
  • named_tree – The named tree to build.
coroutine update_repository(github_repo_id, repo_branches=None, external=None, wait_for_lock=False)[source]

Updates a repository code.

  • github_repo_id – The id of the repository on github.
  • repo_branches – Param to be passed to update_code().
  • external – Information about an external repository.
  • wait_for_lock – Indicates if we should wait for the release of the lock or simply return if we cannot get a lock.

A unicode string field.


URL used to retrieve an access token for this installation.


Datetime field.

Uses the python-dateutil library if available alternatively use time.strptime to parse the dates. Note: python-dateutil’s parser is fully featured and when installed you can utilise it to convert varying types of date formats into valid python datetime objects.

Note: Microseconds are rounded to the nearest millisecond.
Pre UTC microsecond support is effectively broken. Use ComplexDateTimeField if you need accurate microsecond support.

32-bit integer field.


A field wrapper around MongoDB’s ObjectIds.

objects = QuerySet

A ListField designed specially to hold a list of embedded documents to provide additional query helpers.


The only valid list values are subclasses of EmbeddedDocument.

New in version 0.9.


Informs if the installation auth token is expired.


A reference to the User that owns the installation

class toxicbuild.integrations.github.GithubInstallationRepository(*args, **kwargs)[source]

Bases: toxicbuild.core.utils.LoggerMixin, mongoengine.document.EmbeddedDocument

External (github) information about a repository.


Full name of the repository on github.


The id of the repository on github.


The id of the repository on ToxicBuild.

toxicbuild.integrations.webhook_receivers module

class toxicbuild.integrations.webhook_receivers.GithubWebhookReceiver(*args, **kwargs)[source]

Bases: toxicbuild.core.utils.LoggerMixin, pyrocumulus.web.handlers.BasePyroHandler


alias of pyrocumulus.web.operationmappers.HandlerOperationMapper


Called at the beginning of a request before get/post/etc.

Override this method to perform common initialization regardless of the request method.

Asynchronous support: Decorate this method with .gen.coroutine or .return_future to make it asynchronous (the asynchronous decorator cannot be used on prepare). If this method returns a .Future execution will not proceed until the .Future is done.

New in version 3.1: Asynchronous support.

coroutine receive_webhook()[source]

Module contents


Creates a new toxicbuild integrations environment.

Parameters:--root_dir – Root directory for toxicbuild integrations.
toxicbuild.integrations.restart(workdir, pidfile='')[source]

Restarts toxicmaster integrations

The instance of toxicintegrations in workdir will be restarted. :param workdir: Workdir for instance to be killed. :param –pidfile: Name of the file to use as pidfile.

toxicbuild.integrations.start(workdir, daemonize=False, stdout='./toxicintegrations.log', stderr='./toxicintegrations.log', conffile=None, loglevel='info', pidfile='')[source]

Starts toxicmaster integrations.

  • workdir – Work directory for server.
  • --daemonize – Run as daemon. Defaults to False
  • --stdout – stdout path. Defaults to /dev/null
  • --stderr – stderr path. Defaults to /dev/null
  • --conffile (-c,) – path to config file. Defaults to None. If not conffile, will look for a file called toxicintegrations.conf inside workdir
  • --loglevel – Level for logging messages. Defaults to info.
  • --pidfile – Name of the file to use as pidfile. Defaults to
toxicbuild.integrations.stop(workdir, pidfile='')[source]

Stops toxicmaster integrations.

  • workdir – Work directory for the ui to be killed.
  • --pidfile – pid file for the process.