orgs.go

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