github.com/google/go-github/v33@v33.0.0/github/apps.go (about) 1 // Copyright 2016 The go-github AUTHORS. All rights reserved. 2 // 3 // Use of this source code is governed by a BSD-style 4 // license that can be found in the LICENSE file. 5 6 package github 7 8 import ( 9 "context" 10 "fmt" 11 "time" 12 ) 13 14 // AppsService provides access to the installation related functions 15 // in the GitHub API. 16 // 17 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/ 18 type AppsService service 19 20 // App represents a GitHub App. 21 type App struct { 22 ID *int64 `json:"id,omitempty"` 23 Slug *string `json:"slug,omitempty"` 24 NodeID *string `json:"node_id,omitempty"` 25 Owner *User `json:"owner,omitempty"` 26 Name *string `json:"name,omitempty"` 27 Description *string `json:"description,omitempty"` 28 ExternalURL *string `json:"external_url,omitempty"` 29 HTMLURL *string `json:"html_url,omitempty"` 30 CreatedAt *Timestamp `json:"created_at,omitempty"` 31 UpdatedAt *Timestamp `json:"updated_at,omitempty"` 32 Permissions *InstallationPermissions `json:"permissions,omitempty"` 33 Events []string `json:"events,omitempty"` 34 } 35 36 // InstallationToken represents an installation token. 37 type InstallationToken struct { 38 Token *string `json:"token,omitempty"` 39 ExpiresAt *time.Time `json:"expires_at,omitempty"` 40 Permissions *InstallationPermissions `json:"permissions,omitempty"` 41 Repositories []*Repository `json:"repositories,omitempty"` 42 } 43 44 // InstallationTokenOptions allow restricting a token's access to specific repositories. 45 type InstallationTokenOptions struct { 46 // The IDs of the repositories that the installation token can access. 47 // Providing repository IDs restricts the access of an installation token to specific repositories. 48 RepositoryIDs []int64 `json:"repository_ids,omitempty"` 49 50 // The permissions granted to the access token. 51 // The permissions object includes the permission names and their access type. 52 Permissions *InstallationPermissions `json:"permissions,omitempty"` 53 } 54 55 // InstallationPermissions lists the repository and organization permissions for an installation. 56 // 57 // Permission names taken from: 58 // https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/permissions/ 59 // https://developer.github.com/enterprise/v3/apps/permissions/ 60 type InstallationPermissions struct { 61 Administration *string `json:"administration,omitempty"` 62 Blocking *string `json:"blocking,omitempty"` 63 Checks *string `json:"checks,omitempty"` 64 Contents *string `json:"contents,omitempty"` 65 ContentReferences *string `json:"content_references,omitempty"` 66 Deployments *string `json:"deployments,omitempty"` 67 Emails *string `json:"emails,omitempty"` 68 Followers *string `json:"followers,omitempty"` 69 Issues *string `json:"issues,omitempty"` 70 Metadata *string `json:"metadata,omitempty"` 71 Members *string `json:"members,omitempty"` 72 OrganizationAdministration *string `json:"organization_administration,omitempty"` 73 OrganizationHooks *string `json:"organization_hooks,omitempty"` 74 OrganizationPlan *string `json:"organization_plan,omitempty"` 75 OrganizationPreReceiveHooks *string `json:"organization_pre_receive_hooks,omitempty"` 76 OrganizationProjects *string `json:"organization_projects,omitempty"` 77 OrganizationUserBlocking *string `json:"organization_user_blocking,omitempty"` 78 Packages *string `json:"packages,omitempty"` 79 Pages *string `json:"pages,omitempty"` 80 PullRequests *string `json:"pull_requests,omitempty"` 81 RepositoryHooks *string `json:"repository_hooks,omitempty"` 82 RepositoryProjects *string `json:"repository_projects,omitempty"` 83 RepositoryPreReceiveHooks *string `json:"repository_pre_receive_hooks,omitempty"` 84 SingleFile *string `json:"single_file,omitempty"` 85 Statuses *string `json:"statuses,omitempty"` 86 TeamDiscussions *string `json:"team_discussions,omitempty"` 87 VulnerabilityAlerts *string `json:"vulnerability_alerts,omitempty"` 88 } 89 90 // Installation represents a GitHub Apps installation. 91 type Installation struct { 92 ID *int64 `json:"id,omitempty"` 93 NodeID *string `json:"node_id,omitempty"` 94 AppID *int64 `json:"app_id,omitempty"` 95 TargetID *int64 `json:"target_id,omitempty"` 96 Account *User `json:"account,omitempty"` 97 AccessTokensURL *string `json:"access_tokens_url,omitempty"` 98 RepositoriesURL *string `json:"repositories_url,omitempty"` 99 HTMLURL *string `json:"html_url,omitempty"` 100 TargetType *string `json:"target_type,omitempty"` 101 SingleFileName *string `json:"single_file_name,omitempty"` 102 RepositorySelection *string `json:"repository_selection,omitempty"` 103 Events []string `json:"events,omitempty"` 104 Permissions *InstallationPermissions `json:"permissions,omitempty"` 105 CreatedAt *Timestamp `json:"created_at,omitempty"` 106 UpdatedAt *Timestamp `json:"updated_at,omitempty"` 107 } 108 109 // Attachment represents a GitHub Apps attachment. 110 type Attachment struct { 111 ID *int64 `json:"id,omitempty"` 112 Title *string `json:"title,omitempty"` 113 Body *string `json:"body,omitempty"` 114 } 115 116 // ContentReference represents a reference to a URL in an issue or pull request. 117 type ContentReference struct { 118 ID *int64 `json:"id,omitempty"` 119 NodeID *string `json:"node_id,omitempty"` 120 Reference *string `json:"reference,omitempty"` 121 } 122 123 func (i Installation) String() string { 124 return Stringify(i) 125 } 126 127 // Get a single GitHub App. Passing the empty string will get 128 // the authenticated GitHub App. 129 // 130 // Note: appSlug is just the URL-friendly name of your GitHub App. 131 // You can find this on the settings page for your GitHub App 132 // (e.g., https://github.com/settings/apps/:app_slug). 133 // 134 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#get-the-authenticated-app 135 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#get-an-app 136 func (s *AppsService) Get(ctx context.Context, appSlug string) (*App, *Response, error) { 137 var u string 138 if appSlug != "" { 139 u = fmt.Sprintf("apps/%v", appSlug) 140 } else { 141 u = "app" 142 } 143 144 req, err := s.client.NewRequest("GET", u, nil) 145 if err != nil { 146 return nil, nil, err 147 } 148 149 app := new(App) 150 resp, err := s.client.Do(ctx, req, app) 151 if err != nil { 152 return nil, resp, err 153 } 154 155 return app, resp, nil 156 } 157 158 // ListInstallations lists the installations that the current GitHub App has. 159 // 160 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#list-installations-for-the-authenticated-app 161 func (s *AppsService) ListInstallations(ctx context.Context, opts *ListOptions) ([]*Installation, *Response, error) { 162 u, err := addOptions("app/installations", opts) 163 if err != nil { 164 return nil, nil, err 165 } 166 167 req, err := s.client.NewRequest("GET", u, nil) 168 if err != nil { 169 return nil, nil, err 170 } 171 172 var i []*Installation 173 resp, err := s.client.Do(ctx, req, &i) 174 if err != nil { 175 return nil, resp, err 176 } 177 178 return i, resp, nil 179 } 180 181 // GetInstallation returns the specified installation. 182 // 183 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#get-an-installation-for-the-authenticated-app 184 func (s *AppsService) GetInstallation(ctx context.Context, id int64) (*Installation, *Response, error) { 185 return s.getInstallation(ctx, fmt.Sprintf("app/installations/%v", id)) 186 } 187 188 // ListUserInstallations lists installations that are accessible to the authenticated user. 189 // 190 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#list-app-installations-accessible-to-the-user-access-token 191 func (s *AppsService) ListUserInstallations(ctx context.Context, opts *ListOptions) ([]*Installation, *Response, error) { 192 u, err := addOptions("user/installations", opts) 193 if err != nil { 194 return nil, nil, err 195 } 196 197 req, err := s.client.NewRequest("GET", u, nil) 198 if err != nil { 199 return nil, nil, err 200 } 201 202 var i struct { 203 Installations []*Installation `json:"installations"` 204 } 205 resp, err := s.client.Do(ctx, req, &i) 206 if err != nil { 207 return nil, resp, err 208 } 209 210 return i.Installations, resp, nil 211 } 212 213 // SuspendInstallation suspends the specified installation. 214 // 215 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#suspend-an-app-installation 216 func (s *AppsService) SuspendInstallation(ctx context.Context, id int64) (*Response, error) { 217 u := fmt.Sprintf("app/installations/%v/suspended", id) 218 219 req, err := s.client.NewRequest("PUT", u, nil) 220 if err != nil { 221 return nil, err 222 } 223 224 return s.client.Do(ctx, req, nil) 225 } 226 227 // UnsuspendInstallation unsuspends the specified installation. 228 // 229 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#unsuspend-an-app-installation 230 func (s *AppsService) UnsuspendInstallation(ctx context.Context, id int64) (*Response, error) { 231 u := fmt.Sprintf("app/installations/%v/suspended", id) 232 233 req, err := s.client.NewRequest("DELETE", u, nil) 234 if err != nil { 235 return nil, err 236 } 237 238 return s.client.Do(ctx, req, nil) 239 } 240 241 // DeleteInstallation deletes the specified installation. 242 // 243 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#delete-an-installation-for-the-authenticated-app 244 func (s *AppsService) DeleteInstallation(ctx context.Context, id int64) (*Response, error) { 245 u := fmt.Sprintf("app/installations/%v", id) 246 247 req, err := s.client.NewRequest("DELETE", u, nil) 248 if err != nil { 249 return nil, err 250 } 251 252 return s.client.Do(ctx, req, nil) 253 } 254 255 // CreateInstallationToken creates a new installation token. 256 // 257 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#create-an-installation-access-token-for-an-app 258 func (s *AppsService) CreateInstallationToken(ctx context.Context, id int64, opts *InstallationTokenOptions) (*InstallationToken, *Response, error) { 259 u := fmt.Sprintf("app/installations/%v/access_tokens", id) 260 261 req, err := s.client.NewRequest("POST", u, opts) 262 if err != nil { 263 return nil, nil, err 264 } 265 266 t := new(InstallationToken) 267 resp, err := s.client.Do(ctx, req, t) 268 if err != nil { 269 return nil, resp, err 270 } 271 272 return t, resp, nil 273 } 274 275 // CreateAttachment creates a new attachment on user comment containing a url. 276 // 277 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#create-a-content-attachment 278 func (s *AppsService) CreateAttachment(ctx context.Context, contentReferenceID int64, title, body string) (*Attachment, *Response, error) { 279 u := fmt.Sprintf("content_references/%v/attachments", contentReferenceID) 280 payload := &Attachment{Title: String(title), Body: String(body)} 281 req, err := s.client.NewRequest("POST", u, payload) 282 if err != nil { 283 return nil, nil, err 284 } 285 286 // TODO: remove custom Accept headers when APIs fully launch. 287 req.Header.Set("Accept", mediaTypeContentAttachmentsPreview) 288 289 m := &Attachment{} 290 resp, err := s.client.Do(ctx, req, m) 291 if err != nil { 292 return nil, resp, err 293 } 294 295 return m, resp, nil 296 } 297 298 // FindOrganizationInstallation finds the organization's installation information. 299 // 300 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#get-an-organization-installation-for-the-authenticated-app 301 func (s *AppsService) FindOrganizationInstallation(ctx context.Context, org string) (*Installation, *Response, error) { 302 return s.getInstallation(ctx, fmt.Sprintf("orgs/%v/installation", org)) 303 } 304 305 // FindRepositoryInstallation finds the repository's installation information. 306 // 307 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#get-a-repository-installation-for-the-authenticated-app 308 func (s *AppsService) FindRepositoryInstallation(ctx context.Context, owner, repo string) (*Installation, *Response, error) { 309 return s.getInstallation(ctx, fmt.Sprintf("repos/%v/%v/installation", owner, repo)) 310 } 311 312 // FindRepositoryInstallationByID finds the repository's installation information. 313 // 314 // Note: FindRepositoryInstallationByID uses the undocumented GitHub API endpoint /repositories/:id/installation. 315 func (s *AppsService) FindRepositoryInstallationByID(ctx context.Context, id int64) (*Installation, *Response, error) { 316 return s.getInstallation(ctx, fmt.Sprintf("repositories/%d/installation", id)) 317 } 318 319 // FindUserInstallation finds the user's installation information. 320 // 321 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#get-a-user-installation-for-the-authenticated-app 322 func (s *AppsService) FindUserInstallation(ctx context.Context, user string) (*Installation, *Response, error) { 323 return s.getInstallation(ctx, fmt.Sprintf("users/%v/installation", user)) 324 } 325 326 func (s *AppsService) getInstallation(ctx context.Context, url string) (*Installation, *Response, error) { 327 req, err := s.client.NewRequest("GET", url, nil) 328 if err != nil { 329 return nil, nil, err 330 } 331 332 i := new(Installation) 333 resp, err := s.client.Do(ctx, req, i) 334 if err != nil { 335 return nil, resp, err 336 } 337 338 return i, resp, nil 339 }