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.