├── .dockerignore ├── .github └── FUNDING.yml ├── Dockerfile ├── README.md ├── action.yml └── entrypoint.sh /.dockerignore: -------------------------------------------------------------------------------- 1 | # ignore all files by default 2 | * 3 | # include required files with an exception 4 | !entrypoint.sh 5 | !README.md 6 | -------------------------------------------------------------------------------- /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | # These are supported funding model platforms 2 | github: skx 3 | custom: https://steve.fi/donate/ 4 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | FROM golang:latest 2 | 3 | LABEL "com.github.actions.name"="github-action-tester" 4 | LABEL "com.github.actions.description"="Run tests against pull requests" 5 | LABEL "com.github.actions.icon"="eye" 6 | LABEL "com.github.actions.color"="gray-dark" 7 | 8 | LABEL version="1.0.0" 9 | LABEL repository="http://github.com/skx/github-action-tester" 10 | LABEL homepage="http://github.com/skx/github-action-tester" 11 | LABEL maintainer="Steve Kemp " 12 | 13 | COPY "entrypoint.sh" "/entrypoint.sh" 14 | RUN chmod +x /entrypoint.sh 15 | ENTRYPOINT ["/entrypoint.sh"] 16 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | 2 | # GitHub Action for Running tests 3 | 4 | This repository contains a simple GitHub Action which allows you to run a shell-script every time an event occurs within your repository. 5 | 6 | * [GitHub Action for Running tests](#github-action-for-running-tests) 7 | * [Overview](#overview) 8 | * [Enabling the action](#enabling-the-action) 9 | * [Sample Configuration](#sample-configuration) 10 | * [Advanced Configuration](#advanced-configuration) 11 | 12 | 13 | ## Overview 14 | 15 | 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. 16 | 17 | 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. 18 | 19 | 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: 20 | 21 | #!/bin/sh 22 | # Run the go-vet tool. 23 | go vet ./.. || exit 1 24 | # Run the test-cases, with race-detection. 25 | go test -race ./... || exit 1 26 | # Everything passed, exit cleanly. 27 | exit 0 28 | 29 | A C-based project could contain something like this instead: 30 | 31 | #!/bin/sh 32 | make && make test 33 | 34 | But as you can install/invoke arbitrary commands, and update them as your project grows, you can do almost anything you wish. 35 | 36 | 37 | 38 | ## Enabling the action 39 | 40 | There are two steps required to use this action: 41 | 42 | * Enable the action inside your repository. 43 | * You'll probably want to enable it upon pull-requests, to ensure their quality. 44 | * You might also want to enable it to run each time a push is made to your repository, for completeness. 45 | * Add your project-specific test-steps to a script in your repository. 46 | * By default this action will execute `.github/run-tests.sh`, but you can specify a different name if you prefer. 47 | * The exit-code of your script will determine the result. 48 | 49 | 50 | 51 | ## Sample Configuration 52 | 53 | Defining Github Actions requires that you create a directory `.github/workflows` inside your repository. Inside the workflow-directory you create files which are processed when various events occur. 54 | 55 | For example: 56 | 57 | * .`github/workflows/pull_request.yml` 58 | * This is used when a pull-request is created/updated upon your repository. 59 | * `.github/workflows/push.yml` 60 | * This is used when a commit is pushed to your repository. 61 | 62 | The simplest example of using this action would be to create the file `.github/workflows/pull_request.yml` with the following contents: 63 | 64 | ```yml 65 | on: pull_request 66 | name: Pull Request 67 | jobs: 68 | test: 69 | name: Run tests 70 | runs-on: ubuntu-latest 71 | steps: 72 | - uses: actions/checkout@master 73 | - name: Test 74 | uses: skx/github-action-tester@master 75 | ``` 76 | 77 | This example will run the default test-script, `.github/run-tests.sh`, every time a pull-request is created, edited, or updated. 78 | 79 | 80 | 81 | ## Advanced Configuration 82 | 83 | As noted github actions can be launched on multiple events, for example pushes to branches, new releases, pull-request related events, and similar. 84 | 85 | 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. 86 | 87 | 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). 88 | 89 | As an example you might create a workflow for use solely with pushes to master, in the file `.github/workflows/push.yml`: 90 | 91 | ```yml 92 | on: 93 | push: 94 | branches: 95 | - master 96 | name: Push Event 97 | jobs: 98 | test: 99 | name: Run tests 100 | runs-on: ubuntu-latest 101 | steps: 102 | - uses: actions/checkout@master 103 | - name: Test 104 | uses: skx/github-action-tester@master 105 | with: 106 | script: .github/fast-tests.sh 107 | ``` 108 | 109 | Here we've done two things: 110 | 111 | * We've limited the action to only apply to pushes made to the `master` branch. 112 | * We've explicitly set the name of the testing-script to `.github/fast-tests.sh` 113 | * With the expectation this script contains only "quick" tests. 114 | * With slower tests being applied to pull-requests. 115 | -------------------------------------------------------------------------------- /action.yml: -------------------------------------------------------------------------------- 1 | name: 'github-action-tester' 2 | description: 'Run tests when pull-requests are opened, or commits pushed.' 3 | author: 'Steve Kemp' 4 | branding: 5 | icon: eye 6 | color: black 7 | inputs: 8 | script: 9 | description: 'The path to the test-script to run, within the repository.' 10 | default: '.github/run-tests.sh' 11 | runs: 12 | using: 'docker' 13 | image: 'Dockerfile' 14 | args: 15 | - ${{ inputs.script }} 16 | -------------------------------------------------------------------------------- /entrypoint.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # 3 | # The core of our action, it will be invoked with the name of the script 4 | # to execute - If the script doesn't exist then that is a fatal error. 5 | # 6 | # The script used to default to `.github/run-tests.sh`, but now the 7 | # name is passed as the first argument. 8 | # 9 | 10 | # 11 | # Terminate upon errors 12 | # 13 | set -e 14 | 15 | 16 | # 17 | # Get the name of the script to run. 18 | # 19 | script=$1 20 | 21 | 22 | # 23 | # If the argument is empty that is a fatal error. 24 | # 25 | if [ -z "${script}" ]; then 26 | echo "You must specify the script to execute as an argument." 27 | exit 1 28 | fi 29 | 30 | 31 | # 32 | # If the script does not exist that is a fatal-error. 33 | # 34 | if [ ! -e "${script}" ]; then 35 | echo "The supplied testing-script does not exist: ${script}" 36 | exit 1 37 | fi 38 | 39 | 40 | # 41 | # Ensure the script is executable. 42 | # 43 | chmod 755 "${script}" 44 | 45 | 46 | # 47 | # Run it. 48 | # 49 | ${script} 50 | 51 | 52 | # 53 | # If the script exits with a non-zero status-code 54 | # then it will terminate this script due to the use 55 | # of `set -e`. 56 | # 57 | # So when we reach this point we know: 58 | # 59 | # 1. We've executed the test-script. 60 | # 61 | # 2. The test-script passed. 62 | # 63 | # Exit cleanly because we're done. 64 | # 65 | exit 0 66 | 67 | 68 | # 69 | # There is no test-script within the repository. 70 | # 71 | # Show that, and exit with a failure-code. 72 | # 73 | echo "The repository does not contain a test-script '.github/run-tests.sh'" 74 | exit 1 75 | --------------------------------------------------------------------------------