NAV

Introduction

Welcome to the documentation of issue-runner, a toolkit to retrive, set up and run Minimal Working Examples (MWEs).

issue-runner supports MWEs defined in markdown files (such as the first comment in a GitHub issue), and external tarball(s)/zipfile(s)/file(s) can be included. It extracts sources to separate files, (optionally) invokes docker, executes the entrypoint, and cleans up.

Furthermore, a GitHub Action (GHA) is provided, which allows to easily integrate the tool in (scheduled) YAML workflows.

Installation

Set up a GitHub Actions workflow

A minimal YAML workflow file:

name: 'issue?'
on:
  issues:
    types: [ opened, edited ]
jobs:
  mwe:
    runs-on: ubuntu-latest
    steps:
    - uses: umarcor/issue-runner@gha-v1
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
        allow-host: false

Note that with parameters are both optional:

CLI tool

The CLI tool is a static binary written in golang, which can optionally use docker. It can be downloaded from github.com/umarcor/issue-runner/releases, or it can be built from sources.

git clone https://github.com/umarcor/issue-runner
cd tool
go build -o issue-runner

Usage

Supported markdown syntax

Language definition string containing :file:.*:

```sh :file: hello.sh
#!/usr/bin/env sh
echo "Hello world!"
```

Body containing :file:.* as a comment (that depends on the target language):

```sh
#!/usr/bin/env sh
echo "Hello world!"
#:file: hello.sh
```

External files with the name to the reference matching :mwe:.*:

[:mwe:filename.ext.txt](URL)
[:mwe:filename.tar.gz](URL)

issue-runner scans the (markdown) body to extract:

Entrypoint

Language definition string containing :image:.*

```sh :image: debian:buster-slim
echo "Hello world!"
```

Body containing :image:.* as a comment (that depends on the target language):

```py
#!/usr/bin/env python3

print('Hello world!')

#:image: python:slim-buster
```

One, and only one, of the code blocks should contain :image:.* instead of :file:.*. That file will be the entrypoint to an OCI container.

Alternatively, if no :image: is defined, the file which is named run will be used as the entrypoint to execute the MWE on the host.

CLI

Providing a list of identifiers is supported:

issue-runner 'tests/md/vunit-sh.md' 'VUnit/vunit#337' 'ghdl/ghdl#579'
# or
issue-runner 'ghdl/ghdl#584' 'https://raw.githubusercontent.com/umarcor/issue-runner/master/tests/md/vunit-py.md'

At least one of the following references needs to be provided:

MWEs defined in a single file/body can be read through stdin:

cat ./tests/md/hello001.md | ./issue-runner -
# or
./issue-runner -y - < ./tests/md/hello003.md

Docker container

Instead of installing issue-runner on the host, the CLI tool can be used as a container. In this context, execution on the host refers to executing the MWEs in the same container. Running sibling containers is supported too; however, it requires a named volume (issues:/volume) and the socket of the daemon to be bind.

Execution of MWEs on sibling containers:

docker run --rm \
  -v //var/run/docker.sock://var/run/docker.sock \
  -v issues://volume \
  umarcor/issue-runner <ref>

Development

issue-runner is composed of:

Build and test inside a container

The CLI can be developed in an official golang (or golang:alpine) container. See Usage for information about required binds.

docker run --rm -it \
  -v /$(pwd)://src \
  -w //src \
  -v //var/run/docker.sock://var/run/docker.sock \
  -v issues://volume \
  golang bash

Internal execution steps

Each time an issue is created or edited:

Create a new release branch

cp action.yml dist/
git checkout --orphan <BRANCH>
git rm --cached -r .
git add dist
git clean -fdx
git mv dist/* ./

git commit -am <release message>
git push origin <release branch name>

master branch of this repository contains the TypeScript sources of the action. However, these need to be compiled. A job in workflow push.yml is used to update branch gha-tip after each push that passes the tests. This kind of auto-updated branches need to be manually created the first time.

Continuous integration

After each commit is pushed to master:

ToDo