FilesExpand file tree

 NestedTeamsPreview

/

doc.go

Copy path

Blame

More file actions

Blame

More file actions

Latest commit

 

History

History

History

191 lines (141 loc) · 6.45 KB

 NestedTeamsPreview

/

doc.go

Copy path

Top

File metadata and controls

• Code
• Blame

191 lines (141 loc) · 6.45 KB

Raw

Copy raw file

Download raw file

Open symbols panel

Edit and raw actions

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

65

66

67

68

69

70

71

72

73

74

75

76

77

78

79

80

81

82

83

84

85

86

87

88

89

90

91

92

93

94

95

96

97

98

99

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

// Copyright 2013 The go-github AUTHORS. All rights reserved.

//

// Use of this source code is governed by a BSD-style

// license that can be found in the LICENSE file.

/*

Package github provides a client for using the GitHub API.

Usage:

import "github.com/google/go-github/github"

Construct a new GitHub client, then use the various services on the client to

access different parts of the GitHub API. For example:

client := github.NewClient(nil)

// list all organizations for user "willnorris"

orgs, _, err := client.Organizations.List(ctx, "willnorris", nil)

Some API methods have optional parameters that can be passed. For example:

client := github.NewClient(nil)

// list public repositories for org "github"

opt := &github.RepositoryListByOrgOptions{Type: "public"}

repos, _, err := client.Repositories.ListByOrg(ctx, "github", opt)

The services of a client divide the API into logical chunks and correspond to

the structure of the GitHub API documentation at

https://developer.github.com/v3/.

Authentication

The go-github library does not directly handle authentication. Instead, when

creating a new client, pass an http.Client that can handle authentication for

you. The easiest and recommended way to do this is using the golang.org/x/oauth2

library, but you can always use any other library that provides an http.Client.

If you have an OAuth2 access token (for example, a personal API token), you can

use it with the oauth2 library using:

import "golang.org/x/oauth2"

func main() {

ctx := context.Background()

ts := oauth2.StaticTokenSource(

&oauth2.Token{AccessToken: "... your access token ..."},

)

tc := oauth2.NewClient(ctx, ts)

client := github.NewClient(tc)

// list all repositories for the authenticated user

repos, _, err := client.Repositories.List(ctx, "", nil)

}

Note that when using an authenticated Client, all calls made by the client will

include the specified OAuth token. Therefore, authenticated clients should

almost never be shared between different users.

See the oauth2 docs for complete instructions on using that library.

For API methods that require HTTP Basic Authentication, use the

BasicAuthTransport.

GitHub Apps authentication can be provided by the

https://github.com/bradleyfalzon/ghinstallation package.

import "github.com/bradleyfalzon/ghinstallation"

func main() {

// Wrap the shared transport for use with the integration ID 1 authenticating with installation ID 99.

itr, err := ghinstallation.NewKeyFromFile(http.DefaultTransport, 1, 99, "2016-10-19.private-key.pem")

if err != nil {

// Handle error.

}

// Use installation transport with client

client := github.NewClient(&http.Client{Transport: itr})

// Use client...

}

Rate Limiting

GitHub imposes a rate limit on all API clients. Unauthenticated clients are

limited to 60 requests per hour, while authenticated clients can make up to

5,000 requests per hour. The Search API has a custom rate limit. Unauthenticated

clients are limited to 10 requests per minute, while authenticated clients

can make up to 30 requests per minute. To receive the higher rate limit when

making calls that are not issued on behalf of a user,

use UnauthenticatedRateLimitedTransport.

The returned Response.Rate value contains the rate limit information

from the most recent API call. If a recent enough response isn't

available, you can use RateLimits to fetch the most up-to-date rate

limit data for the client.

To detect an API rate limit error, you can check if its type is *github.RateLimitError:

repos, _, err := client.Repositories.List(ctx, "", nil)

if _, ok := err.(*github.RateLimitError); ok {

log.Println("hit rate limit")

}

Learn more about GitHub rate limiting at

https://developer.github.com/v3/#rate-limiting.

Accepted Status

Some endpoints may return a 202 Accepted status code, meaning that the

information required is not yet ready and was scheduled to be gathered on

the GitHub side. Methods known to behave like this are documented specifying

this behavior.

To detect this condition of error, you can check if its type is

*github.AcceptedError:

stats, _, err := client.Repositories.ListContributorsStats(ctx, org, repo)

if _, ok := err.(*github.AcceptedError); ok {

log.Println("scheduled on GitHub side")

}

Conditional Requests

The GitHub API has good support for conditional requests which will help

prevent you from burning through your rate limit, as well as help speed up your

application. go-github does not handle conditional requests directly, but is

instead designed to work with a caching http.Transport. We recommend using

https://github.com/gregjones/httpcache for that.

Learn more about GitHub conditional requests at

https://developer.github.com/v3/#conditional-requests.

Creating and Updating Resources

All structs for GitHub resources use pointer values for all non-repeated fields.

This allows distinguishing between unset fields and those set to a zero-value.

Helper functions have been provided to easily create these pointers for string,

bool, and int values. For example:

// create a new private repository named "foo"

repo := &github.Repository{

Name: github.String("foo"),

Private: github.Bool(true),

}

client.Repositories.Create(ctx, "", repo)

Users who have worked with protocol buffers should find this pattern familiar.

Pagination

All requests for resource collections (repos, pull requests, issues, etc.)

support pagination. Pagination options are described in the

github.ListOptions struct and passed to the list methods directly or as an

embedded type of a more specific list options struct (for example

github.PullRequestListOptions). Pages information is available via the

github.Response struct.

client := github.NewClient(nil)

opt := &github.RepositoryListByOrgOptions{

ListOptions: github.ListOptions{PerPage: 10},

}

// get all pages of results

var allRepos []*github.Repository

for {

repos, resp, err := client.Repositories.ListByOrg(ctx, "github", opt)

if err != nil {

return err

}

allRepos = append(allRepos, repos...)

if resp.NextPage == 0 {

break

}

opt.Page = resp.NextPage

}

Google App Engine

Go on App Engine Classic (which as of this writing uses Go 1.6) can not use

the "context" import and still relies on "golang.org/x/net/context".

As a result, if you wish to continue to use "go-github" on App Engine Classic,

you will need to rewrite all the "context" imports using the following command:

gofmt -w -r '"context" -> "golang.org/x/net/context"' *.go

See "with_appengine.go" for more details.

*/

package github