gomason
CategoryContinuous Integration
SubcategoryContinuous Integration
Stars69
Test, Build, Sign, and Publish your go binaries from a clean workspace
About gomason
This large README is shown as a plain-text preview. Read the full README at the source
# gomason
[](https://img.shields.io/github/release/nikogura/gomason.svg)
[](https://github.com/nikogura/gomason/actions/workflows/ci.yml)
[](https://goreportcard.com/report/github.com/nikogura/gomason/v2)
[](https://pkg.go.dev/github.com/nikogura/gomason/v2)
[](https://codecov.io/gh/nikogura/gomason)
[](https://github.com/avelino/awesome-go)
Tool for testing, building, signing and publishing binaries. Think of it as an on-premises CI/CD system that also performs code signing and publishing of artifacts.
## Historical Context
**Note:** Gomason was originally created in the pre-Go modules era (before Go 1.11, released September 2018) when Go dependency management was less deterministic and required tools like `dep`, `godep`, or manual `GOPATH` management. Many of gomason's core features—such as clean workspace builds, dependency isolation, and reproducible builds—addressed pain points that have since been largely solved by Go modules and the modern Go toolchain.
While Go modules now provide deterministic builds and better dependency management, gomason still offers significant value for:
- **Template-based artifact generation** - Dynamic creation of install scripts, documentation, and configuration files from templates
- **Sophisticated publishing workflows** - Automated upload of binaries, signatures, checksums, and generated artifacts to multiple repository types
- **Code signing with provenance** - GPG signing of binaries with proper author attribution
- **Multi-platform release automation** - Cross-compilation and publishing in a single command
- **Legacy project support** - Projects that haven't migrated to modules
The templating and publishing functions remain highly useful even in the modern Go ecosystem, where they can complement standard tooling (`go build`, `go test`, GitHub Actions, etc.) to provide a complete release pipeline.
You could do this via a CI/CD System and an artifact repository of some flavor. But wiring that up properly takes time, experience, and tends to be very specific to your particular system and repository.
Gomason attempts to abstract all of that. It will:
1. Run tests and report on results
2. Build binaries for the target OS/Arch and other files based on templates.
3. Sign the binaries and files thus built.
4. Publish the files, their signatures, and their checksums to the destination of your choice.
It does all of this based on config file called 'metadata.json' which you place in the root of your repository.
None of this is exactly rocket science, but I have done it enough times, in enough different ways, that it was finally time to say 'enough' and be done with it.
Gomason comes from an experience I had where management was so astounding **anti-testing** that I needed to come up with a way to do clean-room CI testing quickly, easily and transparently, but also fly under the radar. They didn't need to know I was 'wasting time' testing my work. *(yeah, I couldn't believe it either. Blew my mind.)*
What started out as a sort of subversive method of continuing to test my own code expanded after we parted ways. See, signing binaries and uploading the various bits to a repo isn't exactly rocket science, but it's also *dreadfully boring* once you've done it a few times. I figured DRY, so I made a 'one and done' means for doing so.
CI systems like Artifactory Pro can sign binaries, but they don't really have provenance on who the author was. The bits arrived there, presumably after authentication (but that depends on the config), but you don't really know who did the signing.
Enter gomason, which can do the building and signing locally with personal keys and then upload. Presumably you'd also require authentication on upload, but now you've actually established 2 things- someone with credentials has uploaded this, *and* they've personally signed what they uploaded. Whether you trust that signature is up to you, but we've provided an easy means to extend what a traditional CI system can do.
Gomason uses ```gox``` the Go cross compiler to do it's compiling. It builds whatever versions you like, but they need to be specified in the metadata file detailed below in gox-like format.
Code is downloaded via ```go get``` (or `go mod download` in module-aware builds). If you have your VCS configured so that you can do that without authentication, then everything will *just work*.
Signing is currently done via GPG. I intend to support other signing methods such as Keybase.io, but at the moment, gpg is all you get. If your signing keys are in gpg, and you have the gpg-agent running, it should *just work*.
## Language Suppport
At present, `gomason` only supports golang, but it turns out automating the whole test/build/sign/publish steps and making the UX painless is a really attractive thing, and it would be nice to have when working in other languages.
Basically, the authors have gotten so used to the painless UX that when we have to do things in other languages, we found ourselves missing `gomason`.
Necessity being the mother of invention, stay tuned...
## Installation
go install github.com/nikogura/gomason/v2@latest
## Modern Usage Patterns
For new projects, gomason excels at:
**Release Automation:**
```bash
# Complete test, build, sign, and publish pipeline
gomason publish
# Test and build only (useful in CI)
gomason build
```
**Template-Driven Artifacts:**
- Generate install scripts, documentation, and configuration files
- Template variables populated from `metadata.json` at build time
- Perfect for creating distribution artifacts alongside binaries
**Multi-Repository Publishing:**
- Upload to multiple artifact repositories simultaneously
- Support for Artifactory, S3, and HTTP endpoints
- Separate tool repositories from main binary repositories
Combined with modern CI/CD (GitHub Actions, etc.), gomason provides the signing and publishing capabilities that standard Go tooling doesn't offer.
## Usage Examples
Test the master branch in a clean GOPATH return success/failure:
gomason test
Test the master branch and see what's going on behind the scenes:
gomason test -v
Test another branch verbosely:
gomason test -v -b <branch name>
Publish the master branch after building:
gomason publish -v
Build and publish a branch without testing (I know, I know, don't test?!!?!)
This can be occasionally useful for publishing 3rd party tools internally when you need to make internal tweaks to support your use case.
Sometimes you don't have the wherewithal to build and maintain a full test suite for a 3rd party tool.
gomason publish -vs -b <branch name>
Other options can be found by running:
gomason help
## Project Config
Projects are configured by the file ```metadata.json``` in the root of the project being tested/built/published by gomason. This file is intended to be checked into the project and contains information required for gomason to function. See below for examples and [Project Config Reference](#project-config-reference) for full details.
As of v2.6.1, `gomason` supports S3 urls of the 'virtual host' variety. (i.e. `https://<bucket>.s3.<region>.amazonaws.com/<key>`). It's assumed AWS credentials are configured in the environment used to run `gomason`. If other AWS programs and tools work, `gomason` should too - so long as you have permission to write to the configured bucket(s).
Some information in ```metadata.json```, such as signing info can be overwritten by the [User Config](#user-config) detailed below.
Example metadata file:
{
"version": "1.0.0",
"package": "github.com/nikogura/gomason/v2",
"description": "A tool for testing, building, signing, and publishing your project from a clean workspace.",
"repository": "http://localhost:8081/artifactory/generic-local",
"tool-repository": "http://localhost:8081/artifactory/generic-local-tools",
"insecure_get": false,
"language": "golang",
"building": {
"prepcommands": [
"go get k8s.io/client-go/...",
"cd ${GOPATH}/src/k8s.io/client-go && git checkout v10.0.0",
"cd ${GOPATH}/src/k8s.io/client-go && godep restore ./..."
],
"targets": [
{
"name": "darwin/amd64",
"cgo": true,
"flags": {
"CC": "o64-gcc",
"CXX": "o64-g++"
},
"ldflags": "-X github.com/nikogura/dbt/pkg/dbt.METADATA_TEMPLATE=${METADATA_TEMPLATE}"
{
"name": "linux/amd64"
}
]
},
"signing": {
"program": "gpg",
"email": "[email protected]"
},
"publishing": {
"targets": [
{
"src": "gomason_darwin_amd64",
"dst": "{{.Repository}}/gomason/{{.Version}}/darwin/amd64/gomason",
"sig": true,
"checksums": false
},
{
"src": "gomason_linux_amd64",
"dst": "{{.Repository}}/gomason/{{.Version}}/linux/amd64/gomason",
"sig": true,
"checksums": false
}
]
}
}
## User Config
User configuration is accomplished by the file ```~/.gomason```. This is an *ini* formatted file that contains user level information such as the identity of the signer for use when signing binaries.
An example ```~/.gomason```:
[user]
email = [email protected]
username = nikogura
passwordfunc = lpass show --notes gomason-test
[signing]
program = gpg
email = [email protected]
This config would use the gpg program to sign binaries with the author's private key. Obviously a key for the listed user must exist within gpg's keychain for this to function.
This example also uses the LastPass cli to get the publishing password. Neat huh?
User config, if set, overrides any project config.
See [User Config Reference](#user-config-reference) for more details.
## Usage
* NOTE: you must have a ```metadata.json``` in your project as described in [Project Config Reference](#project-config-reference) below.
### Testing
Example Minimum Config:
{
"package": "github.com/nikogura/gomason/v2",
"version": "0.1.0",
"description": "A tool for building and testing your project in a clean GOPATH."
}
Run:
gomason test
### Building
Example Minimum Config:
{
"package": "github.com/nikogura/gomason/v2",
"version": "0.1.0",
"description": "A tool for building and testing your project in a clean GOPATH.",
"building": {
"targets": [
{
"name": "darwin/amd64",
{
"name": "linux/amd64"
}
]
}
}
Run:
gomason build
The binaries will be moved into the current working directory.
### Signing
Example Config (Shared Key Signing):
{
"package": "github.com/nikogura/gomason/v2",
"version": "0.1.0",
"description": "A tool for building and testing your project in a clean GOPATH.",
"building": {
"targets": [
"darwin/amd64",
"linux/amd64"
]
},
"signing": {
"program": "gpg",
"email": "[email protected]"
},
}
Run:
gomason sign
The binaries and their signatures will be dumped into the current working directory.
Example Config (Personal Key Signing):
{
"package": "github.com/nikogura/gomason/v2",
"version": "0.1.0",
"description": "A tool for building and testing your project in a clean GOPATH.",
"building": {
"targets": [
"darwin/amd64",
"linux/amd64"
]
}
}
```~/.gomason```:
[user]
email = [email protected]
[signing]
program = gpg
Run:
gomason sign
The binaries and their signatures will be dumped into the current working directory.
### Publishing
Example Config (Personal Key Signing, Personal Credentials):
{
"package": "github.com/nikogura/gomason/v2",
"version": "0.1.0",
"description": "A tool for building and testing your project in a clean GOPATH.",
"repository": "http://localhost:8081/artifactory/generic-local",
"building": {
"targets": [
{
"name": "darwin/amd64",
{
"name": "linux/amd64"
}
]
},
"publishing": {
"targets": [
{
"src": "gomason_darwin_amd64",
"dst": "{{.Repository}}/gomason/{{.Version}}/darwin/amd64/gomason",
"sig": true,
"checksums": false
},
{
"src": "gomason_linux_amd64",
"dst": "{{.Repository}}/gomason/{{.Version}}/linux/amd64/gomason",
"sig": true,
"checksums": false
}
]
}
}
```~/.gomason```:
[user]
email = [email protected]
username = nikogura
password = $ecretY0uNoR3ad!
[signing]
program = gpg
Run:
gomason publish
Example Config (Shared Key Signing, Shared Credentials):
{
"package": "github.com/nikogura/gomason/v2",
"version": "0.1.0",
"description": "A tool for building and testing your project in a clean GOPATH.",
"repository": "http://localhost:8081/artifactory/generic-local",
"building": {
"targets": [
{
"name": "darwin/amd64",
{
"name": "linux/amd64"
}
]
},
"signing": {
"program": "gpg",
"email": "[email protected]"
},
"publishing": {
"targets": [
{
"src": "gomason_darwin_amd64",
"dst": "{{.Repository}}/gomason/{{.Version}}/darwin/amd64/gomason",
"sig": true,
"checksums": false
},
{
"src": "gomason_linux_amd64",
"dst": "{{.Repository}}/gomason/{{.Version}}/linux/amd64/gomason",
"sig": true,
"checksums": false
}
],
"username": "nikogura",
"password": "$ecretY0uNoR3ad!"
}
}
Run:
gomason publish
### Publishing without Signing.
Occasionally, it might be useful to test and publish, but not sign. Internal use for instance, where you don't really have a web of trust set up.
In that case, set "skip-signing": true in the publishing section and gomason will publish without bothering with the signatures.
Example:
{
"package": "github.com/nikogura/gomason/v2",
"version": "0.1.0",
"description": "A tool for building and testing your project in a clean GOPATH.",
"repository": "http://localhost:8081/artifactory/generic-local",
"building": {
"targets": [
{
"name": "darwin/amd64",
{
"name": "linux/amd64"
}
]
},
"publishing": {
"skip-signing": true,
"targets": [
{
"src": "gomason_darwin_amd64",
"dst": "{{.Repository}}/gomason/{{.Version}}/darwin/amd64/gomason",
"sig": true,
"checksums": false
},
{
"src": "gomason_linux_amd64",
"dst": "{{.Repository}}/gomason/{{.Version}}/linux/amd64/gomason",
"sig": true,
"checksums": false
}
]
}
}
### Building and Publishing Without Testing
This is generally not a great idea, but one common use case for `gomason` is to make your own builds of some third party code with some custom flags. In this case you often don't want or need the full range of testing or test targets, or don't have access to the author's test system.
Sometimes you just want to build the damn code and publish it somewhere. In those cases, run:
gomason [build | publish] -s [--skip-tests]
Please don't do this with your own code. It makes <insert deity here> cry.
---
## Project Config Reference
Gomason depends on a metadata file imaginatively named 'metadata.json'. It's expected to be in the root of the repo.
The metadata file contains such information as the version. (Yes, I'm old fashioned that way. I like human readable version numbers.)
Example:
{
"version": "0.1.0",
"package": "github.com/nikogura/gomason/v2",
"description": "A tool for building and testing your project in a clean GOPATH.",
"repository": "http://localhost:8081/artifactory/generic-local",
"tool-repository": "http://localhost:8081/artifactory/generic-local-tools",
"language": "golang",
"building": {
"prepcommands": [
"go get k8s.io/client-go/...",
"cd ${GOPATH}/src/k8s.io/client-go && git checkout v10.0.0",
"cd ${GOPATH}/src/k8s.io/client-go && godep restore ./..."
],
"targets": [
{
"name": "darwin/amd64",
},
{
"name": "linux/amd64"
}
]
}
}
### Version
Semantic version string of your package. I realize go's github dependency mechanism provides commit-level granularity, but honestly? Is that really useful?
When's the last time you looked at a commit hash and derived any meaning around how much this version has changed from the last one you depended on? I'm a fan of the idea that the major/minor/patch contract of semantic versioning can help you estimate, at a glance, how much of a change that upgrade you're pondering will be.
Sure, it needs to be tested. (Trust but verify, right?) But it's really nice to be able to have that estimate in a glance before you devote resources to the upgrade, even if it's just a quick estimate in your head.
### Package
The name of the Go package as used by 'go get'. Used to actually check out the code in the clean build environment.
### Description
A nice, human readable description for your module, cos that's really nice. Having it in a parsable location as a simple string is also useful for other things, as you can probably imagine.
### Repository
The url of the repository to which you're planning to publish your binaries.
### Tool-Repository
The url of a secondary repository to which you're planning to publish your binaries. Primarily intended for use by (dbt)[https://github.com/nikogura/dbt].
### Insecure_Get
Sometimes you've got a code repo that has a self signed cert. Set this to true, and it'll pass ```-insecure``` to ```go get``` and ```govendor sync``` so you can still run- even if your internal repo has a self signed cert on it.
### Language
Optional at this point, and the only legal value is `golang`. We plan to support other languages that can compile to single binaries in the future.
### Building
Information specifically for building the project.
#### Prepcommands
These are a list of bash commands that will be run prior to running any command that acutally uses your code, such as `go test'.
Frequently Asked Questions
What is gomason?
gomason is a Continuous Integration library for the Go programming language. Test, Build, Sign, and Publish your go binaries from a clean workspace
How do I install gomason?
Install gomason with the Go module system using `go get nikogura/gomason`. Check the repository for the current installation instructions.
What category does gomason belong to?
gomason is listed under Continuous Integration, specifically Continuous Integration.