github

package
v2.4.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 6, 2025 License: Apache-2.0 Imports: 26 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// "all" used in queries to get users with all roles.
	RoleAll = "all"
	// github.Invitation has "direct_member" instead of "member" as the role string.
	RoleDirectMember = "direct_member"
)
View Source 
const (
	IDSep = ":"
	// DefaultCacheDuration is the default time to live for the user and team caches.
	// We don't expect user info (e.g. username etc.) nor team info (team name etc.)
	// to change frequently so a time to live of 1 day is the default.
	DefaultCacheDuration = time.Hour * 24
)
View Source 
const DefaultGitHubEndpointURL = "https://github.com"
View Source 
const DefaultStaticTokenEnvVar = "TEAM_LINK_GITHUB_TOKEN" // #nosec G101

DefaultStaticTokenEnvVar is where we read default github token from. This is the default EnvVar we will write to, nosec here to avoid linting.

Variables

View Source 
var Roles []Role = []Role{Member, Admin}

List of roles ordered by lowest to highest privileges. Ensure any new roles added are properly ordered.

Functions

func CreateGraphQLClientWithToken 

func CreateGraphQLClientWithToken(ctx context.Context, token, endpoint string) *githubv4.Client

CreateGraphQLClientWithToken creates a graphQL client with a static token.

func Encode 

func Encode(orgID, teamID int64) string

Encode encodes the GitHub org ID and team ID as single ID string.

func GetAllOrgsSAMLIdentities 

func GetAllOrgsSAMLIdentities(ctx context.Context, httpClient *http.Client, endpoint string, ghc *github.Client, orgTeamSSORequired map[int64]map[int64]bool) (map[int64]map[string]struct{}, error)

GetAllOrgsSAMLIdentities get all users that have SAML identities from each organization. This function returns a map with each orgID as key and a set of users with samkIdentities as value.

func GetOrgSAMLIdentities 

func GetOrgSAMLIdentities(ctx context.Context, client *githubv4.Client, orglogin string) (map[string]struct{}, error)

GetOrgSAMLIdentities get all users with SAML identities from the given org.

func GetOrgSAMLIdentitiesByOrgID 

func GetOrgSAMLIdentitiesByOrgID(ctx context.Context, ghc *github.Client, gqc *githubv4.Client, orgID int64) (map[string]struct{}, error)

GetOrgSAMLIdentitiesByOrgID get SAML identities for the github org. The return is a map with users have external SAML identity attached.

func NewAppKeySignerProvider 

func NewAppKeySignerProvider(kp credentials.KeyProvider) credentials.SignerProvider

NewAppKeySignerProvider creates a signer provider with the given key provider.

func NewRoleMetadata 

func NewRoleMetadata(roleStr string) groupsync.MappingMetadata

Types

type AppKeySignerProvider 

type AppKeySignerProvider struct {
	// contains filtered or unexported fields
}

AppKeySignerProvider provides a GitHub private key signer from a GitHub app private key.

func (*AppKeySignerProvider) Signer 

func (p *AppKeySignerProvider) Signer(ctx context.Context) (crypto.Signer, error)

Signer provides the key signer, implementing the SignerProvider interface.

type AppTokenSource 

type AppTokenSource struct {
	// contains filtered or unexported fields
}

func NewAppTokenSource 

func NewAppTokenSource(signerProvider credentials.SignerProvider, appID string, appOpts ...githubauth.Option) *AppTokenSource

func (*AppTokenSource) TokenForOrg 

func (s *AppTokenSource) TokenForOrg(ctx context.Context, orgID int64) (string, error)

type Config 

type Config struct {
	// contains filtered or unexported fields
}

type EnterpriseRWOpt 

type EnterpriseRWOpt func(rw *EnterpriseUserWriter)

ENterpriseRWOpt is a configuration option for EnterpriseUserReadWriter.

func WithMaxUsersToProvision 

func WithMaxUsersToProvision(num int64) EnterpriseRWOpt

WithMaxUsersToProvision sets the maximum number of SCIM provisioned users.

func WithUserDeactivationSanityCheck added in v2.4.0 

func WithUserDeactivationSanityCheck(f func(context.Context, *SCIMUser, string) (bool, error)) EnterpriseRWOpt

WithUserDeactivationSanityCheck sets the sanity check function for SCIM user deactivation. It will only attempt to deactivate user If the func returns true.

type EnterpriseUserWriter 

type EnterpriseUserWriter struct {
	// contains filtered or unexported fields
}

EnterpriseUserWriter manages enterprise users via a direct GHES SCIM API client.

