B U I L D O M A T
a software build labour-saving device
Buildomat manages the provisioning of ephemeral UNIX systems (e.g., instances in AWS EC2) on which to run software builds. It logs job output, collects build artefacts, and reports status. The system integrates with GitHub through the Checks API, to allow build jobs to be triggered by pushes and pull requests.
Components
Buildomat Core
The buildomat core is responsible for authenticating users and remote services, for managing build systems, and for running jobs and collecting output.
Client Command (buildomat, in client/)
A client tool that uses the client library to interface with and manipulate the core server. The tool has both administrative and user-level functions, expressed in a relatively regular hierarchy of commands; e.g., buildomat job run or buildomat user ls.
$ ./target/release/buildomat
Usage: buildomat [OPTS] COMMAND [ARGS...]
Commands:
info get information about server and user account
control server control functions
job job management
user user management
Options:
--help usage information
-p, --profile PROFILE
authentication and server profile
ERROR: choose a command
Client Library (buildomat-openapi, in openapi/)
A HTTP client library for accessing the core buildomat server. This client is regenerated by a script (./tools/generate.sh) which uses the progenitor OpenAPI client generator.
Server (buildomat-server, in server/)
The core buildomat API server. Manages the creation, tracking, and destruction of AWS EC2 instances as required to execute jobs. This component can be used by both the GitHub integration server (Wollongong) and the client command.
Agent (buildomat-agent, in agent/)
A process that is injected into an ephemeral AWS EC2 instance to allow the buildomat core server to take control and run jobs. This process receives single-use credentials at provisioning time from the core server, and connects out to receive instructions. The agent does not require a public IP, or any direct inbound connectivity, to allow agents to run inside remote NAT environments.
GitHub Integration (Wollongong)
Wollongong is the GitHub-specific portion of the buildomat suite. It is responsible for receiving and processing notifications of new commits and pull requests on GitHub, starting any configured build jobs, and reporting the results so that they are visible through the GitHub user interface.
Server (wollongong-server, in github/server/)
This server acts as a GitHub App. It is responsible for processing incoming GitHub webhooks that notify the system about commits and pull requests in authorised repositories. In addition to relaying jobs between GitHub and the buildomat core, this service provides an additional HTML presentation of job state (e.g., detailed logs) and access to any artefacts that jobs produce. This server keeps state required to manage the interaction with GitHub, but does not store job data; requests for logs or artefacts are proxied back to the core server.
Database Tool (wollongong-dbtool, in github/dbtool/)
This tool can be used to inspect the database state kept by Wollongong as it tracks GitHub pull requests and commits. Unlike the core client tool, this program directly interacts with a local SQLite database.
$ wollongong-dbtool
Usage: wollongong-dbtool COMMAND [ARGS...]
Commands:
delivery (del) webhook deliveries
repository (repo) GitHub repositories
check GitHub checks
Options:
--help usage information
ERROR: choose a command
Of particular note, the tool is useful for inspecting and replaying received webhook events; e.g.,
$ wollongong-dbtool del ls
SEQ ACK RECVTIME EVENT ACTION
0 1 2021-10-05T01:58:32Z ping -
1 1 2021-10-05T02:25:33Z installation created
2 1 2021-10-05T02:26:53Z push
3 1 2021-10-05T02:26:53Z check_suite requested
4 1 2021-10-05T02:26:56Z check_suite completed
5 1 2021-10-05T02:26:56Z check_run completed
6 1 2021-10-05T02:26:56Z check_run created
7 1 2021-10-05T02:26:56Z check_run created
8 1 2021-10-05T02:26:57Z check_run created
...
The wollongong-dbtool del unack SEQ command can be used to trigger the reprocessing of an invididual webhook message.
Licence
Unless otherwise noted, all components are licenced under the Mozilla Public License Version 2.0.
8 Dec 15, 2022
7 Sep 11, 2022
40 Oct 2, 2022
36 Dec 14, 2022
34 Dec 18, 2022
21 Nov 20, 2022
51 Dec 26, 2022
18 Sep 29, 2022
21 Dec 16, 2022
45 Dec 17, 2022
3 May 10, 2023
186 Dec 30, 2022
0 Mar 29, 2022
61 Dec 16, 2022
8 Dec 6, 2022
2.7k Apr 17, 2023
2 Nov 8, 2021
18 Dec 27, 2022