SS13 Gitwebhook Handler is an automation tool for maintaining TauCeti repository. This handler is built with orientation on BYOND games, mainly for Space Station 13, so with minor changes it could be used for any compatible codebase.
Handler features:
- Changelog generation and validation from PR description markup
DMMandDMIdiff reports- Test Merge changelog generation
- Interactive Diff Map for
.dmmfiles - Auto-labeling of PRs and Issues
- Web UI interface (Configuration without recompiling or redeploying)
Tool may look similar to github_webhook_processor.php, which do sort of same things,
but unlike it this handler gives more complex and flexible solution, which could be extended in any way, without maintenance problems.
Current work of handler can be seen here TauCetiStation/TauCetiClassic.
Important: application needs Java (at least 8 version).
- Download 'jar' file.
- Start it with next command:
java -jar ss13-gitwebhook-handler-${version}.jar --server.port=${port} --security.user.name=${login} --security.user.password=${password}
- Go to configuration UI in browser and change all properties as you need. Config page located on address:
/config - Configure your repository to send webhook to handler.
While filling of some fields questions about what value it should contain may appear.
In the right part of the page full description about every field can be found. (Question mark in the top-right part.)
Additional info may be found in About window. (Info mark in the bottom-right part.)
Also, during application startup two files will be created: GWHLog.log and GWHConfig.json for logs and configuration storing.
To work handler should receive so called webhooks from GitHub and it should have token to interact with GitHub API.
- Webhook should send
pull_requestandissuesevents - Webhook should send data in
application/jsonformat - GitHub API token should have at least
reporights
Endpoint to send webhooks: /handler
To store images handler use self hosted image sharing service PictShare with upload_code check.
Current configured endpoint is img.taucetistation.org. It can't be changed without app recompiling.
During generating of Interactive Diff Map a lot of map images could be created. To optimize their storage space,
pngquant tool is used to compress them. On Windows you should put pngquant.exe in the root
of application (place where log/config files generated), on *nix systems tool should be available by path /usr/bin/pngquant.
To patch .html file with new changes it should have <div id="changelogs"></div> element. For example:
<div id="changelogs"></div>
All the rest will be generated automatically.
Example of PR description with changelog markup:
...Some PR description...
:cl:
- bugfix: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
After pull request will be merged next will appear in changelog file:
<!doctype html>
<html>
<head></head>
<body>
<div id="changelogs">
<div class="row" data-date="${current date}">
<div class="col-lg-12">
<h3 class="row-header">${current date}</h3>
<div data-author="${author name}">
<h4 class="author">${author name}:</h4>
<ul class="changelog">
<li class="bugfix">Lorem ipsum dolor sit amet, consectetur adipiscing elit.</li>
</ul>
</div>
</div>
</div>
</div>
</body>
</html>
- All text after
:cl:will be parsed as changelog, so it should be in the end of PR body. - Changelog entry is a list entry in GitHub markdown. So, if your changelog does not look like a list it's probably invalid.
- Entry should not contain explicit newlines. If entry is too long GitHub may visually stretch it, but it's fine.
- class: Text.Space before dash, after it and after colon.
By default handler takes author name value as GitHub login. This could be modified by setting custom name after :cl: symbol.
...Some PR description...
:cl: Custom name goes here
- bugfix: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Adding of [link] tag after changelog class will result into linking with PR, by adding link button.
This: - bugfix[link]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Will result into this:
<li class="bugfix">Lorem ipsum dolor sit amet, consectetur adipiscing elit.<a class="btn btn-xs btn-success link-btn" href="PR url">Read More</a></li>
There is no need to work with it directly, all process is automatic.
If changelog markup is invalid, handler will mark PR with Invalid Changelog label (can be changed in Web UI)
and leave comment with problem description. After markup fixing, label will be removed automatically.
Validation process happens on PR creation and description editing.
Auto-labeling works with pull requests and issues. Process happens only once on issue/pull request creation.
All issues would automatically labeled with Bug label. Issue with [Proposal] tag in title will be labeled with Proposal label.
List of labels to add to PR depends on three things:
- If PR diff has changes in
.dmior.dmmfilesIcon ChangesandMap Changeslabels will be added. - If
[DNM]or[WIP]tags exists in titleDo Not MergeandWork In Progresslabels will be added. - Changelog classes are used to determine label to add.
Read more in Web UI.
If handler found changes in .dmi/.dmm files, diff report will be generated automatically.
Report generation happens on PR creation and new commits pushing events.
To create interactive map PR should be labeled with Interactive Diff Map label (name is configurable). Right after that
comment with map links will be appeared. After removing this label, comment with links will be deleted, and local server files
with map images will be deleted.
Some pull requests may be merged locally for test merge. Since pull request doesn't merged in github, changelog, if exist, won't be generated. To notify players about changes there is ability to create Test Merge changelog, by adding "Test Merge" label. This changelog will be automatically removed after PR merging or label removing.
Code is licensed under GNU Affero General Public License version 3. All commits before 879b496 and builds before version 1.5 (all exclusively) are licensed under MIT