func NewEnterpriseUserWriter 

func NewEnterpriseUserWriter(httpClient *http.Client, enterpriseBaseURL string, opts ...EnterpriseRWOpt) (*EnterpriseUserWriter, error)

NewEnterpriseUserWriter creates a new EnterpriseUserWriter with default 1000 maximum number of users to provision if not override by given opts.

func (*EnterpriseUserWriter) SetMembers 

func (w *EnterpriseUserWriter) SetMembers(ctx context.Context, enterpriseID string, members []groupsync.Member) error

SetMembers creates and suspends enterprise users given the desired members.

type GitHubData 

type GitHubData struct {
	// contains filtered or unexported fields
}

type Opt 

type Opt func(writer *Config)

func WithCacheDuration 

func WithCacheDuration(duration time.Duration) Opt

WithCacheDuration set the time to live for the user and team cache entries.

func WithInviteToOrgIfNotAMember 

func WithInviteToOrgIfNotAMember() Opt

WithInviteToOrgIfNotAMember toggles sending an invitation to the user if they are not a member of the org being synced to. If the TeamReadWriter is trying to add a user to a team, it will first check if they are a member of the org the team belongs. If the user does not belong to the org, then the TeamReadWriter will send an invitation to add the user to the org and the team.

func WithoutSubTeamsAsMembers 

func WithoutSubTeamsAsMembers() Opt

WithoutSubTeamsAsMembers toggles off treating subteams as members of their parent team. When this option is used TeamReadWriter.GetMembers will only return user members of the team. Similarly, TeamReadWriter.SetMembers will only consider user members when setting members.

type OrgMembershipReadWriter 

type OrgMembershipReadWriter struct {
	// contains filtered or unexported fields
}

OrgMembershipReadWriter adheres to the groupsync.GroupReadWriter interface and provides mechanisms for manipulating GitHub org memberships.

func NewOrgMembershipReadWriter 

func NewOrgMembershipReadWriter(orgTokenSource OrgTokenSource, client *github.Client, opts ...OrgRWOpt) *OrgMembershipReadWriter

NewOrgMembershipReadWriter creates a new OrgMembershipReadWriter.

func (*OrgMembershipReadWriter) Descendants 

func (rw *OrgMembershipReadWriter) Descendants(ctx context.Context, orgID string) ([]*groupsync.User, error)

Descendants retrieve all users of the GitHub org with the given ID.

func (*OrgMembershipReadWriter) GetGroup 

func (rw *OrgMembershipReadWriter) GetGroup(ctx context.Context, orgID string) (*groupsync.Group, error)

GetGroup retrieves the GitHub org with the given ID.

func (*OrgMembershipReadWriter) GetMembers 

func (rw *OrgMembershipReadWriter) GetMembers(ctx context.Context, orgID string) ([]groupsync.Member, error)

GetMembers retrieves the members of the GitHub org with given ID.

func (*OrgMembershipReadWriter) GetUser 

func (rw *OrgMembershipReadWriter) GetUser(ctx context.Context, userID string) (*groupsync.User, error)

GetUser retrieves the GitHub user with the given ID. The ID is the GitHub user's login.

func (*OrgMembershipReadWriter) SetMembers 

func (rw *OrgMembershipReadWriter) SetMembers(ctx context.Context, orgID string, members []groupsync.Member) error

SetMembers replaces the members of the GitHub org with the given ID with the given members. Any members of the GitHub org not found in the given members list will be removed. Likewise, any members of the given list that are not currently members of the org will be added.

type OrgRWConfig 

type OrgRWConfig struct {
	// contains filtered or unexported fields
}

type OrgRWOpt 

type OrgRWOpt func(writer *OrgRWConfig)

OrgRWOpt is a configuration option for OrgMembershipReadWriter.

func WithInvitations 

func WithInvitations(value bool) OrgRWOpt

WithInvitations toggles using the APIs for Invitations in GitHub. GHES does not have invitations APIs so this option is required for GHES.

func WithOrgCacheDuration 

func WithOrgCacheDuration(duration time.Duration) OrgRWOpt

WithOrgCacheDuration sets the time to live for the user and org cache entries.

type OrgTokenSource 

type OrgTokenSource interface {
	// TokenForOrg returns a token that grants access to the given Org's resources.
	TokenForOrg(ctx context.Context, orgID int64) (string, error)
}

type Role 

type Role string
const (
	Member          Role = "member"
	Admin           Role = "admin"
	RoleUnspecified Role = Member
)

func (Role) InviteString 

func (r Role) InviteString() string

