github.com/google/go-github/v65@v65.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 ) 12 13 // AppsService provides access to the installation related functions 14 // in the GitHub API. 15 // 16 // GitHub API docs: https://docs.github.com/rest/apps/ 17 type AppsService service 18 19 // App represents a GitHub App. 20 type App struct { 21 ID *int64 `json:"id,omitempty"` 22 Slug *string `json:"slug,omitempty"` 23 NodeID *string `json:"node_id,omitempty"` 24 Owner *User `json:"owner,omitempty"` 25 Name *string `json:"name,omitempty"` 26 Description *string `json:"description,omitempty"` 27 ExternalURL *string `json:"external_url,omitempty"` 28 HTMLURL *string `json:"html_url,omitempty"` 29 CreatedAt *Timestamp `json:"created_at,omitempty"` 30 UpdatedAt *Timestamp `json:"updated_at,omitempty"` 31 Permissions *InstallationPermissions `json:"permissions,omitempty"` 32 Events []string `json:"events,omitempty"` 33 InstallationsCount *int `json:"installations_count,omitempty"` 34 } 35 36 // InstallationToken represents an installation token. 37 type InstallationToken struct { 38 Token *string `json:"token,omitempty"` 39 ExpiresAt *Timestamp `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 names of the repositories that the installation token can access. 51 // Providing repository names restricts the access of an installation token to specific repositories. 52 Repositories []string `json:"repositories,omitempty"` 53 54 // The permissions granted to the access token. 55 // The permissions object includes the permission names and their access type. 56 Permissions *InstallationPermissions `json:"permissions,omitempty"` 57 } 58 59 type InstallationTokenListRepoOptions struct { 60 // The IDs of the repositories that the installation token can access. 61 // Providing repository IDs restricts the access of an installation token to specific repositories. 62 RepositoryIDs []int64 `json:"repository_ids"` 63 64 // The names of the repositories that the installation token can access. 65 // Providing repository names restricts the access of an installation token to specific repositories. 66 Repositories []string `json:"repositories,omitempty"` 67 68 // The permissions granted to the access token. 69 // The permissions object includes the permission names and their access type. 70 Permissions *InstallationPermissions `json:"permissions,omitempty"` 71 } 72 73 // InstallationPermissions lists the repository and organization permissions for an installation. 74 // 75 // Permission names taken from: 76 // 77 // https://docs.github.com/enterprise-server@3.0/rest/apps#create-an-installation-access-token-for-an-app 78 // https://docs.github.com/rest/apps#create-an-installation-access-token-for-an-app 79 type InstallationPermissions struct { 80 Actions *string `json:"actions,omitempty"` 81 ActionsVariables *string `json:"actions_variables,omitempty"` 82 Administration *string `json:"administration,omitempty"` 83 Blocking *string `json:"blocking,omitempty"` 84 Checks *string `json:"checks,omitempty"` 85 Contents *string `json:"contents,omitempty"` 86 ContentReferences *string `json:"content_references,omitempty"` 87 Deployments *string `json:"deployments,omitempty"` 88 Emails *string `json:"emails,omitempty"` 89 Environments *string `json:"environments,omitempty"` 90 Followers *string `json:"followers,omitempty"` 91 Issues *string `json:"issues,omitempty"` 92 Metadata *string `json:"metadata,omitempty"` 93 Members *string `json:"members,omitempty"` 94 OrganizationAdministration *string `json:"organization_administration,omitempty"` 95 OrganizationCustomProperties *string `json:"organization_custom_properties,omitempty"` 96 OrganizationCustomRoles *string `json:"organization_custom_roles,omitempty"` 97 OrganizationCustomOrgRoles *string `json:"organization_custom_org_roles,omitempty"` 98 OrganizationHooks *string `json:"organization_hooks,omitempty"` 99 OrganizationPackages *string `json:"organization_packages,omitempty"` 100 OrganizationPersonalAccessTokens *string `json:"organization_personal_access_tokens,omitempty"` 101 OrganizationPersonalAccessTokenRequests *string `json:"organization_personal_access_token_requests,omitempty"` 102 OrganizationPlan *string `json:"organization_plan,omitempty"` 103 OrganizationPreReceiveHooks *string `json:"organization_pre_receive_hooks,omitempty"` 104 OrganizationProjects *string `json:"organization_projects,omitempty"` 105 OrganizationSecrets *string `json:"organization_secrets,omitempty"` 106 OrganizationSelfHostedRunners *string `json:"organization_self_hosted_runners,omitempty"` 107 OrganizationUserBlocking *string `json:"organization_user_blocking,omitempty"` 108 Packages *string `json:"packages,omitempty"` 109 Pages *string `json:"pages,omitempty"` 110 PullRequests *string `json:"pull_requests,omitempty"` 111 RepositoryHooks *string `json:"repository_hooks,omitempty"` 112 RepositoryProjects *string `json:"repository_projects,omitempty"` 113 RepositoryPreReceiveHooks *string `json:"repository_pre_receive_hooks,omitempty"` 114 Secrets *string `json:"secrets,omitempty"` 115 SecretScanningAlerts *string `json:"secret_scanning_alerts,omitempty"` 116 SecurityEvents *string `json:"security_events,omitempty"` 117 SingleFile *string `json:"single_file,omitempty"` 118 Statuses *string `json:"statuses,omitempty"` 119 TeamDiscussions *string `json:"team_discussions,omitempty"` 120 VulnerabilityAlerts *string `json:"vulnerability_alerts,omitempty"` 121 Workflows *string `json:"workflows,omitempty"` 122 } 123 124 // InstallationRequest represents a pending GitHub App installation request. 125 type InstallationRequest struct { 126 ID *int64 `json:"id,omitempty"` 127 NodeID *string `json:"node_id,omitempty"` 128 Account *User `json:"account,omitempty"` 129 Requester *User `json:"requester,omitempty"` 130 CreatedAt *Timestamp `json:"created_at,omitempty"` 131 } 132 133 // Installation represents a GitHub Apps installation. 134 type Installation struct { 135 ID *int64 `json:"id,omitempty"` 136 NodeID *string `json:"node_id,omitempty"` 137 AppID *int64 `json:"app_id,omitempty"` 138 AppSlug *string `json:"app_slug,omitempty"` 139 TargetID *int64 `json:"target_id,omitempty"` 140 Account *User `json:"account,omitempty"` 141 AccessTokensURL *string `json:"access_tokens_url,omitempty"` 142 RepositoriesURL *string `json:"repositories_url,omitempty"` 143 HTMLURL *string `json:"html_url,omitempty"` 144 TargetType *string `json:"target_type,omitempty"` 145 SingleFileName *string `json:"single_file_name,omitempty"` 146 RepositorySelection *string `json:"repository_selection,omitempty"` 147 Events []string `json:"events,omitempty"` 148 SingleFilePaths []string `json:"single_file_paths,omitempty"` 149 Permissions *InstallationPermissions `json:"permissions,omitempty"` 150 CreatedAt *Timestamp `json:"created_at,omitempty"` 151 UpdatedAt *Timestamp `json:"updated_at,omitempty"` 152 HasMultipleSingleFiles *bool `json:"has_multiple_single_files,omitempty"` 153 SuspendedBy *User `json:"suspended_by,omitempty"` 154 SuspendedAt *Timestamp `json:"suspended_at,omitempty"` 155 } 156 157 // Attachment represents a GitHub Apps attachment. 158 type Attachment struct { 159 ID *int64 `json:"id,omitempty"` 160 Title *string `json:"title,omitempty"` 161 Body *string `json:"body,omitempty"` 162 } 163 164 // ContentReference represents a reference to a URL in an issue or pull request. 165 type ContentReference struct { 166 ID *int64 `json:"id,omitempty"` 167 NodeID *string `json:"node_id,omitempty"` 168 Reference *string `json:"reference,omitempty"` 169 } 170 171 func (i Installation) String() string { 172 return Stringify(i) 173 } 174 175 // Get a single GitHub App. Passing the empty string will get 176 // the authenticated GitHub App. 177 // 178 // Note: appSlug is just the URL-friendly name of your GitHub App. 179 // You can find this on the settings page for your GitHub App 180 // (e.g., https://github.com/settings/apps/:app_slug). 181 // 182 // GitHub API docs: https://docs.github.com/rest/apps/apps#get-an-app 183 // GitHub API docs: https://docs.github.com/rest/apps/apps#get-the-authenticated-app 184 // 185 //meta:operation GET /app 186 //meta:operation GET /apps/{app_slug} 187 func (s *AppsService) Get(ctx context.Context, appSlug string) (*App, *Response, error) { 188 var u string 189 if appSlug != "" { 190 u = fmt.Sprintf("apps/%v", appSlug) 191 } else { 192 u = "app" 193 } 194 195 req, err := s.client.NewRequest("GET", u, nil) 196 if err != nil { 197 return nil, nil, err 198 } 199 200 app := new(App) 201 resp, err := s.client.Do(ctx, req, app) 202 if err != nil { 203 return nil, resp, err 204 } 205 206 return app, resp, nil 207 } 208 209 // ListInstallationRequests lists the pending installation requests that the current GitHub App has. 210 // 211 // GitHub API docs: https://docs.github.com/rest/apps/apps#list-installation-requests-for-the-authenticated-app 212 // 213 //meta:operation GET /app/installation-requests 214 func (s *AppsService) ListInstallationRequests(ctx context.Context, opts *ListOptions) ([]*InstallationRequest, *Response, error) { 215 u, err := addOptions("app/installation-requests", opts) 216 if err != nil { 217 return nil, nil, err 218 } 219 220 req, err := s.client.NewRequest("GET", u, nil) 221 if err != nil { 222 return nil, nil, err 223 } 224 225 var i []*InstallationRequest 226 resp, err := s.client.Do(ctx, req, &i) 227 if err != nil { 228 return nil, resp, err 229 } 230 231 return i, resp, nil 232 } 233 234 // ListInstallations lists the installations that the current GitHub App has. 235 // 236 // GitHub API docs: https://docs.github.com/rest/apps/apps#list-installations-for-the-authenticated-app 237 // 238 //meta:operation GET /app/installations 239 func (s *AppsService) ListInstallations(ctx context.Context, opts *ListOptions) ([]*Installation, *Response, error) { 240 u, err := addOptions("app/installations", opts) 241 if err != nil { 242 return nil, nil, err 243 } 244 245 req, err := s.client.NewRequest("GET", u, nil) 246 if err != nil { 247 return nil, nil, err 248 } 249 250 var i []*Installation 251 resp, err := s.client.Do(ctx, req, &i) 252 if err != nil { 253 return nil, resp, err 254 } 255 256 return i, resp, nil 257 } 258 259 // GetInstallation returns the specified installation. 260 // 261 // GitHub API docs: https://docs.github.com/rest/apps/apps#get-an-installation-for-the-authenticated-app 262 // 263 //meta:operation GET /app/installations/{installation_id} 264 func (s *AppsService) GetInstallation(ctx context.Context, id int64) (*Installation, *Response, error) { 265 return s.getInstallation(ctx, fmt.Sprintf("app/installations/%v", id)) 266 } 267 268 // ListUserInstallations lists installations that are accessible to the authenticated user. 269 // 270 // GitHub API docs: https://docs.github.com/rest/apps/installations#list-app-installations-accessible-to-the-user-access-token 271 // 272 //meta:operation GET /user/installations 273 func (s *AppsService) ListUserInstallations(ctx context.Context, opts *ListOptions) ([]*Installation, *Response, error) { 274 u, err := addOptions("user/installations", opts) 275 if err != nil { 276 return nil, nil, err 277 } 278 279 req, err := s.client.NewRequest("GET", u, nil) 280 if err != nil { 281 return nil, nil, err 282 } 283 284 var i struct { 285 Installations []*Installation `json:"installations"` 286 } 287 resp, err := s.client.Do(ctx, req, &i) 288 if err != nil { 289 return nil, resp, err 290 } 291 292 return i.Installations, resp, nil 293 } 294 295 // SuspendInstallation suspends the specified installation. 296 // 297 // GitHub API docs: https://docs.github.com/rest/apps/apps#suspend-an-app-installation 298 // 299 //meta:operation PUT /app/installations/{installation_id}/suspended 300 func (s *AppsService) SuspendInstallation(ctx context.Context, id int64) (*Response, error) { 301 u := fmt.Sprintf("app/installations/%v/suspended", id) 302 303 req, err := s.client.NewRequest("PUT", u, nil) 304 if err != nil { 305 return nil, err 306 } 307 308 return s.client.Do(ctx, req, nil) 309 } 310 311 // UnsuspendInstallation unsuspends the specified installation. 312 // 313 // GitHub API docs: https://docs.github.com/rest/apps/apps#unsuspend-an-app-installation 314 // 315 //meta:operation DELETE /app/installations/{installation_id}/suspended 316 func (s *AppsService) UnsuspendInstallation(ctx context.Context, id int64) (*Response, error) { 317 u := fmt.Sprintf("app/installations/%v/suspended", id) 318 319 req, err := s.client.NewRequest("DELETE", u, nil) 320 if err != nil { 321 return nil, err 322 } 323 324 return s.client.Do(ctx, req, nil) 325 } 326 327 // DeleteInstallation deletes the specified installation. 328 // 329 // GitHub API docs: https://docs.github.com/rest/apps/apps#delete-an-installation-for-the-authenticated-app 330 // 331 //meta:operation DELETE /app/installations/{installation_id} 332 func (s *AppsService) DeleteInstallation(ctx context.Context, id int64) (*Response, error) { 333 u := fmt.Sprintf("app/installations/%v", id) 334 335 req, err := s.client.NewRequest("DELETE", u, nil) 336 if err != nil { 337 return nil, err 338 } 339 340 return s.client.Do(ctx, req, nil) 341 } 342 343 // CreateInstallationToken creates a new installation token. 344 // 345 // GitHub API docs: https://docs.github.com/rest/apps/apps#create-an-installation-access-token-for-an-app 346 // 347 //meta:operation POST /app/installations/{installation_id}/access_tokens 348 func (s *AppsService) CreateInstallationToken(ctx context.Context, id int64, opts *InstallationTokenOptions) (*InstallationToken, *Response, error) { 349 u := fmt.Sprintf("app/installations/%v/access_tokens", id) 350 351 req, err := s.client.NewRequest("POST", u, opts) 352 if err != nil { 353 return nil, nil, err 354 } 355 356 t := new(InstallationToken) 357 resp, err := s.client.Do(ctx, req, t) 358 if err != nil { 359 return nil, resp, err 360 } 361 362 return t, resp, nil 363 } 364 365 // CreateInstallationTokenListRepos creates a new installation token with a list of all repositories in an installation which is not possible with CreateInstallationToken. 366 // 367 // It differs from CreateInstallationToken by taking InstallationTokenListRepoOptions as a parameter which does not omit RepositoryIDs if that field is nil or an empty array. 368 // 369 // GitHub API docs: https://docs.github.com/rest/apps/apps#create-an-installation-access-token-for-an-app 370 // 371 //meta:operation POST /app/installations/{installation_id}/access_tokens 372 func (s *AppsService) CreateInstallationTokenListRepos(ctx context.Context, id int64, opts *InstallationTokenListRepoOptions) (*InstallationToken, *Response, error) { 373 u := fmt.Sprintf("app/installations/%v/access_tokens", id) 374 375 req, err := s.client.NewRequest("POST", u, opts) 376 if err != nil { 377 return nil, nil, err 378 } 379 380 t := new(InstallationToken) 381 resp, err := s.client.Do(ctx, req, t) 382 if err != nil { 383 return nil, resp, err 384 } 385 386 return t, resp, nil 387 } 388 389 // CreateAttachment creates a new attachment on user comment containing a url. 390 // 391 // GitHub API docs: https://docs.github.com/enterprise-server@3.3/rest/reference/apps#create-a-content-attachment 392 // 393 //meta:operation POST /repos/{owner}/{repo}/content_references/{content_reference_id}/attachments 394 func (s *AppsService) CreateAttachment(ctx context.Context, contentReferenceID int64, title, body string) (*Attachment, *Response, error) { 395 u := fmt.Sprintf("content_references/%v/attachments", contentReferenceID) 396 payload := &Attachment{Title: String(title), Body: String(body)} 397 req, err := s.client.NewRequest("POST", u, payload) 398 if err != nil { 399 return nil, nil, err 400 } 401 402 // TODO: remove custom Accept headers when APIs fully launch. 403 req.Header.Set("Accept", mediaTypeContentAttachmentsPreview) 404 405 m := &Attachment{} 406 resp, err := s.client.Do(ctx, req, m) 407 if err != nil { 408 return nil, resp, err 409 } 410 411 return m, resp, nil 412 } 413 414 // FindOrganizationInstallation finds the organization's installation information. 415 // 416 // GitHub API docs: https://docs.github.com/rest/apps/apps#get-an-organization-installation-for-the-authenticated-app 417 // 418 //meta:operation GET /orgs/{org}/installation 419 func (s *AppsService) FindOrganizationInstallation(ctx context.Context, org string) (*Installation, *Response, error) { 420 return s.getInstallation(ctx, fmt.Sprintf("orgs/%v/installation", org)) 421 } 422 423 // FindRepositoryInstallation finds the repository's installation information. 424 // 425 // GitHub API docs: https://docs.github.com/rest/apps/apps#get-a-repository-installation-for-the-authenticated-app 426 // 427 //meta:operation GET /repos/{owner}/{repo}/installation 428 func (s *AppsService) FindRepositoryInstallation(ctx context.Context, owner, repo string) (*Installation, *Response, error) { 429 return s.getInstallation(ctx, fmt.Sprintf("repos/%v/%v/installation", owner, repo)) 430 } 431 432 // FindRepositoryInstallationByID finds the repository's installation information. 433 // 434 // Note: FindRepositoryInstallationByID uses the undocumented GitHub API endpoint "GET /repositories/{repository_id}/installation". 435 // 436 //meta:operation GET /repositories/{repository_id}/installation 437 func (s *AppsService) FindRepositoryInstallationByID(ctx context.Context, id int64) (*Installation, *Response, error) { 438 return s.getInstallation(ctx, fmt.Sprintf("repositories/%d/installation", id)) 439 } 440 441 // FindUserInstallation finds the user's installation information. 442 // 443 // GitHub API docs: https://docs.github.com/rest/apps/apps#get-a-user-installation-for-the-authenticated-app 444 // 445 //meta:operation GET /users/{username}/installation 446 func (s *AppsService) FindUserInstallation(ctx context.Context, user string) (*Installation, *Response, error) { 447 return s.getInstallation(ctx, fmt.Sprintf("users/%v/installation", user)) 448 } 449 450 func (s *AppsService) getInstallation(ctx context.Context, url string) (*Installation, *Response, error) { 451 req, err := s.client.NewRequest("GET", url, nil) 452 if err != nil { 453 return nil, nil, err 454 } 455 456 i := new(Installation) 457 resp, err := s.client.Do(ctx, req, i) 458 if err != nil { 459 return nil, resp, err 460 } 461 462 return i, resp, nil 463 }