Gobra Action

This action adds Gobra to the CI Workflow of Go projects.

Usage

See action.yml

Examples

Simple set-up without caching

uses: viperproject/gobra-action@main
  with:
    caching: 0
    javaXss: 64m
    globalTimeout: 1h
    packageTimeout: 10m
    projectLocation: go

Set-up with caching

This configuration shows how to set-up the Gobra Action to store the verification results in ${{ runner.workspace }}/.gobra/cache.json. This file is loaded on subsequent runs of the Gobra Action and all cached verification results will not be re-computed.

- name: Cache Viper Server cache
  uses: actions/cache@v2
  env:
    cache-name: vs-cache
  with:
    path: ${{ runner.workspace }}/.gobra/cache.json 
    key: ${{ env.cache-name }}
- name: Verify all Gobra files
  uses: viperproject/gobra-action@main
  with:
    caching: 1
    viperBackend: VSWITHSILICON

Using a JSON config

Gobra can read all of its options from JSON config files. The configFile input points either to a gobra.json file or to a directory containing one. A gobra-mod.json file, which holds the settings that are common to the entire module, must exist in the same directory or in one of its parent directories.

configFile is resolved against the directory in which the repository is checked out. A leading / is ignored, so go/pkg and /go/pkg both refer to go/pkg within the repository:

- name: Verify the package described by go/pkg/gobra.json
  uses: viperproject/gobra-action@main
  with:
    configFile: 'go/pkg'
    timeout: 1h

In this mode, Gobra reads all of its options from the JSON files, and it reports an error if one of them is passed on the command line as well. Setting overflow, viperBackend, files or any other input that maps to an option of Gobra therefore fails the step instead of being ignored. Options without a dedicated field in the JSON config can be set through its other field:

{
  "overflow": true,
  "other": ["--requireTriggers"]
}

The inputs that do not configure Gobra itself keep working: javaXss and javaXmx size the JVM, timeout bounds how long the step may run, and imageName and imageVersion select the Gobra image.

statsFile also keeps working. Gobra's JSON config has no field for -g and it cannot be passed next to --config, so the Action adds it to the other field of a generated copy of the job config, which it places next to the original and removes again after the run. A -g in the job config itself takes precedence over the input.

Caching is not available in this mode, since Gobra's JSON config has no field for --cacheFile either and the Action does not work around it. Setting caching next to configFile therefore fails the step.

Before verifying, the Action always runs Gobra once with --printConfig, so that the configuration resolved from the JSON files appears in the log of the step. If that run fails, the step fails without verifying anything.

Storing artifacts

There are two artifacts generated by this Action that are worth to be stored:

• the cache file, generated in ${{ runner.workspace }}/.gobra/cache.json.
• the statistics collected during verification, generated in ${{ runner.workspace }}/.gobra/stats.json.

The following snippet shows how to store these files as artifacts:

- name: Verify all Gobra files
  uses: viperproject/gobra-action@main
  with:
    caching: 1
    viperBackend: VSWITHSILICON
- name: Archive cache
  uses: actions/upload-artifact@v2
  with:
    name: cache
    path: ${{ runner.workspace }}/.gobra/cache.json
- name: Archive statistics report
  uses: actions/upload-artifact@v2
  with:
    name: stats
    path: ${{ runner.workspace }}/.gobra/stats.json     

License

The scripts and documentation in this project are released under the Mozilla Public License 2.0.