apps.go

Documentation: github.com/google/go-github/v45/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/rest/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/apps#create-an-installation-access-token-for-an-app
    63  //   https://docs.github.com/en/rest/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/rest/apps/apps#get-the-authenticated-app
   152  // GitHub API docs: https://docs.github.com/en/rest/apps/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/rest/apps/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/rest/apps/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/rest/apps/installations#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/rest/apps/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/rest/apps/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/rest/apps/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/rest/apps/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  // TODO: Find GitHub API docs.
   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/rest/apps/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/rest/apps/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/rest/apps/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  }
   357
View as plain text