CircleCIのジョブをAPI経由で起動する方法
How to trigger CircleCI jobs through API
CircleCIはその名の通りCI（継続的インテグレーション）に関するサービスなので、GitHubと連携してジョブを起動することが多いかと思いますが、実は、CircleCIが提供するRESTful APIを呼び出して起動することもできます。
最近、ちょっとしたツールはGAEに載せることが多いのですが、「ツールを利用してファイルを出力」して、「リポジトリの内容と差分がある場合はリポジトリにPush」するといったツールを作成しようとしたときに、GAEだと少し面倒。そこで目を付けたのがCircleCIのジョブでした。ということで、今回はCircleCIのジョブをAPI経由で起動する方法を紹介します。
.circleci/config.ymlの書き方
作成したconfig.ymlのサンプルを下に貼り付けています。test_jobジョブをAPI経由で起動すれば、ソースとGoのツールをダウンロードして実行し、差分があればリポジトリにPushします。
個人的に一番重要なことは、CircleCI 2.1ではAPIによるジョブの起動は、現在サポートされていないため、version: 2を指定しなければいけないことです。よって、executorsや commandsといった2.1から追加された機能は使用できません。
version: 2jobs:
test_job:
docker:
- image: circleci/golang:1.11
working_directory: /go/src/github.com/xxx/xxxxx
steps:
- checkout
- run:
name: Install tool
command: |
go get github.com/yyy/yyyyy
- run:
name: Execute tool
command: |
# execute tool
# move files to the correct directory
- run:
name: Check diff, commit and push
command: |
git diff --unified=0 > ./diff.txt
if [ -s './diff.txt' ]; then
rm ./diff.txt
git config user.name "github-user-name"
git config user.email "github-user@e.mail"
git checkout -b new-branch
git add .
git commit -m "commit comment"
git push origin new-branch
else
echo 'There are no difference.'
fi
ちなみにconfig.ymlには通常、buildジョブが必要となりますが、今回は使用しないため作成していません。GitHub上でCircleCIへのWebhookが残っていると、PushなどのタイミングでCircleCIが起動され、毎回buildジョブがないことによるエラーが発生するので、不要であればWebhookを削除してしまいましょう。
また、本筋から外れるので詳細は記載しませんが、CircleCIとGitHubを連携する際に通常使用されるDeploy Keyは、読み取り権限しか持っていないためPush操作はできません。こちらの記事などにも記載していますが、適切なキーを設定してあげてください。
API経由で起動する
基本的にはRESTfulなAPIを呼び出すだけなのですが、その前に認証用のトークンが必要となります。公式ドキュメントではPersonal API tokenを使用していますが、今回はProject API tokenを使用します。ProjectのSetting画面から、API Permissionsを選択してCreate Tokenボタンからトークンを作成してください。ScopeはAllでなければ、権限が足りないた起動ができません。
トークンを作成できたら、後はAPIを呼び出すだけです。cURLだと下記のようになります。
curl -d build_parameters[CIRCLE_JOB]=test_job \
https://circleci.com/api/v1.1/project/github/<org>/<repo>/tree/<branch>?circle-token=<token>なお、masterブランチのジョブやbuildジョブを起動する場合は、それぞれブランチ名、ジョブ名の指定が不要なため、下記だけで呼び出すことができます。
curl https://circleci.com/api/v1.1/project/github/<org>/<repo>?circle-token=<token>実行すると何やら大量なレスポンスが返ってきますが、それは起動が成功した証です。失敗した場合はシンプルなエラーメッセージが返ってきます。後はCircleCIのページでジョブの進行状況を確認しましょう。
APIで起動ができるというのはとても便利ですね。SlackのSlash Commandなんかとも簡単に連携ができるようになるので、またひとつ自動化に弾みがつきそうです。
