orgs.go

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

     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/rest/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  	// MembersCanForkPrivateRepos toggles whether organization members can fork private organization repositories.
    69  	MembersCanForkPrivateRepos *bool `json:"members_can_fork_private_repositories,omitempty"`
    70  
    71  	// MembersAllowedRepositoryCreationType denotes if organization members can create repositories
    72  	// and the type of repositories they can create. Possible values are: "all", "private", or "none".
    73  	//
    74  	// Deprecated: Use MembersCanCreatePublicRepos, MembersCanCreatePrivateRepos, MembersCanCreateInternalRepos
    75  	// instead. The new fields overrides the existing MembersAllowedRepositoryCreationType during 'edit'
    76  	// operation and does not consider 'internal' repositories during 'get' operation
    77  	MembersAllowedRepositoryCreationType *string `json:"members_allowed_repository_creation_type,omitempty"`
    78  
    79  	// MembersCanCreatePages toggles whether organization members can create GitHub Pages sites.
    80  	MembersCanCreatePages *bool `json:"members_can_create_pages,omitempty"`
    81  	// MembersCanCreatePublicPages toggles whether organization members can create public GitHub Pages sites.
    82  	MembersCanCreatePublicPages *bool `json:"members_can_create_public_pages,omitempty"`
    83  	// MembersCanCreatePrivatePages toggles whether organization members can create private GitHub Pages sites.
    84  	MembersCanCreatePrivatePages *bool `json:"members_can_create_private_pages,omitempty"`
    85  
    86  	// API URLs
    87  	URL              *string `json:"url,omitempty"`
    88  	EventsURL        *string `json:"events_url,omitempty"`
    89  	HooksURL         *string `json:"hooks_url,omitempty"`
    90  	IssuesURL        *string `json:"issues_url,omitempty"`
    91  	MembersURL       *string `json:"members_url,omitempty"`
    92  	PublicMembersURL *string `json:"public_members_url,omitempty"`
    93  	ReposURL         *string `json:"repos_url,omitempty"`
    94  }
    95  
    96  // OrganizationInstallations represents GitHub app installations for an organization.
    97  type OrganizationInstallations struct {
    98  	TotalCount    *int            `json:"total_count,omitempty"`
    99  	Installations []*Installation `json:"installations,omitempty"`
   100  }
   101  
   102  func (o Organization) String() string {
   103  	return Stringify(o)
   104  }
   105  
   106  // Plan represents the payment plan for an account. See plans at https://github.com/plans.
   107  type Plan struct {
   108  	Name          *string `json:"name,omitempty"`
   109  	Space         *int    `json:"space,omitempty"`
   110  	Collaborators *int    `json:"collaborators,omitempty"`
   111  	PrivateRepos  *int    `json:"private_repos,omitempty"`
   112  	FilledSeats   *int    `json:"filled_seats,omitempty"`
   113  	Seats         *int    `json:"seats,omitempty"`
   114  }
   115  
   116  func (p Plan) String() string {
   117  	return Stringify(p)
   118  }
   119  
   120  // OrganizationsListOptions specifies the optional parameters to the
   121  // OrganizationsService.ListAll method.
   122  type OrganizationsListOptions struct {
   123  	// Since filters Organizations by ID.
   124  	Since int64 `url:"since,omitempty"`
   125  
   126  	// Note: Pagination is powered exclusively by the Since parameter,
   127  	// ListOptions.Page has no effect.
   128  	// ListOptions.PerPage controls an undocumented GitHub API parameter.
   129  	ListOptions
   130  }
   131  
   132  // ListAll lists all organizations, in the order that they were created on GitHub.
   133  //
   134  // Note: Pagination is powered exclusively by the since parameter. To continue
   135  // listing the next set of organizations, use the ID of the last-returned organization
   136  // as the opts.Since parameter for the next call.
   137  //
   138  // GitHub API docs: https://docs.github.com/en/rest/orgs/orgs#list-organizations
   139  func (s *OrganizationsService) ListAll(ctx context.Context, opts *OrganizationsListOptions) ([]*Organization, *Response, error) {
   140  	u, err := addOptions("organizations", opts)
   141  	if err != nil {
   142  		return nil, nil, err
   143  	}
   144  
   145  	req, err := s.client.NewRequest("GET", u, nil)
   146  	if err != nil {
   147  		return nil, nil, err
   148  	}
   149  
   150  	orgs := []*Organization{}
   151  	resp, err := s.client.Do(ctx, req, &orgs)
   152  	if err != nil {
   153  		return nil, resp, err
   154  	}
   155  	return orgs, resp, nil
   156  }
   157  
   158  // List the organizations for a user. Passing the empty string will list
   159  // organizations for the authenticated user.
   160  //
   161  // GitHub API docs: https://docs.github.com/en/rest/orgs/orgs#list-organizations-for-the-authenticated-user
   162  // GitHub API docs: https://docs.github.com/en/rest/orgs/orgs#list-organizations-for-a-user
   163  func (s *OrganizationsService) List(ctx context.Context, user string, opts *ListOptions) ([]*Organization, *Response, error) {
   164  	var u string
   165  	if user != "" {
   166  		u = fmt.Sprintf("users/%v/orgs", user)
   167  	} else {
   168  		u = "user/orgs"
   169  	}
   170  	u, err := addOptions(u, opts)
   171  	if err != nil {
   172  		return nil, nil, err
   173  	}
   174  
   175  	req, err := s.client.NewRequest("GET", u, nil)
   176  	if err != nil {
   177  		return nil, nil, err
   178  	}
   179  
   180  	var orgs []*Organization
   181  	resp, err := s.client.Do(ctx, req, &orgs)
   182  	if err != nil {
   183  		return nil, resp, err
   184  	}
   185  
   186  	return orgs, resp, nil
   187  }
   188  
   189  // Get fetches an organization by name.
   190  //
   191  // GitHub API docs: https://docs.github.com/en/rest/orgs/orgs#get-an-organization
   192  func (s *OrganizationsService) Get(ctx context.Context, org string) (*Organization, *Response, error) {
   193  	u := fmt.Sprintf("orgs/%v", org)
   194  	req, err := s.client.NewRequest("GET", u, nil)
   195  	if err != nil {
   196  		return nil, nil, err
   197  	}
   198  
   199  	// TODO: remove custom Accept header when this API fully launches.
   200  	req.Header.Set("Accept", mediaTypeMemberAllowedRepoCreationTypePreview)
   201  
   202  	organization := new(Organization)
   203  	resp, err := s.client.Do(ctx, req, organization)
   204  	if err != nil {
   205  		return nil, resp, err
   206  	}
   207  
   208  	return organization, resp, nil
   209  }
   210  
   211  // GetByID fetches an organization.
   212  //
   213  // Note: GetByID uses the undocumented GitHub API endpoint /organizations/:id.
   214  func (s *OrganizationsService) GetByID(ctx context.Context, id int64) (*Organization, *Response, error) {
   215  	u := fmt.Sprintf("organizations/%d", id)
   216  	req, err := s.client.NewRequest("GET", u, nil)
   217  	if err != nil {
   218  		return nil, nil, err
   219  	}
   220  
   221  	organization := new(Organization)
   222  	resp, err := s.client.Do(ctx, req, organization)
   223  	if err != nil {
   224  		return nil, resp, err
   225  	}
   226  
   227  	return organization, resp, nil
   228  }
   229  
   230  // Edit an organization.
   231  //
   232  // GitHub API docs: https://docs.github.com/en/rest/orgs/orgs#update-an-organization
   233  func (s *OrganizationsService) Edit(ctx context.Context, name string, org *Organization) (*Organization, *Response, error) {
   234  	u := fmt.Sprintf("orgs/%v", name)
   235  	req, err := s.client.NewRequest("PATCH", u, org)
   236  	if err != nil {
   237  		return nil, nil, err
   238  	}
   239  
   240  	// TODO: remove custom Accept header when this API fully launches.
   241  	req.Header.Set("Accept", mediaTypeMemberAllowedRepoCreationTypePreview)
   242  
   243  	o := new(Organization)
   244  	resp, err := s.client.Do(ctx, req, o)
   245  	if err != nil {
   246  		return nil, resp, err
   247  	}
   248  
   249  	return o, resp, nil
   250  }
   251  
   252  // ListInstallations lists installations for an organization.
   253  //
   254  // GitHub API docs: https://docs.github.com/en/rest/orgs/orgs#list-app-installations-for-an-organization
   255  func (s *OrganizationsService) ListInstallations(ctx context.Context, org string, opts *ListOptions) (*OrganizationInstallations, *Response, error) {
   256  	u := fmt.Sprintf("orgs/%v/installations", org)
   257  
   258  	u, err := addOptions(u, opts)
   259  	if err != nil {
   260  		return nil, nil, err
   261  	}
   262  
   263  	req, err := s.client.NewRequest("GET", u, nil)
   264  	if err != nil {
   265  		return nil, nil, err
   266  	}
   267  
   268  	result := new(OrganizationInstallations)
   269  	resp, err := s.client.Do(ctx, req, result)
   270  	if err != nil {
   271  		return nil, resp, err
   272  	}
   273  
   274  	return result, resp, nil
   275  }
   276
View as plain text