InviteString gives the string for the role used by the GitHub APIs for Invitations. The only difference is that "direct_member" is used instead of "member" for Invitations.

func (Role) String 

func (r Role) String() string

String gives the string for the role used by GitHub APIs.

type RoleMetadata 

type RoleMetadata struct {
	Role Role
}

RoleMetadata holds a role for a github user being added to a target org.

func (*RoleMetadata) Combine 

func (m *RoleMetadata) Combine(other groupsync.MappingMetadata) groupsync.MappingMetadata

Combine calculates the role for a github user being added to a target org by taking the maximum role granted to the user via a mapping from a source group.

type SCIMClient 

type SCIMClient struct {
	// contains filtered or unexported fields
}

SCIMClient handles direct HTTP communication with the GHES SCIM API. API doc: https://docs.github.com/en/enterprise-server@3.17/admin/managing-iam/provisioning-user-accounts-with-scim/provisioning-users-and-groups-with-scim-using-the-rest-api#provisioning-users-with-the-rest-api

func NewSCIMClient 

func NewSCIMClient(httpClient *http.Client, baseURL string) (*SCIMClient, error)

NewSCIMClient creates a new client for the GHES SCIM API.

func (*SCIMClient) CreateUser 

func (c *SCIMClient) CreateUser(ctx context.Context, user *SCIMUser) (*SCIMUser, *github.Response, error)

CreateUser provisions a new user.

func (*SCIMClient) DeactivateUser 

func (c *SCIMClient) DeactivateUser(ctx context.Context, scimID string) (*SCIMUser, *github.Response, error)

DeactivateUser deactivates a user. https://docs.github.com/en/enterprise-server@3.17/admin/managing-iam/provisioning-user-accounts-with-scim/provisioning-users-and-groups-with-scim-using-the-rest-api#soft-deprovisioning-users-with-the-rest-api

func (*SCIMClient) DeleteUser 

func (c *SCIMClient) DeleteUser(ctx context.Context, scimID string) (*github.Response, error)

DeleteUser deactivates a user. https://docs.github.com/en/enterprise-server@3.17/admin/managing-iam/provisioning-user-accounts-with-scim/provisioning-users-and-groups-with-scim-using-the-rest-api#hard-deprovisioning-users-with-the-rest-api

func (*SCIMClient) GetUser 

func (c *SCIMClient) GetUser(ctx context.Context, scimID string) (*SCIMUser, *github.Response, error)

GetUser gets a SCIM provisioned user by their SCIM ID.

func (*SCIMClient) ListUsers 

func (c *SCIMClient) ListUsers(ctx context.Context) (map[string]*SCIMUser, error)

ListUsers fetches all SCIM provisioned users from the enterprise, handling SCIM pagination.

func (*SCIMClient) ReactivateUser 

func (c *SCIMClient) ReactivateUser(ctx context.Context, scimID string) (*SCIMUser, *github.Response, error)

ReactivateUser reinstating a suspended user. https://docs.github.com/en/enterprise-server@3.17/admin/managing-iam/provisioning-user-accounts-with-scim/deprovisioning-and-reinstating-users#reinstating-a-user-account-that-was-soft-deprovisioned

func (*SCIMClient) UpdateUser 

func (c *SCIMClient) UpdateUser(ctx context.Context, scimID string, user *SCIMUser) (*SCIMUser, *github.Response, error)

UpdateUser updates a user's attributes.

type SCIMProvisionedIdentities 

type SCIMProvisionedIdentities struct {
	Schemas      []string    `json:"schemas,omitempty"`
	TotalResults *int        `json:"totalResults,omitempty"`
	ItemsPerPage *int        `json:"itemsPerPage,omitempty"`
	StartIndex   *int        `json:"startIndex,omitempty"`
	Resources    []*SCIMUser `json:"Resources,omitempty"`
}

SCIMProvisionedIdentities represents the result of calling ListSCIMProvisionedIdentities. This is a copy/paste of the upstream SCIMProvisionedIdentities struct, with the Resources field typed as *SCIMUser instead of *SCIMUserAttributes. Temporary pending https://github.com/google/go-github/pull/3728.

type SCIMUser 

type SCIMUser struct {
	github.SCIMUserAttributes
	Roles []*SCIMUserRole `json:"roles,omitempty"`
}

SCIMUser is a wrapper around the upstream SCIMUserAttributes struct that includes roles. Temporary pending https://github.com/google/go-github/pull/3728.

type SCIMUserRole 

