github.com/google/go-github/v33@v33.0.0/github/orgs.go (about)

     1  // Copyright 2013 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  // OrganizationsService provides access to the organization related functions
    15  // in the GitHub API.
    16  //
    17  // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/orgs/
    18  type OrganizationsService service
    19  
    20  // Organization represents a GitHub organization account.
    21  type Organization struct {
    22  	Login                       *string    `json:"login,omitempty"`
    23  	ID                          *int64     `json:"id,omitempty"`
    24  	NodeID                      *string    `json:"node_id,omitempty"`
    25  	AvatarURL                   *string    `json:"avatar_url,omitempty"`
    26  	HTMLURL                     *string    `json:"html_url,omitempty"`
    27  	Name                        *string    `json:"name,omitempty"`
    28  	Company                     *string    `json:"company,omitempty"`
    29  	Blog                        *string    `json:"blog,omitempty"`
    30  	Location                    *string    `json:"location,omitempty"`
    31  	Email                       *string    `json:"email,omitempty"`
    32  	TwitterUsername             *string    `json:"twitter_username,omitempty"`
    33  	Description                 *string    `json:"description,omitempty"`
    34  	PublicRepos                 *int       `json:"public_repos,omitempty"`
    35  	PublicGists                 *int       `json:"public_gists,omitempty"`
    36  	Followers                   *int       `json:"followers,omitempty"`
    37  	Following                   *int       `json:"following,omitempty"`
    38  	CreatedAt                   *time.Time `json:"created_at,omitempty"`
    39  	UpdatedAt                   *time.Time `json:"updated_at,omitempty"`
    40  	TotalPrivateRepos           *int       `json:"total_private_repos,omitempty"`
    41  	OwnedPrivateRepos           *int       `json:"owned_private_repos,omitempty"`
    42  	PrivateGists                *int       `json:"private_gists,omitempty"`
    43  	DiskUsage                   *int       `json:"disk_usage,omitempty"`
    44  	Collaborators               *int       `json:"collaborators,omitempty"`
    45  	BillingEmail                *string    `json:"billing_email,omitempty"`
    46  	Type                        *string    `json:"type,omitempty"`
    47  	Plan                        *Plan      `json:"plan,omitempty"`
    48  	TwoFactorRequirementEnabled *bool      `json:"two_factor_requirement_enabled,omitempty"`
    49  	IsVerified                  *bool      `json:"is_verified,omitempty"`
    50  	HasOrganizationProjects     *bool      `json:"has_organization_projects,omitempty"`
    51  	HasRepositoryProjects       *bool      `json:"has_repository_projects,omitempty"`
    52  
    53  	// DefaultRepoPermission can be one of: "read", "write", "admin", or "none". (Default: "read").
    54  	// It is only used in OrganizationsService.Edit.
    55  	DefaultRepoPermission *string `json:"default_repository_permission,omitempty"`
    56  	// DefaultRepoSettings can be one of: "read", "write", "admin", or "none". (Default: "read").
    57  	// It is only used in OrganizationsService.Get.
    58  	DefaultRepoSettings *string `json:"default_repository_settings,omitempty"`
    59  
    60  	// MembersCanCreateRepos default value is true and is only used in Organizations.Edit.
    61  	MembersCanCreateRepos *bool `json:"members_can_create_repositories,omitempty"`
    62  
    63  	// https://developer.github.com/changes/2019-12-03-internal-visibility-changes/#rest-v3-api
    64  	MembersCanCreatePublicRepos   *bool `json:"members_can_create_public_repositories,omitempty"`
    65  	MembersCanCreatePrivateRepos  *bool `json:"members_can_create_private_repositories,omitempty"`
    66  	MembersCanCreateInternalRepos *bool `json:"members_can_create_internal_repositories,omitempty"`
    67  
    68  	// MembersAllowedRepositoryCreationType denotes if organization members can create repositories
    69  	// and the type of repositories they can create. Possible values are: "all", "private", or "none".
    70  	//
    71  	// Deprecated: Use MembersCanCreatePublicRepos, MembersCanCreatePrivateRepos, MembersCanCreateInternalRepos
    72  	// instead. The new fields overrides the existing MembersAllowedRepositoryCreationType during 'edit'
    73  	// operation and does not consider 'internal' repositories during 'get' operation
    74  	MembersAllowedRepositoryCreationType *string `json:"members_allowed_repository_creation_type,omitempty"`
    75  
    76  	// API URLs
    77  	URL              *string `json:"url,omitempty"`
    78  	EventsURL        *string `json:"events_url,omitempty"`
    79  	HooksURL         *string `json:"hooks_url,omitempty"`
    80  	IssuesURL        *string `json:"issues_url,omitempty"`
    81  	MembersURL       *string `json:"members_url,omitempty"`
    82  	PublicMembersURL *string `json:"public_members_url,omitempty"`
    83  	ReposURL         *string `json:"repos_url,omitempty"`
    84  }
    85  
    86  // OrganizationInstallations represents GitHub app installations for an organization.
    87  type OrganizationInstallations struct {
    88  	TotalCount    *int            `json:"total_count,omitempty"`
    89  	Installations []*Installation `json:"installations,omitempty"`
    90  }
    91  
    92  func (o Organization) String() string {
    93  	return Stringify(o)
    94  }
    95  
    96  // Plan represents the payment plan for an account. See plans at https://github.com/plans.
    97  type Plan struct {
    98  	Name          *string `json:"name,omitempty"`
    99  	Space         *int    `json:"space,omitempty"`
   100  	Collaborators *int    `json:"collaborators,omitempty"`
   101  	PrivateRepos  *int    `json:"private_repos,omitempty"`
   102  	FilledSeats   *int    `json:"filled_seats,omitempty"`
   103  	Seats         *int    `json:"seats,omitempty"`
   104  }
   105  
   106  func (p Plan) String() string {
   107  	return Stringify(p)
   108  }
   109  
   110  // OrganizationsListOptions specifies the optional parameters to the
   111  // OrganizationsService.ListAll method.
   112  type OrganizationsListOptions struct {
   113  	// Since filters Organizations by ID.
   114  	Since int64 `url:"since,omitempty"`
   115  
   116  	// Note: Pagination is powered exclusively by the Since parameter,
   117  	// ListOptions.Page has no effect.
   118  	// ListOptions.PerPage controls an undocumented GitHub API parameter.
   119  	ListOptions
   120  }
   121  
   122  // ListAll lists all organizations, in the order that they were created on GitHub.
   123  //
   124  // Note: Pagination is powered exclusively by the since parameter. To continue
   125  // listing the next set of organizations, use the ID of the last-returned organization
   126  // as the opts.Since parameter for the next call.
   127  //
   128  // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/orgs/#list-organizations
   129  func (s *OrganizationsService) ListAll(ctx context.Context, opts *OrganizationsListOptions) ([]*Organization, *Response, error) {
   130  	u, err := addOptions("organizations", opts)
   131  	if err != nil {
   132  		return nil, nil, err
   133  	}
   134  
   135  	req, err := s.client.NewRequest("GET", u, nil)
   136  	if err != nil {
   137  		return nil, nil, err
   138  	}
   139  
   140  	orgs := []*Organization{}
   141  	resp, err := s.client.Do(ctx, req, &orgs)
   142  	if err != nil {
   143  		return nil, resp, err
   144  	}
   145  	return orgs, resp, nil
   146  }
   147  
   148  // List the organizations for a user. Passing the empty string will list
   149  // organizations for the authenticated user.
   150  //
   151  // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/orgs/#list-organizations-for-the-authenticated-user
   152  // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/orgs/#list-organizations-for-a-user
   153  func (s *OrganizationsService) List(ctx context.Context, user string, opts *ListOptions) ([]*Organization, *Response, error) {
   154  	var u string
   155  	if user != "" {
   156  		u = fmt.Sprintf("users/%v/orgs", user)
   157  	} else {
   158  		u = "user/orgs"
   159  	}
   160  	u, err := addOptions(u, opts)
   161  	if err != nil {
   162  		return nil, nil, err
   163  	}
   164  
   165  	req, err := s.client.NewRequest("GET", u, nil)
   166  	if err != nil {
   167  		return nil, nil, err
   168  	}
   169  
   170  	var orgs []*Organization
   171  	resp, err := s.client.Do(ctx, req, &orgs)
   172  	if err != nil {
   173  		return nil, resp, err
   174  	}
   175  
   176  	return orgs, resp, nil
   177  }
   178  
   179  // Get fetches an organization by name.
   180  //
   181  // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/orgs/#get-an-organization
   182  func (s *OrganizationsService) Get(ctx context.Context, org string) (*Organization, *Response, error) {
   183  	u := fmt.Sprintf("orgs/%v", org)
   184  	req, err := s.client.NewRequest("GET", u, nil)
   185  	if err != nil {
   186  		return nil, nil, err
   187  	}
   188  
   189  	// TODO: remove custom Accept header when this API fully launches.
   190  	req.Header.Set("Accept", mediaTypeMemberAllowedRepoCreationTypePreview)
   191  
   192  	organization := new(Organization)
   193  	resp, err := s.client.Do(ctx, req, organization)
   194  	if err != nil {
   195  		return nil, resp, err
   196  	}
   197  
   198  	return organization, resp, nil
   199  }
   200  
   201  // GetByID fetches an organization.
   202  //
   203  // Note: GetByID uses the undocumented GitHub API endpoint /organizations/:id.
   204  func (s *OrganizationsService) GetByID(ctx context.Context, id int64) (*Organization, *Response, error) {
   205  	u := fmt.Sprintf("organizations/%d", id)
   206  	req, err := s.client.NewRequest("GET", u, nil)
   207  	if err != nil {
   208  		return nil, nil, err
   209  	}
   210  
   211  	organization := new(Organization)
   212  	resp, err := s.client.Do(ctx, req, organization)
   213  	if err != nil {
   214  		return nil, resp, err
   215  	}
   216  
   217  	return organization, resp, nil
   218  }
   219  
   220  // Edit an organization.
   221  //
   222  // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/orgs/#update-an-organization
   223  func (s *OrganizationsService) Edit(ctx context.Context, name string, org *Organization) (*Organization, *Response, error) {
   224  	u := fmt.Sprintf("orgs/%v", name)
   225  	req, err := s.client.NewRequest("PATCH", u, org)
   226  	if err != nil {
   227  		return nil, nil, err
   228  	}
   229  
   230  	// TODO: remove custom Accept header when this API fully launches.
   231  	req.Header.Set("Accept", mediaTypeMemberAllowedRepoCreationTypePreview)
   232  
   233  	o := new(Organization)
   234  	resp, err := s.client.Do(ctx, req, o)
   235  	if err != nil {
   236  		return nil, resp, err
   237  	}
   238  
   239  	return o, resp, nil
   240  }
   241  
   242  // ListInstallations lists installations for an organization.
   243  //
   244  // GitHub API docs: https://docs.github.com/en/free-pro-team@latest/rest/reference/orgs/#list-app-installations-for-an-organization
   245  func (s *OrganizationsService) ListInstallations(ctx context.Context, org string, opts *ListOptions) (*OrganizationInstallations, *Response, error) {
   246  	u := fmt.Sprintf("orgs/%v/installations", org)
   247  
   248  	u, err := addOptions(u, opts)
   249  	if err != nil {
   250  		return nil, nil, err
   251  	}
   252  
   253  	req, err := s.client.NewRequest("GET", u, nil)
   254  	if err != nil {
   255  		return nil, nil, err
   256  	}
   257  
   258  	result := new(OrganizationInstallations)
   259  	resp, err := s.client.Do(ctx, req, result)
   260  	if err != nil {
   261  		return nil, resp, err
   262  	}
   263  
   264  	return result, resp, nil
   265  }