README.md
1go-travis
2====
3
4[](https://github.com/shuheiktgw/go-travis/releases/latest)
5[](https://travis-ci.org/shuheiktgw/go-travis)
6[](https://opensource.org/licenses/BSD-3-Clause)
7[](https://godoc.org/github.com/shuheiktgw/go-travis)
8
9go-travis is a Go client library to interact with the [Travis CI API V3](https://developer.travis-ci.com/).
10
11## Installation
12
13```bash
14$ go get github.com/shuheiktgw/go-travis
15```
16
17## Usage
18
19Interaction with the Travis CI API is done through a `Client` instance.
20
21```go
22import "github.com/shuheiktgw/go-travis"
23
24client := travis.NewClient(travis.ApiOrgUrl, "TravisApiToken")
25
26// List all the builds which belongs to the current user
27builds, res, err := client.Builds.Find(context.Background(), nil)
28```
29
30### URL
31Currently, there are two possible options for Travis CI API URL.
32
33- `https://api.travis-ci.org/`
34- `https://api.travis-ci.com/`
35
36You should know which URL your project belongs to, and hand it in to `NewClient` method as an argument. We provide two constants, `ApiOrgUrl` for `https://api.travis-ci.org/` and `ApiComUrl` for `https://api.travis-ci.com/`, so please choose one of them.
37
38Travis CI is migrating projects in `https://api.travis-ci.org/` to `https://api.travis-ci.com/`, and please visit [their documentation page](https://docs.travis-ci.com/user/open-source-on-travis-ci-com#existing-private-repositories-on-travis-cicom) for more information on the migration.
39
40
41### Authentication
42
43There two ways to authenticator your Travis CI client.
44
45- Authentication with Travis API token
46- Authentication with GitHub personal access token
47
48##### Authentication with Travis API token
49
50```go
51client := travis.NewClient(travis.ApiOrgUrl, "TravisApiToken")
52
53// Jobs.Cancel will success
54_, err := client.Jobs.Cancel(context.Background(), 12345)
55```
56
57You can issue Travis API token and hand it in to `NewClient` method directly. You can issue your token by visiting your Travis CI [Profile page](https://travis-ci.com/profile) or using Travis CI [command line tool](https://github.com/travis-ci/travis.rb#readme).
58
59For more information on how to issue Travis CI API token, please visit [their documentation](https://docs.travis-ci.com/user/triggering-builds/).
60
61
62
63##### Authentication with GitHub personal access token
64Authentication with a Github personal access token will require some extra steps. [This GitHub help page](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) guides you thorough how to create one.
65
66```go
67client := travis.NewClient(travis.ApiOrgUrl, "")
68
69err := client.Authentication.UsingGithubToken("GitHubToken")
70
71// Jobs.Cancel will success
72_, err := client.Jobs.Cancel(context.Background(), 12345)
73```
74
75#### Unauthenticated client
76
77It is possible to interact with the API without authentication. However some resources are not accessible.
78
79```go
80client := travis.NewClient(travis.ApiOrgUrl, "")
81
82// Builds.FindByRepoSlug is available without authentication
83builds, resp, err := client.Builds.FindByRepoSlug(context.Background(), "shuheiktgw/go-travis", nil)
84
85// Jobs.Cancel is unavailable without authentication
86_, err := client.Jobs.Cancel(context.Background(), 12345)
87```
88
89## Supported / Unsupported features
90
91### Supported features
92- ~~Covers all the [Travis CI API v3 public endpoints](https://developer.travis-ci.com/)! :tada:~~
93- As of April 14. 2019, there are several changes on the API we have not yet handled yet. Check https://github.com/shuheiktgw/go-travis/issues/19 and help us fix the problems! :+1:
94
95### Unsupported features
96- [Eager loading](https://developer.travis-ci.com/eager-loading#eager%20loading) is not supported so far
97
98## Contribution
99Contributions are of course always welcome!
100
1011. Fork shuheiktgw/go-travis (https://github.com/shuheiktgw/go-travis/fork)
1022. Run `dep ensure` to install dependencies
1033. Create a feature branch
1044. Commit your changes
1055. Run test using `go test`
1066. Create a Pull Request
107
108See [`CONTRIBUTING.md`](https://github.com/shuheiktgw/go-travis/blob/master/CONTRIBUTING.md) for details.
109
110## Acknowledgements
111
112This library is originally forked from [Ableton/go-travis](https://github.com/Ableton/go-travis) and most of the credits of this library is attributed to them.
113
){kind=link}
){kind=link}
){kind=link}
){kind=link}