From 2f4cb6ac56787dffff626facc4f821e3b0aeb7da Mon Sep 17 00:00:00 2001 From: Steve Kemp Date: Mon, 28 Oct 2019 17:41:42 +0200 Subject: [PATCH 1/5] Define an argument, optional, to declare the script-name. Pass that option to our `entrypoint.sh` script, when it is launched. --- action.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/action.yml b/action.yml index 1d8307d..6aa33f7 100644 --- a/action.yml +++ b/action.yml @@ -4,6 +4,12 @@ author: 'Steve Kemp' branding: icon: eye color: black +inputs: + script: + description: 'The path to the test-script to run, within the repository.' + default: '.github/run-tests.sh' runs: using: 'docker' image: 'Dockerfile' + args: + - ${{ inputs.script }} From 3660e5f30ec8e19ee1ed2a863b1a886c9ec2bbf4 Mon Sep 17 00:00:00 2001 From: Steve Kemp Date: Mon, 28 Oct 2019 17:47:23 +0200 Subject: [PATCH 2/5] Use the argument passed by the metadata file. --- entrypoint.sh | 85 +++++++++++++++++++++++++++++++++------------------ 1 file changed, 56 insertions(+), 29 deletions(-) diff --git a/entrypoint.sh b/entrypoint.sh index a034dc2..a805538 100755 --- a/entrypoint.sh +++ b/entrypoint.sh @@ -1,42 +1,70 @@ #!/bin/bash +# +# The core of our action, it will be invoked with the name of the script +# to execute - If the script doesn't exist then that is a fatal error. +# +# The script used to default to `.github/run-tests.sh`, but now the +# name is passed as the first argument. +# # # Terminate upon errors # set -e + +# +# Get the name of the script to run. +# +script=$1 + + # -# If the script is present .. -# -if [ -e .github/run-tests.sh ]; then - - # - # Ensure it is executable. - # - chmod 755 .github/run-tests.sh - - # - # Run it. - # - .github/run-tests.sh - - # - # If the script exits with a non-zero status-code - # then it will terminate this script due to the use - # of `set -e`. - # - # So when we reach this point we know: - # - # 1. We've executed the test-script. - # - # 2. The test-script passed. - # - # Exit cleanly because we're done. - # - exit 0 +# If the argument is empty that is a fatal error. +# +if [ -z "${script}" ]; then + echo "You must specify the script to execute as an argument." + exit 1 +fi + + +# +# If the script does not exist that is a fatal-error. +# +if [ ! -e "${script}" ]; then + echo "The supplied testing-script does not exist: ${script}" + exit 1 fi +# +# Ensure the script is executable. +# +chmod 755 "${script}" + + +# +# Run it. +# +${script} + + +# +# If the script exits with a non-zero status-code +# then it will terminate this script due to the use +# of `set -e`. +# +# So when we reach this point we know: +# +# 1. We've executed the test-script. +# +# 2. The test-script passed. +# +# Exit cleanly because we're done. +# +exit 0 + + # # There is no test-script within the repository. # @@ -44,4 +72,3 @@ fi # echo "The repository does not contain a test-script '.github/run-tests.sh'" exit 1 - From 2ac114b1ed77b8b1e4c3802d2bfa7744bfab2f8d Mon Sep 17 00:00:00 2001 From: Steve Kemp Date: Mon, 28 Oct 2019 17:54:23 +0200 Subject: [PATCH 3/5] Updated to document the argument-passing and customization we now allow --- README.md | 50 +++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 45 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 78c1813..57e7d90 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ If your shell-script terminates with an exit-code of 0 that is regarded as a pas The expectation is that you'll use this action to launch your project-specific test-cases, ensuring that all pull-requests, commits, or both, are tested automatically. -Because the action ultimately just executes a shell-script contained in your repository, you can be as simple or complex as you can imagine. For example a [golang](https://golang.org/) project might contain a simple script such as this: +Because the action ultimately executes a shell-script contained in your repository, you can be as simple or complex as you can like. For example a [golang](https://golang.org/) project might contain a simple script such as this: #!/bin/sh # Run the go-vet tool @@ -24,6 +24,7 @@ A C-based project might contain something like this: But as you can install/invoke arbitrary commands, and update them as your project grows, you can do almost anything you wish. + ## Enabling the action There are two steps required to use this action: @@ -31,8 +32,10 @@ There are two steps required to use this action: * Enable the action inside your repository. * You'll probably want to enable it upon pull-requests, to ensure their quality. * You might also want to enable it to run each time a push is made to your repository, for completeness. -* Add your project-specific tests to the script `.github/run-tests.sh`. - * The exit-code of this script will determine the result. +* Add your project-specific test-steps to a script in your repository. + * By default this action will execute `.github/run-tests.sh`, but you can specify a different name if you prefer. + * The exit-code of your script will determine the result. + ## Sample Configuration @@ -46,7 +49,7 @@ For example: * `.github/workflows/push.yml` * This is used when a commit is pushed to your repository. -You can use content like this to invoke the action: +The simplest example of using this action would be to create the file `.github/workflows/pull_request.yml' with the following contents: ``` on: pull_request @@ -61,4 +64,41 @@ jobs: uses: skx/github-action-tester@master ``` -You can also limit the tests to only executing when specific branches are updated, and chain events. For more details please consult the [Github Actions documentation](https://developer.github.com/actions/). +This example will run the default test-script `.github/run-tests.sh` every time a pull-request is created, edited, or updated. + + + +## Advanced Configuration + +As noted github actions can be launched on multiple events, for example pushes to branches, new releases, pull-request related events, and similar. + +Because you probably wish to run different tests/scripts on these different events it is possible to override the name/path of the shell-script which is executed on a per-event basis. + +For example might wish to run thorough tests upon pull-requests, and a smaller subset when a push is made to your `master` branch (on the assumption that commits there are rare, and the usual workflow will have ensured the full-tests will have been executed via pull-requests). + +As an example you might create a workflow for use solely with pushes to master, in the file `.github/workflows/push.yml`: + +``` +on: + push: + branches: + - master +name: Push Event +jobs: + test: + name: Run tests + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@master + - name: Test + uses: skx/github-action-tester@master + with: + script: .github/fast-tests.sh +``` + +Here we've done two things: + +* We've limited the action to only apply to pushes made to the `master` branch. +* We've explicitly set the name of the testing-script to `.github/fast-tests.sh` + * With the expectation this script contains only "quick" tests. + * With slower tests being applied to pull-requests. From 702f1c68800d13999058fceda33b2c0abd48bfa9 Mon Sep 17 00:00:00 2001 From: Steve Kemp Date: Mon, 28 Oct 2019 17:57:06 +0200 Subject: [PATCH 4/5] Added ToC --- README.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 57e7d90..af040e1 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,32 @@ + # GitHub Action for Running tests This repository contains a simple GitHub Action which allows you to run a shell-script every time an event occurs within your repository. -If your shell-script terminates with an exit-code of 0 that is regarded as a pass, otherwise the action will be marked as a failure. +* [GitHub Action for Running tests](#github-action-for-running-tests) + * [Overview](#overview) + * [Enabling the action](#enabling-the-action) + * [Sample Configuration](#sample-configuration) + * [Advanced Configuration](#advanced-configuration) + + +## Overview + +This action allows you to run a shell-script when your workflow action is triggered. If your script terminates with an exit-code of 0 that is regarded as a pass, otherwise the action will be marked as a failure. The expectation is that you'll use this action to launch your project-specific test-cases, ensuring that all pull-requests, commits, or both, are tested automatically. -Because the action ultimately executes a shell-script contained in your repository, you can be as simple or complex as you can like. For example a [golang](https://golang.org/) project might contain a simple script such as this: +Because the action ultimately executes a shell-script contained in your repository you can be as simple or complex as you can like, for example a [golang](https://golang.org/) project might contain a script such as this: #!/bin/sh - # Run the go-vet tool + # Run the go-vet tool. go vet ./.. || exit 1 - # Run the test-cases + # Run the test-cases, with race-detection. go test -race ./... || exit 1 - # Everything passed. + # Everything passed, exit cleanly. exit 0 -A C-based project might contain something like this: +A C-based project could contain something like this instead: #!/bin/sh make && make test From f85c7aa5349cf978f5a48fb20d3233ec0e4f5ba3 Mon Sep 17 00:00:00 2001 From: Steve Kemp Date: Mon, 28 Oct 2019 17:58:22 +0200 Subject: [PATCH 5/5] Minor tweaks --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index af040e1..3a3559f 100644 --- a/README.md +++ b/README.md @@ -59,7 +59,7 @@ For example: * `.github/workflows/push.yml` * This is used when a commit is pushed to your repository. -The simplest example of using this action would be to create the file `.github/workflows/pull_request.yml' with the following contents: +The simplest example of using this action would be to create the file `.github/workflows/pull_request.yml` with the following contents: ``` on: pull_request @@ -74,7 +74,7 @@ jobs: uses: skx/github-action-tester@master ``` -This example will run the default test-script `.github/run-tests.sh` every time a pull-request is created, edited, or updated. +This example will run the default test-script, `.github/run-tests.sh`, every time a pull-request is created, edited, or updated. @@ -84,7 +84,7 @@ As noted github actions can be launched on multiple events, for example pushes t Because you probably wish to run different tests/scripts on these different events it is possible to override the name/path of the shell-script which is executed on a per-event basis. -For example might wish to run thorough tests upon pull-requests, and a smaller subset when a push is made to your `master` branch (on the assumption that commits there are rare, and the usual workflow will have ensured the full-tests will have been executed via pull-requests). +For example you might wish to run more thorough tests upon pull-requests, and a smaller subset when a push is made to your `master` branch (on the assumption that commits there are rare, and the usual workflow will have ensured the full-tests will have been executed via pull-requests). As an example you might create a workflow for use solely with pushes to master, in the file `.github/workflows/push.yml`: