README

Woodhouse是一个命令行工具（以及PHP库），用于将构建工件（如测试报告和代码覆盖率指标）发布到GitHub页面仓库。最初它是为了在Travis CI构建中运行而设计的，但也可以在任何环境中使用。

• 下载可执行PHAR文件
• 通过Composer包icecave/woodhouse安装

功能

发布工件

Woodhouse最基本的使用是发布构建工件。

$ woodhouse publish bob/widget report.html:artifacts/tests.html --auth-token 0be..8a3

上面的示例将当前目录中名为report.html的文件发布到GitHub仓库bob/widget的gh-pages分支的artifacts/tests.html中。可以通过指定额外的source:destination对来在单个提交中发布多个工件。源路径可以引用单个文件或目录。

构建状态徽章

Woodhouse能够解析几种常见的测试报告格式，以推断构建结果并发布相应的状态图像。此图像可用于GitHub README.md文件或网站上显示构建的当前状态。

$ woodhouse publish bob/widget --build-status-image img/status.png --build-status-junit junit.xml --auth-token 0be..8a3

此示例解析junit.xml以确定构建状态，然后将相应的状态图像发布到img/status.png。本文件顶部的图像也是以这种方式发布的。

支持的测试报告格式包括

• JUnit XML
• TAP（测试任何协议）
• PHPUnit JSON

您也可以使用--build-status-result选项在命令行上直接指定构建状态。

覆盖率徽章

与构建状态图像类似，Woodhouse还可以发布显示代码覆盖率百分比的图像。

$ woodhouse publish bob/widget --coverage-image img/coverage.png --coverage-phpunit coverage.txt --auth-token 0be..8a3

此示例解析使用PHPUnit的--coverage-text选项创建的coverage.txt文件以确定覆盖率百分比，然后将相应的图像发布到img/coverage.png。

您也可以使用--coverage-percentage选项在命令行上直接指定覆盖率百分比。

图像主题

Woodhouse使用ezzatron/ci-status-images构建状态和覆盖率图像。有几种主题和变体可供选择。可以使用--image-theme选项选择所需的主题。默认主题是travis/variable-width。

安全

Woodhouse需要一个具有写入权限的GitHub OAuth令牌来发布内容。

此令牌必须保持安全，任何拥有此令牌的人都可以操纵您的GitHub账户

在 Travis CI 中，可以使用 加密环境变量 来存储令牌，这样只有 Travis 能够解密它。为了补充这个特性，Woodhouse 提供了 --auth-token-env 选项，可以从环境变量中读取令牌，从而防止它在控制台中被记录。

请注意，虽然单独创建一个 GitHub 账户专门用于发布工件很诱人，但 GitHub 的 服务条款 明确禁止这样做。

创建 GitHub 令牌

可以使用 github:create-auth 命令创建 GitHub 令牌。对于您的 GitHub 账户，这只需要做一次。

$ woodhouse github:create-auth

您将被提示输入 GitHub 用户名和密码。这些凭证用于通过 GitHub API 创建授权，并且不会被存储。

撤销 GitHub 令牌

如果您怀疑您的令牌已被泄露，可以在 应用程序设置 页面或使用 github:delete-auth 命令撤销它。

$ 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.

然后，您需要按照上述说明创建新的令牌。

联系我们

• 关注 @IcecaveStudios
• 访问 Icecave Studios 网站
• 加入 #icecave 在 irc.freenode.net