Welcome to badwolf’s documentation!

badwolf is a Docker based continuous integration and code lint review system for BitBucket

https://travis-ci.org/bosondata/badwolf.svg?branch=master https://codecov.io/gh/bosondata/badwolf/branch/master/graph/badge.svg

User Guide:

安装配置

安装 Docker

请参考 Docker 官方文档 安装最新版本的 Docker

Standalone 模式

系统依赖：

  1. Python 2.7 和 Python 3.4+
  2. Docker
  3. Nodejs

可以通过以下 shell 命令配置系统：

curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get install -y software-properties-common python-dev python-software-properties python-setuptools python-pip git nodejs shellcheck
sudo npm install -g eslint csslint sass-lint jsonlint eslint-plugin-react eslint-plugin-react-native

然后使用 pip 安装 badwolf：

pip install -U badwolf

最后，通过以下命令启动 server：

badwolf runserver --port 8000

Docker 模式

获取 Docker 镜像

从 Docker Hub 上拉取镜像：

docker pull messense/badwolf

如果需要自行构建 Docker 镜像，可以在代码根目录中运行：

docker build --rm -t messense/badwolf .

运行

docker run \
--volume /var/run/docker.sock:/var/run/docker.sock \
--volume /var/lib/badwolf/log:/var/lib/badwolf/log \
--volume /tmp/badwolf:/tmp/badwolf \
--env-file ~/.badwolfrc \
--publish=8000:8000 \
--detach=true \
--restart=always \
--name=badwolf \
messense/badwolf

其中 ~/.badwolfrc 为 Docker 环境变量配置文件，配置示例：

SERVER_NAME=badwolf.example.com:8000
SECRET_KEY=top-secret
SECURE_TOKEN_KEY=\x18\xd5\xb5\xd0\xae\x9f\x05\xb3\x7fAO\x89h*\xd9\x8d.u\xa3\xf0U\xa22\xffOc\xe3\x19J\xeaX1
MAIL_SERVER=smtp.mailgun.org
MAIL_PORT=587
MAIL_USERNAME=badwolf@example.com
MAIL_PASSWORD=password
MAIL_SENDER_ADDRESS=badwolf@example.com
BITBUCKET_USERNAME=username
BITBUCKET_PASSWORD=password
SENTRY_DSN=http://username:password@sentry.example.com/1

配置 badwolf

对于 standalone 模式，可以通过多种方式配置：

  1. 在 badwolf 运行用户的 ~/.badwolf.conf.py 中配置
  2. 通过 BADWOLF_CONF 环境变量指定配置文件路径，并在此文件配置
  3. 通过各个独立环境变量配置

Docker 模式一般使用独立环境变量进行配置。

可供配置的项请参考 配置选项 文档。

Docker 镜像和容器日常清理

批量删除停止的无用的容器：

docker rm $(docker ps -a -q)

批量删除无用的镜像：

docker rmi $(docker images -q -f dangling=true)

配置选项

所以的配置都是可以通过环境变量进行配置。

基本配置

环境变量名称 默认值 说明
BADWOLF_DEBUG False debug 模式开关
SERVER_NAME localhost:8000 部署服务器域名
SECRET_KEY 空 Flask SECRET_KEY
SECURE_TOKEN_KEY 随机生成 .badwolf.yml 配置文件 secure token key
SENTRY_DSN 空 Sentry DSN URL
DOCKER_HOST unix:///var/run/docker.sock Docker host
DOCKER_API_TIMEOUT 600 docker-py timeout，单位秒
DOCKER_RUN_TIMEOUT 1200 Docker 测试运行时长限制，单位秒
AUTO_MERGE_ENABLED True 自动合并 PR 功能开关
AUTO_MERGE_APPROVAL_COUNT 3 自动合并 PR 需要的 Approval 数量
BITBUCKET_USERNAME 空 BitBucket 用户名
BITBUCKET_PASSWORD 空 BitBucket 用户密码，支持 app passwords
BADWOLF_DATA_DIR /var/lib/badwolf badwolf 数据目录
BADWOLF_REPO_DIR /var/lib/badwolf/repos badwolf 克隆仓库目录
BADWOLF_LOG_DIR /var/lib/badwolf/log badwolf 构建日志目录
VAULT_URL 空 Vault URL 全局配置
VAULT_ADDR 空 Vault URL 的别名
VAULT_TOKEN 空 Vault Token 全局配置

其中，SECURE_TOKEN_KEY 为 base64 URL-safe 编码的 32 bytes 字符串，可以使用 os.urandom(32) 生成：

import os
import base64

print(base64.urlsafe_b64encode(os.urandom(32)))

邮件服务器配置

环境变量名称 默认值 说明
MAIL_SERVER 空 邮件服务器地址
MAIL_PORT 587 邮件服务器端口
MAIL_USE_TLS True  
MAIL_USE_SSL False  
MAIL_USERNAME 空 邮件账户
MAIL_PASSWORD 空 邮件账户密码
MAIL_SENDER_NAME badwolf 发件人名称
MAIL_SENDER_ADDRESS 空 发件人邮件地址

构建和测试

项目接入

在项目根目录中提供 .badwolf.yml 文件，用于配置 CI 环境等，使用 YAML 语法。

可配置的项有：

