Biscepter: Efficient Repeated and Concurrent Bisection
Table of Contents
🛠️ Why Biscepter over git bisect?
Biscepter and git bisect may solve the same problem, but biscepter comes with multiple advantages:
- 🗄️ Caching of builds from previous bisects
- 🚂 Bisecting multiple issues at once
- 🚦 Possibility of prioritizing previously built commits to avoid arduous rebuilding
- 🛡️ Automatically remembering and avoiding commits that break the build
- 🩺 Easy builtin healthchecks to ensure the system under test is ready
- 🐳 Simple definition of builds through Dockerfiles
Together, these advantages result in a more streamlined and straight-forward way of bisecting large systems exhibiting multiple different issues.
⚙️ Installation
Installation of the biscepter CLI requires Go 1.22.0
or newer.
Installing directly:
$ go install github.com/Anon10214/dinkel/biscepter@latest
You should now be able to run dinkel from the command line using biscepter
.
If you encounter an error, ensure that the GOBIN
environment variable is set and in your path.
Alternatively, you may clone this repository and build biscepter locally
$ git clone git@github.com:Anon10214/biscepter.git
$ cd biscepter
$ go build
You should now have a binary which you can run via ./biscepter
.
📡 API
The CLI exposes a RESTful HTTP API on port 40032
(can be changed via flags), whose openAPI specification can be found under /api/openapi.yml.
For every kind of system to test, a job config has to be created.
An example config with explanations of all fields can be found at /configs/job-config.yml.
Using this API, any language can be used to communicate with biscepter.
Be sure to check out the examples under /examples/api-* to get a quick understanding of how to use the API!
📦 Go Package
This repository contains a Go package, whose documentation can be found here.
Said package allows a Go program to control biscepter without a need for the CLI.
Be sure to check out the examples under /examples/pkg-* to get a quick overview of how to use the Go package!
For every kind of system to test, a job config has to be created.
An example config with explanations of all fields can be found at /configs/job-config.yml.
It is easiest to create a job using such a config, but it can also be created by setting the job's fields manually.
The required fields for a job to run correctly are:
ReplicaCount
GoodCommit
& BadCommit
Dockerfile
or DockerfilePath
Repository
🩺 Healthchecks
This section contains a list of all supported types of healthchecks, as well as what the additionally supplied data represents for this healthcheck.
Type |
Explanation |
Data |
Data Example |
HTTP |
This endpoint is considered healthy if it returns a status code of 200 on a GET request. |
The path of the URL |
"/status" |
Script |
This endpoint is considered healthy if the script returns with exit code 0 . The environment variable $PORT<XXXX> can be used within the script to get the port to which <XXXX> was mapped to on the host (e.g. $PORT443 ). |
The script to run |
"echo Hello World!" |