orgs.go

Documentation: github.com/google/go-github/v47/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  	// WebCommitSignoffRequire toggles
    86  	WebCommitSignoffRequired *bool `json:"web_commit_signoff_required,omitempty"`
    87  	// AdvancedSecurityAuditLogEnabled toggles whether the advanced security audit log is enabled.
    88  	AdvancedSecurityEnabledForNewRepos *bool `json:"advanced_security_enabled_for_new_repositories,omitempty"`
    89  	// DependabotAlertsEnabled toggles whether dependabot alerts are enabled.
    90  	DependabotAlertsEnabledForNewRepos *bool `json:"dependabot_alerts_enabled_for_new_repositories,omitempty"`
    91  	// DependabotSecurityUpdatesEnabled toggles whether dependabot security updates are enabled.
    92  	DependabotSecurityUpdatesEnabledForNewRepos *bool `json:"dependabot_security_updates_enabled_for_new_repositories,omitempty"`
    93  	// DependabotGraphEnabledForNewRepos toggles whether dependabot graph is enabled on new repositories.
    94  	DependencyGraphEnabledForNewRepos *bool `json:"dependency_graph_enabled_for_new_repositories,omitempty"`
    95  	// SecretScanningEnabled toggles whether secret scanning is enabled on new repositories.
    96  	SecretScanningEnabledForNewRepos *bool `json:"secret_scanning_enabled_for_new_repositories,omitempty"`
    97  	// SecretScanningPushProtectionEnabledForNewRepos toggles whether secret scanning push protection is enabled on new repositories.
    98  	SecretScanningPushProtectionEnabledForNewRepos *bool `json:"secret_scanning_push_protection_enabled_for_new_repositories,omitempty"`
    99  
   100  	// API URLs
   101  	URL              *string `json:"url,omitempty"`
   102  	EventsURL        *string `json:"events_url,omitempty"`
   103  	HooksURL         *string `json:"hooks_url,omitempty"`
   104  	IssuesURL        *string `json:"issues_url,omitempty"`
   105  	MembersURL       *string `json:"members_url,omitempty"`
   106  	PublicMembersURL *string `json:"public_members_url,omitempty"`
   107  	ReposURL         *string `json:"repos_url,omitempty"`
   108  }
   109  
   110  // OrganizationInstallations represents GitHub app installations for an organization.
   111  type OrganizationInstallations struct {
   112  	TotalCount    *int            `json:"total_count,omitempty"`
   113  	Installations []*Installation `json:"installations,omitempty"`
   114  }
   115  
   116  func (o Organization) String() string {
   117  	return Stringify(o)
   118  }
   119  
   120  // Plan represents the payment plan for an account. See plans at https://github.com/plans.
   121  type Plan struct {
   122  	Name          *string `json:"name,omitempty"`
   123  	Space         *int    `json:"space,omitempty"`
   124  	Collaborators *int    `json:"collaborators,omitempty"`
   125  	PrivateRepos  *int    `json:"private_repos,omitempty"`
   126  	FilledSeats   *int    `json:"filled_seats,omitempty"`
   127  	Seats         *int    `json:"seats,omitempty"`
   128  }
   129  
   130  func (p Plan) String() string {
   131  	return Stringify(p)
   132  }
   133  
   134  // OrganizationsListOptions specifies the optional parameters to the
   135  // OrganizationsService.ListAll method.
   136  type OrganizationsListOptions struct {
   137  	// Since filters Organizations by ID.
   138  	Since int64 `url:"since,omitempty"`
   139  
   140  	// Note: Pagination is powered exclusively by the Since parameter,
   141  	// ListOptions.Page has no effect.
   142  	// ListOptions.PerPage controls an undocumented GitHub API parameter.
   143  	ListOptions
   144  }
   145  
   146  // ListAll lists all organizations, in the order that they were created on GitHub.
   147  //
   148  // Note: Pagination is powered exclusively by the since parameter. To continue
   149  // listing the next set of organizations, use the ID of the last-returned organization
   150  // as the opts.Since parameter for the next call.
   151  //
   152  // GitHub API docs: https://docs.github.com/en/rest/orgs/orgs#list-organizations
   153  func (s *OrganizationsService) ListAll(ctx context.Context, opts *OrganizationsListOptions) ([]*Organization, *Response, error) {
   154  	u, err := addOptions("organizations", opts)
   155  	if err != nil {
   156  		return nil, nil, err
   157  	}
   158  
   159  	req, err := s.client.NewRequest("GET", u, nil)
   160  	if err != nil {
   161  		return nil, nil, err
   162  	}
   163  
   164  	orgs := []*Organization{}
   165  	resp, err := s.client.Do(ctx, req, &orgs)
   166  	if err != nil {
   167  		return nil, resp, err
   168  	}
   169  	return orgs, resp, nil
   170  }
   171  
   172  // List the organizations for a user. Passing the empty string will list
   173  // organizations for the authenticated user.
   174  //
   175  // GitHub API docs: https://docs.github.com/en/rest/orgs/orgs#list-organizations-for-the-authenticated-user
   176  // GitHub API docs: https://docs.github.com/en/rest/orgs/orgs#list-organizations-for-a-user
   177  func (s *OrganizationsService) List(ctx context.Context, user string, opts *ListOptions) ([]*Organization, *Response, error) {
   178  	var u string
   179  	if user != "" {
   180  		u = fmt.Sprintf("users/%v/orgs", user)
   181  	} else {
   182  		u = "user/orgs"
   183  	}
   184  	u, err := addOptions(u, opts)
   185  	if err != nil {
   186  		return nil, nil, err
   187  	}
   188  
   189  	req, err := s.client.NewRequest("GET", u, nil)
   190  	if err != nil {
   191  		return nil, nil, err
   192  	}
   193  
   194  	var orgs []*Organization
   195  	resp, err := s.client.Do(ctx, req, &orgs)
   196  	if err != nil {
   197  		return nil, resp, err
   198  	}
   199  
   200  	return orgs, resp, nil
   201  }
   202  
   203  // Get fetches an organization by name.
   204  //
   205  // GitHub API docs: https://docs.github.com/en/rest/orgs/orgs#get-an-organization
   206  func (s *OrganizationsService) Get(ctx context.Context, org string) (*Organization, *Response, error) {
   207  	u := fmt.Sprintf("orgs/%v", org)
   208  	req, err := s.client.NewRequest("GET", u, nil)
   209  	if err != nil {
   210  		return nil, nil, err
   211  	}
   212  
   213  	// TODO: remove custom Accept header when this API fully launches.
   214  	req.Header.Set("Accept", mediaTypeMemberAllowedRepoCreationTypePreview)
   215  
   216  	organization := new(Organization)
   217  	resp, err := s.client.Do(ctx, req, organization)
   218  	if err != nil {
   219  		return nil, resp, err
   220  	}
   221  
   222  	return organization, resp, nil
   223  }
   224  
   225  // GetByID fetches an organization.
   226  //
   227  // Note: GetByID uses the undocumented GitHub API endpoint /organizations/:id.
   228  func (s *OrganizationsService) GetByID(ctx context.Context, id int64) (*Organization, *Response, error) {
   229  	u := fmt.Sprintf("organizations/%d", id)
   230  	req, err := s.client.NewRequest("GET", u, nil)
   231  	if err != nil {
   232  		return nil, nil, err
   233  	}
   234  
   235  	organization := new(Organization)
   236  	resp, err := s.client.Do(ctx, req, organization)
   237  	if err != nil {
   238  		return nil, resp, err
   239  	}
   240  
   241  	return organization, resp, nil
   242  }
   243  
   244  // Edit an organization.
   245  //
   246  // GitHub API docs: https://docs.github.com/en/rest/orgs/orgs#update-an-organization
   247  func (s *OrganizationsService) Edit(ctx context.Context, name string, org *Organization) (*Organization, *Response, error) {
   248  	u := fmt.Sprintf("orgs/%v", name)
   249  	req, err := s.client.NewRequest("PATCH", u, org)
   250  	if err != nil {
   251  		return nil, nil, err
   252  	}
   253  
   254  	// TODO: remove custom Accept header when this API fully launches.
   255  	req.Header.Set("Accept", mediaTypeMemberAllowedRepoCreationTypePreview)
   256  
   257  	o := new(Organization)
   258  	resp, err := s.client.Do(ctx, req, o)
   259  	if err != nil {
   260  		return nil, resp, err
   261  	}
   262  
   263  	return o, resp, nil
   264  }
   265  
   266  // ListInstallations lists installations for an organization.
   267  //
   268  // GitHub API docs: https://docs.github.com/en/rest/orgs/orgs#list-app-installations-for-an-organization
   269  func (s *OrganizationsService) ListInstallations(ctx context.Context, org string, opts *ListOptions) (*OrganizationInstallations, *Response, error) {
   270  	u := fmt.Sprintf("orgs/%v/installations", org)
   271  
   272  	u, err := addOptions(u, opts)
   273  	if err != nil {
   274  		return nil, nil, err
   275  	}
   276  
   277  	req, err := s.client.NewRequest("GET", u, nil)
   278  	if err != nil {
   279  		return nil, nil, err
   280  	}
   281  
   282  	result := new(OrganizationInstallations)
   283  	resp, err := s.client.Do(ctx, req, result)
   284  	if err != nil {
   285  		return nil, resp, err
   286  	}
   287  
   288  	return result, resp, nil
   289  }
   290
View as plain text