type SCIMUserRole struct {
	Value   string  `json:"value"`             // (Required.)
	Display *string `json:"display,omitempty"` // (Optional.)
	Type    *string `json:"type,omitempty"`    // (Optional.)
	Primary *bool   `json:"primary,omitempty"` // (Optional.)
}

SCIMUserRole is an enterprise-wide role granted to the user. This is only supported in GitHub Enterprise Server, and not GitHub Enterprise Cloud. See the docs for allowed role names.

https://docs.github.com/en/enterprise-server@latest/rest/enterprise-admin/scim?apiVersion=2022-11-28#provision-a-scim-enterprise-user

type StaticTokenSource 

type StaticTokenSource struct {
	// contains filtered or unexported fields
}

StaticTokenSource implements OrgTokenSource.

func NewStaticTokenSourceFromEnvVar 

func NewStaticTokenSourceFromEnvVar(envVarName string) (*StaticTokenSource, error)

NewStaticTokenSourceFromEnvVar creates a StaticTokenSource using token read from EnvVar.

func (*StaticTokenSource) GetStaticToken 

func (s *StaticTokenSource) GetStaticToken() string

func (*StaticTokenSource) TokenForOrg 

func (s *StaticTokenSource) TokenForOrg(ctx context.Context, orgID int64) (string, error)

type TeamReadWriter 

type TeamReadWriter struct {
	// contains filtered or unexported fields
}

TeamReadWriter adheres to the groupsync.GroupReadWriter interface and provides mechanisms for manipulating GitHub Teams.

func NewTeamReadWriter 

func NewTeamReadWriter(orgTokenSource OrgTokenSource, client *github.Client, endpoint string, orgTeamSSORequired map[int64]map[int64]bool, opts ...Opt) *TeamReadWriter

NewTeamReadWriter creates a new TeamReadWriter. By default, TeamReadWriter considers subteams as members of their parent team and will treat them as such when executing calls to TeamReadWriter.GetMembers and TeamReadWriter.SetMembers. This behavior can be disabled by supply the WithoutSubTeamsAsMembers option, in which case only users will be considered as members of a team. By default, TeamReadWriter does not attempt to add users to an org if they are not already members. This can be enabled by WithInviteToOrgIfNotAMember option. OrgTeamSSORequired will be used to verify if a team requires user to have sso enabled to sync memberships. If orgTeamSSORequired[org][team] is not found, we will default the value to false.

func NewTeamReadWriterWithStaticTokenSource 

func NewTeamReadWriterWithStaticTokenSource(ctx context.Context, s *StaticTokenSource, endpoint string, orgTeamSSORequired map[int64]map[int64]bool) (*TeamReadWriter, error)

NewTeamReadWriterWithStaticTokenSource creates a team readwriter using provided endpoint and static token source.

func (*TeamReadWriter) Descendants 

func (g *TeamReadWriter) Descendants(ctx context.Context, groupID string) ([]*groupsync.User, error)

Descendants retrieve all users (children, recursively) of the GitHub team with the given ID. The ID must be of the form 'orgID:teamID'.

func (*TeamReadWriter) GetGitHubOrgSAML 

func (g *TeamReadWriter) GetGitHubOrgSAML(ctx context.Context, orgID int64) (map[string]struct{}, error)

GetGitHubOrgSAML gets the SAML identities for the github org. If the SAML for the given orgID is expired in cache or does not exisit, it will retrieve the newest SAML identitiy information.

func (*TeamReadWriter) GetGroup 

func (g *TeamReadWriter) GetGroup(ctx context.Context, groupID string) (*groupsync.Group, error)

GetGroup retrieves the GitHub team with the given ID. The ID must be of the form 'orgID:teamID'.

func (*TeamReadWriter) GetMembers 

func (g *TeamReadWriter) GetMembers(ctx context.Context, groupID string) ([]groupsync.Member, error)

GetMembers retrieves the direct members (children) of the GitHub team with given ID. The ID must be of the form 'orgID:teamID'.

func (*TeamReadWriter) GetUser 

func (g *TeamReadWriter) GetUser(ctx context.Context, userID string) (*groupsync.User, error)

GetUser retrieves the GitHub user with the given ID. The ID is the GitHub user's login.

func (*TeamReadWriter) SetMembers 

func (g *TeamReadWriter) SetMembers(ctx context.Context, groupID string, members []groupsync.Member) error

SetMembers replaces the members of the GitHub team with the given ID with the given members. The ID must be of the form 'orgID:teamID'. Any members of the GitHub team not found in the given members list will be removed. Likewise, any members of the given list that are not currently members of the team will be added.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.