选项名 类型 说明
image string 用于构建的 Docker 镜像，提供此选项时可不提供 dockerfile 选项
shell string 使用的 shell 程序，默认为 bash
docker boolean 挂载外部的 Docker sock 到容器中以便使用 Docker, 默认为 false
dockerfile string 用于构建 Docker 镜像的 dockerfile 文件名称, 默认为 Dockerfile
branch string/list 仅在这些分支上运行构建和测试
script string/list 构建/测试的命令
after_success string/list 构建/测试成功后运行的命令
after_failure string/list 构建/测试失败后运行的命令
service string/list 构建/测试前启动的服务，需要在 Dockerfile 中配置安装对应的软件包
env string 环境变量，如: env: X=1 Y=2 Z=3
linter string/list 启用的代码检查工具
notification.email string/list/object 邮件通知地址列表
notification.slack_webhook string/list/object Slack webhook 地址列表
privileged boolean 使用特权模式启动 Docker 容器
artifacts boolean/object 保存构建中产生的 artifacts
artifacts.paths string/list artifacts 路径
artifacts.excludes string/list 应该忽略的 artifacts (glob pattern)
vault.url string Vault URL
vault.token string Vault Token
vault.env string/list 从 Vault 读取的环境变量，格式为：ENV_NAME secret/path:key

请注意，当 image 和 dockerfile 选项同时提供时， image 选项优先使用。

然后，在 BitBucket 项目设置中配置 webhook，假设部署机器的可访问地址为：http://badwolf.example.com:8000， 则 webhook 地址应配置为：http://badwolf.example.com:8000/webhook/push。

也可以使用 HTTP API 自动配置 webhook，如：

curl -XPOST http://badwolf.example.com:8000/webhook/register/user1/repo1

构建运行时环境变量

变量名 值
DEBIAN_FRONTEND noninteractive
HOME /root
SHELL 设置的 shell 路径，如 /bin/bash, /bin/sh
TERM xterm-256color
CI true
CI_NAME badwolf
DOCKER_HOST unix:///var/run/docker.sock（开启 Docker 功能时存在）
BADWOLF_COMMIT 构建仓库的 git commit sha
BADWOLF_BUILD_DIR 构建目录路径（仓库克隆路径）
BADWOLF_REPO_SLUG 仓库 slug
BADWOLF_TAG git tag 名称（如果有）
BADWOLF_BRANCH git 分支名称
BADWOLF_PULL_REQUEST Bitbucket Pull Request ID（如果有）

Tips

  • 在 commit 的 message 中包含 ci skip 跳过测试
  • 在评论中包含 ci retry 重跑测试
  • 在评论或 commit message 或 Pull Request 的标题/描述中包含 ci rebuild 重新构建 Docker 镜像，同时包含 no cache 禁用 Docker 构建缓存
  • 在 Pull Request 的标题/描述中包含 merge skip 或者 wip 或者 working in progress 禁用自动合并 Pull Request 功能

代码检查

项目接入

请参考 构建和测试 文档接入项目，如不需要构建/测试可忽略相关配置， 对于代码检查，需要配置 linter 选项，如：

单个 linter 示例

linter: flake8

多个 linter 示例

linter:
  - flake8
  - eslint

自定义文件类型示例

可以通过配置 linter 的 pattern 来自定义 linter 需要处理的文件类型，支持 glob/正则表达式，如：

linter: {name: "jsonlint", pattern: "*.mapping"}

支持的代码检查工具

名称 编程语言 官网/文档地址
flake8 Python http://flake8.readthedocs.org/en/latest/
pycodestyle Python http://pycodestyle.readthedocs.org/en/latest/
pylint Python http://pylint.readthedocs.org/en/latest/
bandit Python https://github.com/openstack/bandit
eslint JavaScript http://eslint.org/
csslint CSS http://csslint.net/
stylelint CSS/SASS/SCSS http://stylelint.io/
sasslint SASS/SCSS https://github.com/sasstools/sass-lint
shellcheck bash/zsh https://github.com/koalaman/shellcheck
yamllint YAML https://github.com/adrienverge/yamllint
jsonlint JSON https://github.com/zaach/jsonlint
rstlint RestructuredText https://github.com/twolfson/restructuredtext-lint
hadolint Dockerfile https://github.com/hadolint/hadolint

指定 Python 代码检查工具使用的 Python 版本

对于 Python 相关的代码检查工具，支持指定其使用的 Python 版本（默认使用 Python 3）：

linter: {name: 'pylint', python_version: 2}

Tips

  • 在 Pull Request 的标题/描述中包含 lint skip 禁用代码检查功能

自动化部署

支持的部署方式

  1. 命令行脚本 script
  2. Pypi/PypiCloud

项目接入

请先参考 构建和测试 文档接入项目，对于部署，可配置的项有：

选项名 类型 说明
deploy.provider string 部署服务提供方，如 script, pypi 等
deploy.branch string/list 开启部署的分支，默认为空
deploy.tag boolean 是否开启 tag 部署
after_deploy string/list 部署成功后运行的命令

script

deploy:
  tag: true
  provider: script
  script:
    - echo 'Deploying'
    - etc.

Pypi

可配置的项有：

选项名 类型 说明
username string 用户名
password string 密码
repository string Pypi 仓库，默认为官方仓库

对于密码等敏感信息，可以使用 secure token 配置，可以使用 badwolf encrypt 命令生成，如：

badwolf encrypt my_secret_key

然后将生成的 token 以 secure: <token> 的形式插入 .badwolf.yml 中，如：

after_success: python setup.py sdist bdist_wheel > /dev/null
deploy:
  tag: true
  provider: pypi
  username: pypi
  password:
    secure: my_secure_token
  repository: https://pypi.example.com

配置多个 provider

after_success: python setup.py sdist bdist_wheel > /dev/null
deploy:
  - tag: true
    provider: script
    script:
      - echo 'Deploying'
      - etc.
  - branch: master
    provider: pypi
    username: pypi
    password:
      secure: my_secure_token

以上多个 deploy provider 将有序执行。

Indices and tables