Administration

Patchlab is expected to run with Patchwork as a Django application. As such, you should start by reading the Patchwork documentation and setting it up.

Once that is complete, add in the Patchlab Configuration options and start up the Patchwork server.

Requirements

Patchlab must run in the same WSGI application as Patchwork.

Network

For web hook support (used to bridge merge requests to email), the host must be able to receive web traffic from the Git forge you are bridging. That is, if bridging a project on gitlab.com, gitlab.com must be able to send HTTP POST requests to your web server.

Message Broker

Patchlab uses Celery for asynchronous tasks such as handling web hooks. This is because web hooks have a reasonably short timeout period and need to be quickly acknowledged.

Celery requires a message broker to function. AMQP is the default and RabbitMQ is recommended, but Redis or Amazon SQS should also be acceptable. Celery should be configured through the Django settings.py file; consult the Celery configuration documentation for possible values.

Task Workers

Asynchronous tasks are completed by Celery worker processes. Celery documents various daemonization approaches and you are free to use their approaches or create your own systemd service.

Database

Patchlab adds a few additional database tables and exposes them in the Django admin site. As such, you will need to run python manage.py migrate after installing the application. The tables are documented below.

Git Forges

class patchlab.models.GitForge(*args, **kwargs)[source]

Represents a Git forge being bridged to and from email.

project

A one-to-one relationship with a patchwork.models.Project.

host

The hostname of the Git forge; this is used for a uniqueness constraint on it combined with the forge ID and development branch.

forge_id

The unique ID of the project in the Git forge. For Gitlab, this is prominently displayed on the project home page.

subject_prefix

The subject prefix to prepend to patches being sent to the list when a pull request is opened against the branch.

development_branch

The branch in the Git forge used for development; this is the branch pull requests are opened against.

Branch

class patchlab.models.Branch(*args, **kwargs)[source]

Models multiple development branches within a single tree.

For example, a tree might have a feature branch and a bugfix branch and patches may apply to only one or the other. This allows us to route patches based on subject prefixes to the appropriate branch.

Bridged Submissions

class patchlab.models.BridgedSubmission(*args, **kwargs)[source]

Information about Patchwork submissions we’ve bridged back and forth.

This is necessary so that comments converted to email are properly threaded.

submission

A one-to-one relationship with a patchwork.models.Submission.

merge_request

The merge request ID in the Git forge.

commit

The commit hash of the bridged submission, if the submission in question is a patch. May be null for comments.

URLs

Patchlab inserts a number of URL patterns to the Patchwork URL patterns under the patchlab/ namespace. These URLs are web hooks that must be used when configuring each project to be bridged from the Git forge to email.

Gitlab

To set up a Gitlab project for bridging to email, navigate to the project’s home page, then Settings -> Integrations and fill out the form. The URL should point to your Patchwork instance. For instance, if your Patchwork application runs at / on your web server example.com, the URL would be https://example.com/patchlab/gitlab/. You must also set the secret token to whatever you have configured PATCHLAB_GITLAB_SECRET to be.

Next, select the event(s) you would like to cause the webhook to run. Currently, only merge request and comment events are supported.