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

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

## 何故作ったのか?
GolangからTravis CIのAPIのビルドをキックしたくてクライアントを探していて, [Ableton/go-travis](https://github.com/Ableton/go-travis) というライブラリーを見つけたのですが,以下の問題がありました.

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

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

## 何ができるのか?

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

## どうやって使うのか?

### インストール

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

### 使い方

```golang
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](https://docs.travis-ci.com/user/open-source-on-travis-ci-com/)

#### 認証方法

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

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

**Travis CIのAPI Tokenを用いた認証**

```golang
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の[プロファイルページ](https://travis-ci.com/profile)か Travis CIの[コマンドラインツール](https://github.com/travis-ci/travis.rb#readme)と使って取得することができます. 

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

- [Triggering builds with API V3](https://docs.travis-ci.com/user/triggering-builds/)

**GitHub personal access tokenを用いた認証**

```golang
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](https://help.github.com/articles/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)
```


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