Woodhouse is a command line utility (and PHP library) for publishing build artifacts such as test reports and code coverage metrics to a GitHub pages repository. It was originally designed to run in a Travis CI build, but can be used in any environment.
- Download executable PHAR
- Install via Composer package icecave/woodhouse
The most basic use of Woodhouse is to publish build artifacts.
$ woodhouse publish bob/widget report.html:artifacts/tests.html --auth-token 0be..8a3
The example above publishes a file called report.html in the current directory to artifacts/tests.html in the gh-pages branch of the bob/widget GitHub repository. Multiple artifacts can be published in a single commit by specifying additional source:destination pairs. The source path may reference individual files or directories.
Woodhouse is able to parse several common test report formats to deduce the result of a build and publish an appropriate status image. This image can be used in a GitHub README.md file or on a website to show the current status of the build.
$ woodhouse publish bob/widget --build-status-image img/status.png --build-status-junit junit.xml --auth-token 0be..8a3
This example parses junit.xml to determine the build status, and then publishes the appropropriate status image to img/status.png. The images at the top of this document are published in this way.
The supported test report formats are:
- JUnit XML
- TAP (Test Anything Protocol)
- PHPUnit JSON
You can also specify the build status directly on the command line using the --build-status-result option.
Much like the build status images, Woodhouse can also publish images showing code coverage percentages.
$ woodhouse publish bob/widget --coverage-image img/coverage.png --coverage-phpunit coverage.txt --auth-token 0be..8a3
This example parses coverage.txt (A file created using PHPUnit's --coverage-text option) to determine
the coverage percentage, and then publishes the appropropriate image to img/coverage.png.
You can also specify the coverage percentage directly on the command line using the --coverage-percentage option.
Woodhouse uses ezzatron/ci-status-images for the build status and
coverage images. There are several themes and variants available. The desired theme(s) can be chosen with the
--image-theme option. The default theme is travis/variable-width.
Woodhouse requires a GitHub OAuth token with write access to publish content.
THIS TOKEN MUST BE KEPT SECURE, ANYONE WITH ACCESS TO THIS TOKEN CAN MANIPULATE YOUR GITHUB ACCOUNT
Under Travis CI, encrypted environment variables
can be used to store the token such that it can only be decrypted by Travis. To complement this feature, Woodhouse
provides the --auth-token-env option to read the token from an environment variable, preventing it from being logged
to the console.
Please note that although it is tempting to create a separate GitHub account solely for publishing of artifacts, this is explicitly prohibited by GitHub's Terms of Service.
A GitHub token can be created using the github:create-auth command. This only needs to be done once for your GitHub
account.
$ woodhouse github:create-auth
You will be prompted for your GitHub username and password. These credentials are used to create the authorization via the GitHub API and are not stored.
If you suspect your token has been compromised, it can be revoked on the application settings
page, or using the github:delete-auth command.
$ woodhouse github:list-auth # To get a list of authorizations.
158534: 0be..8a3 Woodhouse (API) [repo] https://github.com/IcecaveStudios/woodhouse
$ woodhouse github:delete-auth 158534 # The authorization ID from above.
You will then need to create a new token as described above.
- Follow @IcecaveStudios on Twitter
- Visit the Icecave Studios website
- Join
#icecaveon irc.freenode.net