Skip to content

Latest commit

 

History

History
150 lines (103 loc) · 5.94 KB

cli.md

File metadata and controls

150 lines (103 loc) · 5.94 KB
Raw

The actions-go-build CLI

All the core logic in this action is contained in the actions-go-build CLI, which is defined here (see main.go).

This CLI is designed to be usable on developer machines as well as in CI, so it can be used as a regular part of the day-to-day development of applications.

Example Usage

Some things you might want to use the tool for when working locally.

# Just build the `main` package in the current directory.
$ actions-go-build build

# Check that the `main` package in the current directory is reproducible.
$ actions-go-build verify

# Build the `main` package in ./cmd/product1
$ actions-go-build build ./cmd/product1

# Check that the `main` package in ./cmd/product1 is reproducible.
$ actions-go-build verify ./cmd/product1

# Export a build result json file for the project I'm working on.
$ actions-go-build build -o my.buildresult.json

# Verify a build result generated by someone else is reproducible on your machine.
$ actions-go-build verify other.buildresult.json

Installation

Run make install to install the CLI.

Usage

The two main uses of this CLI are building and verifying builds.

Core Concepts

We run build to produce a build result. Build can build any "buildish". A buildish is a thing that has build configuration, e.g. a locally checked out repo containing source code, or a file containing explicit build configuration.

We run verify to compare two build results and produce a verification result. Because all buildishes can be converted to build results by executing the build, we can verify two builds done locally, two build results files, or a new build against an old build result file.

Building

The build subcommand is used to perform single builds. It can be used in place of go build to build your project. Every build not only produces the built artifacts, but also a build result which documents the build and its outcomes.

All builds require a build config, and this can be sourced from either local contextual information from the current directory and environment, or from a file containing explicit build configuration.

Running a Local Primary Build

A local primary build is just a normal build, inside a project directory, that produces an executable artifact, and a zip file containing that artifact (alongside other files if needed). By default it stores the binary file in ./dist and the zip file in ./out (these paths may change in the future).

  • Run actions-go-build build [.] to build the project in your current directory.
  • Run actions-go-build build some/dir to build the project in some/dir.

Add the -json flag to print out the full build result.

Running a Local Verification Build

A local verification build is very similar to a local primary build, except that it is done on a copy of the contents of the project directory, rather than inside the real directory. This is done to try to catch the accidental embedding of absolute paths inside your artifacts which tend to break reproducibility.

  • Run actions-go-build build -verification [.] to run a verification build for the project in the current directory.
  • Run actions-go-build build -verification some/dir to run a verification build for the project in some/dir.

Other Kinds of Builds

It's also possible to run 'remote builds' using the build subcommand. These are builds that are defined by a blob of build configuration, either on its own or embedded in a build result or verification result defined elsewhere. To run these kinds of builds, you need to pass a path to a JSON file containing build config (instead of a path to a directory containing source code). This is an uncommon use case so it's not yet documented in full here.

Verifying

The verify subcommand is used to verify that a build is reproducible. It can verify that any de-facto build defined by source code and config in a local directory is reproducible, or that a build result generated previously is reproducible.

Every verification produces a verification result which documents all the inputs and outputs of a pair of builds, all their results, and whether or not they represent a reproducible build.

Verifying a Local Project is Reproducible

  • Run actions-go-build verify [.] to run both a primary and verification build using the code and configuration in the current directory and environment, and compare the results.
  • Run actions-go-build verify some/dir to run both a primary and verification build using the code and configuration in some/dir and the local environment, and compare the results.

Verifying a Remotely-Generated Build Result is Reproducible.

  • Run actions-go-build verify some.buildresult.json to run a verification build based on the build config used for the build in some.buildresult.json and compare the verification build result with that build result and report if it reproduced correctly.

Build Configs

A build config is a complete set of configuration needed to define a build on a specific machine. Without any explicit configuration, there is still a de-facto build config. You can view what it looks like for a given repository, on a given machine by running:

$ actions-go-build inspect -build-config

If you have a file containing build configuration, you can inspect that configuration by passing that filename to the inspect subcommand:

$ actions-go-build inspect -build-config some.build.config.json

The file you pass can either be a bare build config, or a build result file, or even a verification result file. As long as the file is one of these kinds, the build config will be pulled out and displyed.

Verification Build Configs

You can view the "verification build" version of any build config by supplying the -verification flag to the inspect subcommand, e.g.:

$ actions-go-build inspect -build-config -verification

Build Results

Verification Results