Travis CI API のGolang Clientを公開しました #Go

今年の9月頃からしこしこ作っていた Golang向けのTravisCI Client Library, shuheiktgw/go-travis が良い感じになってきたため使い方などを紹介します. READMEは英語で記載しているため,この投稿はREADMEの日本語版という立ち位置です.

何故作ったのか?

GolangからTravis CIのAPIのビルドをキックしたくてクライアントを探していて, Ableton/go-travis というライブラリーを見つけたのですが,以下の問題がありました.

2017年を最後にメンテナンスされている気配がない
Travis CI APIの最新バージョンであるV3をサポートしていない
カバーされているエンドポイントの数が少ない

というわけでこれらの問題を解決したくてAbleton/go-travisをフォークして書いたのが, shuheiktgw/go-travisです. あとは日頃Travis CIをタダで使いまくっているため,何らかの形で恩返ししたいという気持ちも0.1%ぐらいありました.

何ができるのか?

Travis CI APIのV3をサポートしています
Travis CI APIのV3のエンドポイントをすべてカバーしている(はず)です

どうやって使うのか?

インストール

$ go get github.com/shuheiktgw/go-travis

使い方

import "github.com/shuheiktgw/go-travis"

client := travis.NewClient(travis.ApiOrgUrl, "TravisApiToken")

// 認証されたユーザーのbuild一覧を取得する
builds, res, err := client.Builds.Find(context.Background(), nil)

基本的な使い方は上の通り. 何点か使い方のポイントだけ解説します.

`travis.NewClient`のURL

現在Travis CIのプロジェクトには以下二つのURLのどちらかに所属しています.

https://api.travis-ci.org/
https://api.travis-ci.com/

もともとは org のほうがオープンソーズプロジェクト向け, com の方が有料プロジェクト向けのURLだったのですが, 現在 org の方を com の方に統合するプロセスの真っ最中のため, オープンソースのプロジェクトであっても https://api.travis-ci.com/ の方に入っている可能性があります.

shuheiktgw/go-travis ではそれぞれのURL向けに travis.ApiOrgUrl, travis.ApiComUrl という定数を提供しているため,ご自身のプロジェクトが所属している方のURLを選択して travis.NewClient の第一引数へ渡してください.

org から com へのマイグレーションに関しては,Travis CIの公式ドキュメントも合わせてご確認ください.

Open Source on travis-ci.com

認証方法

shuheiktgw/go-travis には以下二つの認証方法が用意されています.

Travis CI APIのTokenを用いた認証
GitHub personal access tokenを用いた認証

Travis CIのAPI Tokenを用いた認証

client := travis.NewClient(travis.ApiOrgUrl, "TravisApiToken")

// ユーザーは認証されているため, Jobs.Cancelは成功する
_, err := client.Jobs.Cancel(context.Background(), 12345)

最もシンプルなのは, travis.NewClient の第二引数へ直接Travis CIのAPI Tokenを渡す方法です. Travis CI APIのTokenはTravis CIのプロファイルページか Travis CIのコマンドラインツールと使って取得することができます.

詳細な情報はTravis CIのドキュメントをご参照ください.

Triggering builds with API V3

GitHub personal access tokenを用いた認証

client := travis.NewClient(travis.ApiOrgUrl, "")

err := client.Authentication.UsingGithubToken("GitHubToken")

// ユーザーは認証されているため, Jobs.Cancelは成功する
_, err := client.Jobs.Cancel(context.Background(), 12345)

GitHubのトークンを用いてTravis CIの認証を行うことも可能です. GitHubのpersonal access tokenの取得方法に関してはGitHubのヘルプページをご参照ください.

Creating a personal access token for the command line

認証せずにgo-travisを使う

client := travis.NewClient(travis.ApiOrgUrl, "")

// Builds.FindByRepoSlug は認証なしで叩くことができる
builds, resp, err := client.Builds.FindByRepoSlug(context.Background(), "shuheiktgw/go-travis", nil)

// Jobs.Cancel は認証なしで叩くことはできない
_, err := client.Jobs.Cancel(context.Background(), 12345)

いくつかのエンドポイントは認証せずに使うことができます.

Travis CI API のGolang Clientを公開しました