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.


Set up a GitHub Actions workflow

A minimal YAML workflow file:

name: 'issue?'
    types: [ opened, edited ]
    runs-on: ubuntu-latest
    - uses: umarcor/issue-runner@gha-v1
        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, or it can be built from sources.

git clone
cd tool
go build -o issue-runner


Supported markdown syntax

Language definition string containing :file:.*:

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

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

#!/usr/bin/env sh
echo "Hello world!"

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


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


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):

#!/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.


Providing a list of identifiers is supported:

issue-runner 'tests/md/' 'VUnit/vunit#337' 'ghdl/ghdl#579'
# or
issue-runner 'ghdl/ghdl#584' ''

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/ | ./issue-runner -
# or
./issue-runner -y - < ./tests/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>


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: