Browse files

Updated README (fixes #8)

  • Loading branch information...
1 parent 0ec09b2 commit 45b57c997735b6bfe7df2445a90b143b931beff4 @jmalloc jmalloc committed Jan 31, 2013
Showing with 88 additions and 1 deletion.
  1. +88 −1
@@ -3,12 +3,17 @@
[![Build Status](](
[![Test Coverage](](
-**Woodhouse** provides a simple way to publish your PHPUnit code coverage reports to GitHub pages. It was originally designed to run in a [Travis CI]( build, but can be used in any environment.
+**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.
## Installation
**Woodhouse** requires PHP 5.3.3 or later.
+### Download executable
+* Run `curl > near` or [download now](
### With [Composer](
* Add 'icecave/woodhouse' to the project's composer.json dependencies
@@ -19,3 +24,85 @@
* Clone from GitHub: `git clone git://`
* Use a [PSR-0](
compatible autoloader (namespace 'Icecave\Woodhouse' in the 'lib' directory)
+## Features
+### Publishing artifacts
+The most basic feature of **Woodhouse** is publication of build artifacts. Artifacts are
+specified as pairs of source and destination paths, separated by colons.
+ $ woodhouse bob/widget report.html:artifacts/tests.html --auth-token 0bee...8a33
+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.
+Many artifacts can be published in a single commit by specifying multiple source:destination pairs.
+The source path may reference individual files or directories.
+### Build status badges
+**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 your GitHub README file or on
+a website to show the current status of the build. The images at the top of this document are
+published in this way.
+ $ woodhouse bob/widget --build-status-image img/status.png --build-status-junit junit.xml --auth-token 0bee...8a33
+This example parses `junit.xml` to determine the build status, and then publishes the appropropriate
+status image to `img/status.png`.
+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.
+### Coverage badges
+Much like the build status images, **Woodhouse** can also publish images showing the percentage of the code based covered by tests.
+ $ woodhouse bob/widget --coverage-image img/coverage.png --coverage-phpunit coverage.txt --auth-token 0bee...8a33
+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.
+More coverage formats will be supported in a future version.
+### Image themes
+**Woodhouse** uses [ezzatron/ci-status-images]( as a source 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.
+If no theme is specified [travis/variable-width]( is used.
+## Security
+**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 masquerade as you on GitHub.**
+If you are using [Travis CI]( you can use
+[encrypted environment variables]( to
+store your token such that it can only be decrypted by Travis. To complement this feature, **Woodhouse** provides the
+`--auth-token-env` option to read your 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 for publishing of artifacts, this is explicitly
+prohibited by the [GitHub Terms of Service](
+### Creating a GitHub token
+To acquire a GitHub token you need to create an authorization using the
+[GitHub API]( This only needs to be done once for your
+GitHub account (not for each repository). The command below can be used to create such an authorization.
+ $ curl -u <github-username> \
+ -d '{"scopes":["repo"],"note":"icecave/woodhouse"}' \
+### Revoking a GitHub token
+If you suspect your token has been compromised, it can be revoked on the [application settings]( page.
+You will then need to create a new token as described above.

0 comments on commit 45b57c9

Please sign in to comment.