Server mode¶
Main configuration¶
Listening for events¶
Using GitHub webhooks¶
Poule can listen on HTTP for incoming GitHub webhooks. Under this mode, the repository’s webhook settings in GitHub must point to the publicly accessible URL of a poule server instance.
The following configuration elements are required:
- The
http_listen
address.- The
http_secret
value which must correspond to the secret value specified in the repository configuration on GitHub.
Example configuration:
http_listen: ":80"
http_secret: "S3CR3T"
repositories:
icecrime/poule: ""
Using NSQ¶
NSQ is a “realtime distributed messaging platform” which, in combination with crosbymichael/hooks, can be used to distribute GitHub events. Relying on a message queue for this use case has several advantages:
- Messages are persisted: events will be queued when poule is offline and will catch-up as soon as it gets back online.
- A single webhook endpoint in the repository’s settings in GitHub can fan out messages to a variety of listeners through the messaging infrastructure.
Configuring poule to listens on NSQ requires several configuration elements:
- The
nsq_lookupd
address.- The
nsq_channel
to subscribe to.- For each repository, the queue name to monitor.
Example configuration:
nsq_channel: "poule"
nsq_lookupd: "127.0.0.1:4161"
repositories:
icecrime/poule: "hooks-poule"
Repository configuration¶
The server-mode configuration can contain both infrastructure-level settings (such as the NSQ configuration) and operations. However, having the entire configuration in a single file is impratical when managing a large collection of repositories.
In server mode, poule will look for a special poule.yml
file at the root of each configured
repository and load it as repository-specific configuration. This allows each individual repository
and group of maintainers to manage their own set of rules. Furthermore, this allows to keep the
central configuration private as it typically contains secret information.
Monitoring for updates¶
Repository-specific configurations will be loaded at poule startup. However, poule also provides a
builtin poule-updater
operation which looks for merged pull requests which either modify or add
the special poule.yml
file at the root of the repository.
When configured to be triggered on a pull request closed event, the operation will auto-refresh the configuration settings for the repository without having to restart the server. One possibily is to add this operation in the main configuration, hence covering all repositories:
common_configuration:
# Poule updater watches for merged pull requests which modify the `poule.yml` file at the root
# of the repository, and takes these changes into account live.
- triggers:
pull_request: [ closed ]
operations:
- type: poule-updater