apps.go

Documentation: github.com/google/go-github/v33/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  	"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  }
   340
View as plain text