mod_pubsub_forgejo

Introduction

This module accepts Forgejo webhooks and publishes them to a local pubsub component as Atom entries for XMPP clients to subscribe to. Such entries can be viewed with a pubsub-compatible XMPP client such as movim or libervia, or turned into chat messages with a bot (cf last section of this document). It is a more customisable mod_pubsub_github.

It should also work with other forges such as github and gitlab (to be tested).

Configuration

Basic setup

Load the module on a pubsub component:

Component "pubsub.example.com" "pubsub"
    modules_enabled = { "pubsub_forgejo" }
    forgejo_secret = "something-very-secret"  -- copy this in the Forgejo web UI

The “Target URL” to configure in the Forgejo web UI should be either:

• http://pubsub.example.com:5280/pubsub_forgejo
• https://pubsub.example.com:5281/pubsub_forgejo

If your HTTP host doesn’t match the pubsub component’s address, you will need to inform Prosody. For more info see Prosody’s HTTP server documentation.

Advanced setup

Publishing settings

Pubsub actor

By default, forgejo_actor is unset; this results in nodes being created by the prosody superuser. Change this if you set up access control and you know what you are doing.

Pubsub node

By default, all events are published in the same pubsub node named “forgejo”. This can be changed by setting forgejo_node to a different value.

Another option is to used different nodes based on which repository emitted the webhook. This is useful if you configured the webhook at the user (or organisation) level instead of repository-level. To set this up, define forgejo_node_prefix and forgejo_node_mapping. forgejo_node_mapping must be a key in the the webhook “repository” payload, e.g., “fullname”. Example: with forge_node_prefix = "forgejo---" and forgejo_node_mapping = "full_name", webhooks emitted by the repository _repo-name in the org-name organisation will be published in the node forgejo—org-name/repo-name.

Customizing the atom entry

Pushes with no commits

By default, pushes without commits (i.e., pushing tags) are ignored, because it leads to weird entries like “romeo pushed 0 commit(s) to repo”. This behaviour can be changed by setting forgejo_skip_commitless_push = false.

Atom entry templates

By default, 3 webhooks events are handled (push, pull_request and release), and the payload is turned into a atom entry by using util.interpolation templates. The default templates can be viewed in the source of this module, in the templates.lib.lua file.

You can customise them using by setting forgejo_templates, which is merged with the default templates. In this table, keys are forgejo event names (x-forgejo-template request header). Values of this table are tables too, where keys are atom elements and values are the templates passed to util.interpolation.

A few filters are provided:

• |shorten strips the last 32 characters: useful to get a short commit hash
• |firstline only keeps the first line: useful to get a commit “title”
• |branch strips the first 12 characters: useful to get a branch name from data.ref
• |tag strips the first 11 characters: useful to get a tag name from data.ref

Example:

forgejo_templates = {
    pull_request = nil,  -- suppress handling of `pull_request` events
    release = {          -- data is the JSON payload of the webhook
        title = "{data.sender.username} {data.action} a release for {data.repository.name}",
        content = "{data.release.name}",
        id = "release-{data.release.tag_name}",
        link = "{data.release.html_url}"
    }
}

Examples payloads are provided in the webhook-examples

Publishing in a MUC

You can use a bot that listen to pubsub events and converts them to MUC messages. MattJ’s riddim is well suited for that.

Example config, single pubsub node:

jid = "forgejo-bot@example.com"
password = "top-secret-stuff"
room = "room@rooms.example.com"
autojoin = room

pubsub2room = {
  "pubsub.example.com#forgejo" = {
    room = room,
    template = "${title}\n${content}\n${link@href}"
  }
}

Example with several nodes:

local nodes = {"forgejo---org/repo1", "forgejo---org/repo2"}
pubsub2room = {}

for _, node in ipairs(slidge_repos) do
  pubsub2room = ["pubsub.example.com#" .. node] = {
    room = room,
    template = "${title}\n${content}\n${link@href}"
  }
end

TODO

• Default templates for all event types
• (x)html content

Compatibility

Works with prosody 0.12

sudo prosodyctl install --server=https://modules.prosody.im/rocks/ mod_pubsub_forgejo