Mercurial > prosody-modules

comparison mod_pubsub_forgejo/README.md @ 6175:131b8bfbefb4

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_pubsub_forgejo: new module for forgejo webhooks
author nicoco <nicoco@nicoco.fr>
date Mon, 17 Feb 2025 23:28:05 +0100
parents
children
comparison
equal deleted inserted replaced
6174:6d5a19bdd718 6175:131b8bfbefb4
1 ---
2 labels:
3 - "Stage-Beta"
4 summary: "Turn forgejo/github/gitlab webhooks into atom-in-pubsub"
5 rockspec:
6 build:
7 modules:
8 mod_pubsub_forgejo.templates: templates.lib.lua
9 mod_pubsub_forgejo.format: format.lib.lua
10 ---
11
12 # Introduction
13
14 This module accepts Forgejo webhooks and publishes them to a local
15 pubsub component as Atom entries for XMPP clients to subscribe to.
16 Such entries can be viewed with a pubsub-compatible XMPP client such as
17 [movim](https://movim.eu/) or [libervia](https://libervia.org/), or turned
18 into chat messages with a bot (cf last section of this document).
19 It is a more customisable `mod_pubsub_github`.
20
21 It should also work with other forges such as github and gitlab (to be tested).
22
23 # Configuration
24
25 ## Basic setup
26
27 Load the module on a pubsub component:
28
29 ```{.lua}
30 Component "pubsub.example.com" "pubsub"
31 modules_enabled = { "pubsub_forgejo" }
32 forgejo_secret = "something-very-secret" -- copy this in the Forgejo web UI
33 ```
34
35 The "Target URL" to configure in the Forgejo web UI should be either:
36
37 - `http://pubsub.example.com:5280/pubsub_forgejo`
38 - `https://pubsub.example.com:5281/pubsub_forgejo`
39
40 If your HTTP host doesn't match the pubsub component's address, you will
41 need to inform Prosody. For more info see Prosody's [HTTP server
42 documentation](https://prosody.im/doc/http#virtual_hosts).
43
44 ## Advanced setup
45
46 ### Publishing settings
47
48 #### Pubsub actor
49
50 By default, `forgejo_actor` is unset; this results in nodes being created by the prosody superuser.
51 Change this if you set up access control and you know what you are doing.
52
53 #### Pubsub node
54
55 By default, all events are published in the same pubsub node named "forgejo".
56 This can be changed by setting `forgejo_node` to a different value.
57
58 Another option is to used different nodes based on which repository emitted the webhook.
59 This is useful if you configured the webhook at the user (or organisation) level instead of repository-level.
60 To set this up, define `forgejo_node_prefix` and `forgejo_node_mapping`.
61 `forgejo_node_mapping` must be a key in the the webhook "repository" payload, e.g., "full*name". 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_.
62
63 ### Customizing the atom entry
64
65 #### Pushes with no commits
66
67 By default, pushes without commits (i.e., pushing tags) are ignored, because it leads
68 to weird entries like "romeo pushed 0 commit(s) to repo".
69 This behaviour can be changed by setting `forgejo_skip_commitless_push = false`.
70
71 #### Atom entry templates
72
73 By default, 3 webhooks events are handled (push, pull_request and release),
74 and the payload is turned into a atom entry by
75 using [util.interpolation](https://prosody.im/doc/developers/util/interpolation) templates.
76 The default templates can be viewed in the source of this module, in the `templates.lib.lua`
77 file.
78
79 You can customise them using by setting `forgejo_templates`, which is merged with the default
80 templates.
81 In this table, keys are forgejo event names (`x-forgejo-template` request header).
82 Values of this table are tables too, where keys are atom elements and values are the templates
83 passed to [util.interpolation](https://prosody.im/doc/developers/util/interpolation).
84
85 A few filters are provided:
86
87 - `|shorten` strips the last 32 characters: useful to get a short commit hash
88 - `|firstline` only keeps the first line: useful to get a commit "title"
89 - `|branch` strips the first 12 characters: useful to get a branch name from `data.ref`
90 - `|tag` strips the first 11 characters: useful to get a tag name from `data.ref`
91
92 Example:
93
94 ```{.lua}
95 forgejo_templates = {
96 pull_request = nil, -- suppress handling of `pull_request` events
97 release = { -- data is the JSON payload of the webhook
98 title = "{data.sender.username} {data.action} a release for {data.repository.name}",
99 content = "{data.release.name}",
100 id = "release-{data.release.tag_name}",
101 link = "{data.release.html_url}"
102 }
103 }
104 ```
105
106 Examples payloads are provided in the `webhook-examples`
107
108 # Publishing in a MUC
109
110 You can use a bot that listen to pubsub events and converts them to MUC messages.
111 MattJ's [riddim](https://matthewwild.co.uk/projects/riddim/) is well suited for that.
112
113 Example config, single pubsub node:
114
115 ```{.lua}
116 jid = "forgejo-bot@example.com"
117 password = "top-secret-stuff"
118 room = "room@rooms.example.com"
119 autojoin = room
120
121 pubsub2room = {
122 "pubsub.example.com#forgejo" = {
123 room = room,
124 template = "${title}\n${content}\n${link@href}"
125 }
126 }
127 ```
128
129 Example with several nodes:
130
131 ```{.lua}
132 local nodes = {"forgejo---org/repo1", "forgejo---org/repo2"}
133 pubsub2room = {}
134
135 for _, node in ipairs(slidge_repos) do
136 pubsub2room = ["pubsub.example.com#" .. node] = {
137 room = room,
138 template = "${title}\n${content}\n${link@href}"
139 }
140 end
141 ```
142
143 # TODO
144
145 - Default templates for all event types
146 - (x)html content
147
148 # Compatibility
149
150 Works with prosody 0.12