annotate mod_pubsub_github/README.markdown @ 5551:8bfcedd93a72

mod_rest: List all error conditions in OpenAPI spec These are not handled by datamanager but by util.stanza and util.error, so they are not represented in the JSON schema file.
author Kim Alvefur <zash@zash.se>
date Sat, 17 Jun 2023 16:26:33 +0200
parents 1fcf3cb7bb50
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
1 ---
3511
b583cce491de mod_pubsub_github/README: Fix 'labels' metafield to be a list
Kim Alvefur <zash@zash.se>
parents: 3264
diff changeset
2 labels:
b583cce491de mod_pubsub_github/README: Fix 'labels' metafield to be a list
Kim Alvefur <zash@zash.se>
parents: 3264
diff changeset
3 - 'Stage-Beta'
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
4 summary: Publish Github commits over pubsub
3264
f48bedd1d433 mod_pubsub_github: Add support for signed requests
Kim Alvefur <zash@zash.se>
parents: 3258
diff changeset
5 ---
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
6
3264
f48bedd1d433 mod_pubsub_github: Add support for signed requests
Kim Alvefur <zash@zash.se>
parents: 3258
diff changeset
7 ## Introduction
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
8
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
9 This module accepts Github web hooks and publishes them to a local
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
10 pubsub component for XMPP clients to subscribe to.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
11
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
12 Entries are pushed as Atom payloads.
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
13
3258
85e3117b2b60 mod_pubsub_github/README: Note that it might work with Gitlab as well
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
14 It may also work with Gitlab.
85e3117b2b60 mod_pubsub_github/README: Note that it might work with Gitlab as well
Kim Alvefur <zash@zash.se>
parents: 1803
diff changeset
15
3264
f48bedd1d433 mod_pubsub_github: Add support for signed requests
Kim Alvefur <zash@zash.se>
parents: 3258
diff changeset
16 ## Configuration
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
17
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
18 Load the module on a pubsub component:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
19
3528
1fcf3cb7bb50 mod_pubsub_github/README: Specify language of code block for pretty syntax highlighting
Kim Alvefur <zash@zash.se>
parents: 3527
diff changeset
20 ``` {.lua}
1fcf3cb7bb50 mod_pubsub_github/README: Specify language of code block for pretty syntax highlighting
Kim Alvefur <zash@zash.se>
parents: 3527
diff changeset
21 Component "pubsub.example.com" "pubsub"
1fcf3cb7bb50 mod_pubsub_github/README: Specify language of code block for pretty syntax highlighting
Kim Alvefur <zash@zash.se>
parents: 3527
diff changeset
22 modules_enabled = { "pubsub_github" }
1fcf3cb7bb50 mod_pubsub_github/README: Specify language of code block for pretty syntax highlighting
Kim Alvefur <zash@zash.se>
parents: 3527
diff changeset
23 github_secret = "NP7bZooYSLKze96TQMpFW5ov"
1fcf3cb7bb50 mod_pubsub_github/README: Specify language of code block for pretty syntax highlighting
Kim Alvefur <zash@zash.se>
parents: 3527
diff changeset
24 ```
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
25
3517
ea1edd7cfb01 mod_pubsub_github: Add support for publishing to multiple node based on repository
Kim Alvefur <zash@zash.se>
parents: 3515
diff changeset
26 The URL for Github to post to would be either:
ea1edd7cfb01 mod_pubsub_github: Add support for publishing to multiple node based on repository
Kim Alvefur <zash@zash.se>
parents: 3515
diff changeset
27
ea1edd7cfb01 mod_pubsub_github: Add support for publishing to multiple node based on repository
Kim Alvefur <zash@zash.se>
parents: 3515
diff changeset
28 - `http://pubsub.example.com:5280/pubsub_github`
ea1edd7cfb01 mod_pubsub_github: Add support for publishing to multiple node based on repository
Kim Alvefur <zash@zash.se>
parents: 3515
diff changeset
29 - `https://pubsub.example.com:5281/pubsub_github`
ea1edd7cfb01 mod_pubsub_github: Add support for publishing to multiple node based on repository
Kim Alvefur <zash@zash.se>
parents: 3515
diff changeset
30
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
31 The module also takes the following config options:
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
32
3512
5fb14ae57b4c mod_pubsub_github/README: Mark up options as code snippets
Kim Alvefur <zash@zash.se>
parents: 3511
diff changeset
33 Name Default Description
5fb14ae57b4c mod_pubsub_github/README: Mark up options as code snippets
Kim Alvefur <zash@zash.se>
parents: 3511
diff changeset
34 ----------------------- ------------------- ------------------------------------------------------------
5fb14ae57b4c mod_pubsub_github/README: Mark up options as code snippets
Kim Alvefur <zash@zash.se>
parents: 3511
diff changeset
35 `github_node` `"github"`{.lua} The pubsub node to publish commits on.
3515
f756e051fa02 mod_pubsub_github: Require a secret to be set (BC)
Kim Alvefur <zash@zash.se>
parents: 3514
diff changeset
36 `github_secret` **Required** Shared secret used to sign HTTP requests.
3517
ea1edd7cfb01 mod_pubsub_github: Add support for publishing to multiple node based on repository
Kim Alvefur <zash@zash.se>
parents: 3515
diff changeset
37 `github_node_prefix` `"github/"`{.lua}
ea1edd7cfb01 mod_pubsub_github: Add support for publishing to multiple node based on repository
Kim Alvefur <zash@zash.se>
parents: 3515
diff changeset
38 `github_node_mapping` *not set* Field in repository object to use as node instead of `github_node`
3514
8811b7dbe6e2 mod_pubsub_github: Add support for specifying an actor with less privileges
Kim Alvefur <zash@zash.se>
parents: 3512
diff changeset
39 `github_actor` *superuser* Which actor to do the publish as (used for access control)
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
40
3517
ea1edd7cfb01 mod_pubsub_github: Add support for publishing to multiple node based on repository
Kim Alvefur <zash@zash.se>
parents: 3515
diff changeset
41 More advanced example
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
42
3517
ea1edd7cfb01 mod_pubsub_github: Add support for publishing to multiple node based on repository
Kim Alvefur <zash@zash.se>
parents: 3515
diff changeset
43 ``` {.lua}
ea1edd7cfb01 mod_pubsub_github: Add support for publishing to multiple node based on repository
Kim Alvefur <zash@zash.se>
parents: 3515
diff changeset
44 Component "pubsub.example.com" "pubsub"
ea1edd7cfb01 mod_pubsub_github: Add support for publishing to multiple node based on repository
Kim Alvefur <zash@zash.se>
parents: 3515
diff changeset
45 modules_enabled = { "pubsub_github" }
ea1edd7cfb01 mod_pubsub_github: Add support for publishing to multiple node based on repository
Kim Alvefur <zash@zash.se>
parents: 3515
diff changeset
46 github_actor = "github.com"
ea1edd7cfb01 mod_pubsub_github: Add support for publishing to multiple node based on repository
Kim Alvefur <zash@zash.se>
parents: 3515
diff changeset
47 github_node_mapping = "name" --> github_node_prefix .. "repo"
ea1edd7cfb01 mod_pubsub_github: Add support for publishing to multiple node based on repository
Kim Alvefur <zash@zash.se>
parents: 3515
diff changeset
48 -- github_node_mapping = "full_name" --> github_node_prefix .. "owner/repo"
ea1edd7cfb01 mod_pubsub_github: Add support for publishing to multiple node based on repository
Kim Alvefur <zash@zash.se>
parents: 3515
diff changeset
49 github_secret = "sekr1t"
ea1edd7cfb01 mod_pubsub_github: Add support for publishing to multiple node based on repository
Kim Alvefur <zash@zash.se>
parents: 3515
diff changeset
50 ```
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
51
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
52 If your HTTP host doesn't match the pubsub component's address, you will
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
53 need to inform Prosody. For more info see Prosody's [HTTP server
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
54 documentation](https://prosody.im/doc/http#virtual_hosts).
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
55
3264
f48bedd1d433 mod_pubsub_github: Add support for signed requests
Kim Alvefur <zash@zash.se>
parents: 3258
diff changeset
56 ## Compatibility
1803
4d73a1a6ba68 Convert all wiki pages to Markdown
Kim Alvefur <zash@zash.se>
parents:
diff changeset
57
3264
f48bedd1d433 mod_pubsub_github: Add support for signed requests
Kim Alvefur <zash@zash.se>
parents: 3258
diff changeset
58 ------ -------------
f48bedd1d433 mod_pubsub_github: Add support for signed requests
Kim Alvefur <zash@zash.se>
parents: 3258
diff changeset
59 0.10 Should work
f48bedd1d433 mod_pubsub_github: Add support for signed requests
Kim Alvefur <zash@zash.se>
parents: 3258
diff changeset
60 0.9 Works
f48bedd1d433 mod_pubsub_github: Add support for signed requests
Kim Alvefur <zash@zash.se>
parents: 3258
diff changeset
61 ------ -------------