gohci

README

gohci - The Go on Hardware CI

• This doc:
  • Genesis
  • Pictures
  • Design
  • Features
• Getting started and configuration: CONFIG.md
• FAQ: FAQ.md

Genesis

All I wanted was to run go test ./... on a Raspberry Pi on both Pull Requests and Pushes for a private repository. I realized that it is possible to store the test's stdout to a Github Gist so I created a serverless CI.

The result is the distilled essence of a Continuous Integration service that leans heavily toward testing Go projects on hardware, specifically low power ones (Raspberry Pis, C.H.I.P., BeagleBone, ODROID, etc) but also works great on Windows and macOS.

Part of the gohci lab testing https://periph.io:

Here's how it looks like on a PR when the workers start to handle it:

View of the status on commits:

Design

It hardly can get any simpler:

• Only support one specific use case: Golang project hosted on Github.
• There is no "server", only workers that you run yourself. Each worker must be internet accessible and HTTPS must be proxied down to HTTP.
  • Caddy works great along its native letsencrypt.org support.

Features

• 100% free and open source.
  • Secure, you are in control. There's no third party service beside GitHub.
  • Enables free testing on macOS, Windows or single CPU ARM micro computer.
  • Low maintenance, run as systemd/launchd service.
• Each worker can test multiple repositories, each with custom checks.
• Each check's stdout is attached to the gist as they complete.
• The commit's status is updated "live" on Github. This is pretty cool to see in action on a GitHub PR.
• gohci-worker exits whenever the executable or gohci.yml is updated; making it easy to use an auto-updating mechanism.

Not convinced? Read the FAQ.md for additional information.

Convinced? See CONFIG.md to get started!

Documentation

Overview

Package gohci defines the configuration schemas for 'gohci.yml' and '.gohci.yml'.

'.gohci.yml' is found in the repository and defines the checks to run.

'gohci.yml' is found on the worker itself and defines the http port, webhook secret and OAuth2 access token.

Index

• type Check
• type ProjectConfig
• type ProjectWorkerConfig
• type WorkerConfig

Types

type Check

type Check struct {
	Cmd []string // Command to run.
	Env []string // Optional environment variables to use.
	Dir string   // Directory to run from. Defaults to the root of the checkout.
}

Check is a single command to run.

type ProjectConfig

type ProjectConfig struct {
	Version int                   // Current 1
	Workers []ProjectWorkerConfig //
}

ProjectConfig is a configuration file found in a project as ".gohci.yml" in the root directory of the repository.

type ProjectWorkerConfig

type ProjectWorkerConfig struct {
	// Name is the worker which this config belongs to.
	//
	// If empty, this is the default configuration to use.
	Name string
	// Checks are the commands to run to test the repository. They are run one
	// after the other from the repository's root.
	Checks []Check
}

ProjectWorkerConfig is the project configuration via ".gohci.yml" for a specific worker.

type WorkerConfig

type WorkerConfig struct {
	// TCP port number for the HTTP server.
	Port int
	// WebHookSecret is the shared secret that keeps people on the internet from
	// running tasks on your worker.
	//
	// gohci-worker generates a good secret by default.
	//
	// See https://developer.github.com/webhooks/ for more information.
	WebHookSecret string
	// Oauth2AccessToken is the OAuth2 Access Token to be able to create gist and
	// update commit status.
	//
	// https://github.com/settings/tokens, check "repo:status" and "gist"
	Oauth2AccessToken string
	// Display name to use in the status report on Github.
	//
	// Defaults to the machine hostname.
	Name string
}

WorkerConfig is a worker configuration.

It is found as `gohci.yml` in the gohci-worker working directory.