github.com/google/go-github/v42@v42.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 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 // InstallationPermissions lists the repository and organization permissions for an installation. 60 // 61 // Permission names taken from: 62 // https://docs.github.com/en/enterprise-server@3.0/rest/reference/apps#create-an-installation-access-token-for-an-app 63 // https://docs.github.com/en/rest/reference/apps#create-an-installation-access-token-for-an-app 64 type InstallationPermissions struct { 65 Actions *string `json:"actions,omitempty"` 66 Administration *string `json:"administration,omitempty"` 67 Blocking *string `json:"blocking,omitempty"` 68 Checks *string `json:"checks,omitempty"` 69 Contents *string `json:"contents,omitempty"` 70 ContentReferences *string `json:"content_references,omitempty"` 71 Deployments *string `json:"deployments,omitempty"` 72 Emails *string `json:"emails,omitempty"` 73 Environments *string `json:"environments,omitempty"` 74 Followers *string `json:"followers,omitempty"` 75 Issues *string `json:"issues,omitempty"` 76 Metadata *string `json:"metadata,omitempty"` 77 Members *string `json:"members,omitempty"` 78 OrganizationAdministration *string `json:"organization_administration,omitempty"` 79 OrganizationHooks *string `json:"organization_hooks,omitempty"` 80 OrganizationPlan *string `json:"organization_plan,omitempty"` 81 OrganizationPreReceiveHooks *string `json:"organization_pre_receive_hooks,omitempty"` 82 OrganizationProjects *string `json:"organization_projects,omitempty"` 83 OrganizationSecrets *string `json:"organization_secrets,omitempty"` 84 OrganizationSelfHostedRunners *string `json:"organization_self_hosted_runners,omitempty"` 85 OrganizationUserBlocking *string `json:"organization_user_blocking,omitempty"` 86 Packages *string `json:"packages,omitempty"` 87 Pages *string `json:"pages,omitempty"` 88 PullRequests *string `json:"pull_requests,omitempty"` 89 RepositoryHooks *string `json:"repository_hooks,omitempty"` 90 RepositoryProjects *string `json:"repository_projects,omitempty"` 91 RepositoryPreReceiveHooks *string `json:"repository_pre_receive_hooks,omitempty"` 92 Secrets *string `json:"secrets,omitempty"` 93 SecretScanningAlerts *string `json:"secret_scanning_alerts,omitempty"` 94 SecurityEvents *string `json:"security_events,omitempty"` 95 SingleFile *string `json:"single_file,omitempty"` 96 Statuses *string `json:"statuses,omitempty"` 97 TeamDiscussions *string `json:"team_discussions,omitempty"` 98 VulnerabilityAlerts *string `json:"vulnerability_alerts,omitempty"` 99 Workflows *string `json:"workflows,omitempty"` 100 } 101 102 // Installation represents a GitHub Apps installation. 103 type Installation struct { 104 ID *int64 `json:"id,omitempty"` 105 NodeID *string `json:"node_id,omitempty"` 106 AppID *int64 `json:"app_id,omitempty"` 107 AppSlug *string `json:"app_slug,omitempty"` 108 TargetID *int64 `json:"target_id,omitempty"` 109 Account *User `json:"account,omitempty"` 110 AccessTokensURL *string `json:"access_tokens_url,omitempty"` 111 RepositoriesURL *string `json:"repositories_url,omitempty"` 112 HTMLURL *string `json:"html_url,omitempty"` 113 TargetType *string `json:"target_type,omitempty"` 114 SingleFileName *string `json:"single_file_name,omitempty"` 115 RepositorySelection *string `json:"repository_selection,omitempty"` 116 Events []string `json:"events,omitempty"` 117 SingleFilePaths []string `json:"single_file_paths,omitempty"` 118 Permissions *InstallationPermissions `json:"permissions,omitempty"` 119 CreatedAt *Timestamp `json:"created_at,omitempty"` 120 UpdatedAt *Timestamp `json:"updated_at,omitempty"` 121 HasMultipleSingleFiles *bool `json:"has_multiple_single_files,omitempty"` 122 SuspendedBy *User `json:"suspended_by,omitempty"` 123 SuspendedAt *Timestamp `json:"suspended_at,omitempty"` 124 } 125 126 // Attachment represents a GitHub Apps attachment. 127 type Attachment struct { 128 ID *int64 `json:"id,omitempty"` 129 Title *string `json:"title,omitempty"` 130 Body *string `json:"body,omitempty"` 131 } 132 133 // ContentReference represents a reference to a URL in an issue or pull request. 134 type ContentReference struct { 135 ID *int64 `json:"id,omitempty"` 136 NodeID *string `json:"node_id,omitempty"` 137 Reference *string `json:"reference,omitempty"` 138 } 139 140 func (i Installation) String() string { 141 return Stringify(i) 142 } 143 144 // Get a single GitHub App. Passing the empty string will get 145 // the authenticated GitHub App. 146 // 147 // Note: appSlug is just the URL-friendly name of your GitHub App. 148 // You can find this on the settings page for your GitHub App 149 // (e.g., https://github.com/settings/apps/:app_slug). 150 // 151 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#get-the-authenticated-app 152 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#get-an-app 153 func (s *AppsService) Get(ctx context.Context, appSlug string) (*App, *Response, error) { 154 var u string 155 if appSlug != "" { 156 u = fmt.Sprintf("apps/%v", appSlug) 157 } else { 158 u = "app" 159 } 160 161 req, err := s.client.NewRequest("GET", u, nil) 162 if err != nil { 163 return nil, nil, err 164 } 165 166 app := new(App) 167 resp, err := s.client.Do(ctx, req, app) 168 if err != nil { 169 return nil, resp, err 170 } 171 172 return app, resp, nil 173 } 174 175 // ListInstallations lists the installations that the current GitHub App has. 176 // 177 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#list-installations-for-the-authenticated-app 178 func (s *AppsService) ListInstallations(ctx context.Context, opts *ListOptions) ([]*Installation, *Response, error) { 179 u, err := addOptions("app/installations", opts) 180 if err != nil { 181 return nil, nil, err 182 } 183 184 req, err := s.client.NewRequest("GET", u, nil) 185 if err != nil { 186 return nil, nil, err 187 } 188 189 var i []*Installation 190 resp, err := s.client.Do(ctx, req, &i) 191 if err != nil { 192 return nil, resp, err 193 } 194 195 return i, resp, nil 196 } 197 198 // GetInstallation returns the specified installation. 199 // 200 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#get-an-installation-for-the-authenticated-app 201 func (s *AppsService) GetInstallation(ctx context.Context, id int64) (*Installation, *Response, error) { 202 return s.getInstallation(ctx, fmt.Sprintf("app/installations/%v", id)) 203 } 204 205 // ListUserInstallations lists installations that are accessible to the authenticated user. 206 // 207 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#list-app-installations-accessible-to-the-user-access-token 208 func (s *AppsService) ListUserInstallations(ctx context.Context, opts *ListOptions) ([]*Installation, *Response, error) { 209 u, err := addOptions("user/installations", opts) 210 if err != nil { 211 return nil, nil, err 212 } 213 214 req, err := s.client.NewRequest("GET", u, nil) 215 if err != nil { 216 return nil, nil, err 217 } 218 219 var i struct { 220 Installations []*Installation `json:"installations"` 221 } 222 resp, err := s.client.Do(ctx, req, &i) 223 if err != nil { 224 return nil, resp, err 225 } 226 227 return i.Installations, resp, nil 228 } 229 230 // SuspendInstallation suspends the specified installation. 231 // 232 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#suspend-an-app-installation 233 func (s *AppsService) SuspendInstallation(ctx context.Context, id int64) (*Response, error) { 234 u := fmt.Sprintf("app/installations/%v/suspended", id) 235 236 req, err := s.client.NewRequest("PUT", u, nil) 237 if err != nil { 238 return nil, err 239 } 240 241 return s.client.Do(ctx, req, nil) 242 } 243 244 // UnsuspendInstallation unsuspends the specified installation. 245 // 246 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#unsuspend-an-app-installation 247 func (s *AppsService) UnsuspendInstallation(ctx context.Context, id int64) (*Response, error) { 248 u := fmt.Sprintf("app/installations/%v/suspended", id) 249 250 req, err := s.client.NewRequest("DELETE", u, nil) 251 if err != nil { 252 return nil, err 253 } 254 255 return s.client.Do(ctx, req, nil) 256 } 257 258 // DeleteInstallation deletes the specified installation. 259 // 260 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#delete-an-installation-for-the-authenticated-app 261 func (s *AppsService) DeleteInstallation(ctx context.Context, id int64) (*Response, error) { 262 u := fmt.Sprintf("app/installations/%v", id) 263 264 req, err := s.client.NewRequest("DELETE", u, nil) 265 if err != nil { 266 return nil, err 267 } 268 269 return s.client.Do(ctx, req, nil) 270 } 271 272 // CreateInstallationToken creates a new installation token. 273 // 274 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#create-an-installation-access-token-for-an-app 275 func (s *AppsService) CreateInstallationToken(ctx context.Context, id int64, opts *InstallationTokenOptions) (*InstallationToken, *Response, error) { 276 u := fmt.Sprintf("app/installations/%v/access_tokens", id) 277 278 req, err := s.client.NewRequest("POST", u, opts) 279 if err != nil { 280 return nil, nil, err 281 } 282 283 t := new(InstallationToken) 284 resp, err := s.client.Do(ctx, req, t) 285 if err != nil { 286 return nil, resp, err 287 } 288 289 return t, resp, nil 290 } 291 292 // CreateAttachment creates a new attachment on user comment containing a url. 293 // 294 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#create-a-content-attachment 295 func (s *AppsService) CreateAttachment(ctx context.Context, contentReferenceID int64, title, body string) (*Attachment, *Response, error) { 296 u := fmt.Sprintf("content_references/%v/attachments", contentReferenceID) 297 payload := &Attachment{Title: String(title), Body: String(body)} 298 req, err := s.client.NewRequest("POST", u, payload) 299 if err != nil { 300 return nil, nil, err 301 } 302 303 // TODO: remove custom Accept headers when APIs fully launch. 304 req.Header.Set("Accept", mediaTypeContentAttachmentsPreview) 305 306 m := &Attachment{} 307 resp, err := s.client.Do(ctx, req, m) 308 if err != nil { 309 return nil, resp, err 310 } 311 312 return m, resp, nil 313 } 314 315 // FindOrganizationInstallation finds the organization's installation information. 316 // 317 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#get-an-organization-installation-for-the-authenticated-app 318 func (s *AppsService) FindOrganizationInstallation(ctx context.Context, org string) (*Installation, *Response, error) { 319 return s.getInstallation(ctx, fmt.Sprintf("orgs/%v/installation", org)) 320 } 321 322 // FindRepositoryInstallation finds the repository's installation information. 323 // 324 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#get-a-repository-installation-for-the-authenticated-app 325 func (s *AppsService) FindRepositoryInstallation(ctx context.Context, owner, repo string) (*Installation, *Response, error) { 326 return s.getInstallation(ctx, fmt.Sprintf("repos/%v/%v/installation", owner, repo)) 327 } 328 329 // FindRepositoryInstallationByID finds the repository's installation information. 330 // 331 // Note: FindRepositoryInstallationByID uses the undocumented GitHub API endpoint /repositories/:id/installation. 332 func (s *AppsService) FindRepositoryInstallationByID(ctx context.Context, id int64) (*Installation, *Response, error) { 333 return s.getInstallation(ctx, fmt.Sprintf("repositories/%d/installation", id)) 334 } 335 336 // FindUserInstallation finds the user's installation information. 337 // 338 // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/apps/#get-a-user-installation-for-the-authenticated-app 339 func (s *AppsService) FindUserInstallation(ctx context.Context, user string) (*Installation, *Response, error) { 340 return s.getInstallation(ctx, fmt.Sprintf("users/%v/installation", user)) 341 } 342 343 func (s *AppsService) getInstallation(ctx context.Context, url string) (*Installation, *Response, error) { 344 req, err := s.client.NewRequest("GET", url, nil) 345 if err != nil { 346 return nil, nil, err 347 } 348 349 i := new(Installation) 350 resp, err := s.client.Do(ctx, req, i) 351 if err != nil { 352 return nil, resp, err 353 } 354 355 return i, resp, nil 356 }