apps.go

Documentation: github.com/google/go-github/v55/github

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