github

package
v1.1.3 Latest Latest
Warning

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

 Go to latest Published: Sep 22, 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 added in v1.0.0 

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 added in v1.0.0 

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 added in v1.0.0 

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 added in v1.0.0 

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 added in v1.0.3 

func NewAppKeySignerProvider(kp credentials.KeyProvider) credentials.SignerProvider

NewAppKeySignerProvider creates a signer provider with the given key provider.

func NewRoleMetadata added in v1.0.0 

func NewRoleMetadata(roleStr string) groupsync.MappingMetadata

Types

type AppKeySignerProvider added in v1.0.0 

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

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

func (*AppKeySignerProvider) Signer added in v1.0.0 

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 added in v1.1.0 

type EnterpriseRWOpt func(rw *EnterpriseUserWriter)

ENterpriseRWOpt is a configuration option for EnterpriseUserReadWriter.

func WithMaxUsersToProvision added in v1.1.0 

func WithMaxUsersToProvision(num int64) EnterpriseRWOpt

WithMaxUsersToProvision sets the maximum number of SCIM provisioned users.

type EnterpriseUserWriter added in v1.1.0 

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

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

func NewEnterpriseUserWriter added in v1.1.0 

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 added in v1.1.0 

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

SetMembers creates and suspends enterprise users given the desired members.

type GitHubData added in v1.0.0 

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 added in v1.0.0 

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 added in v1.0.0 

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

NewOrgMembershipReadWriter creates a new OrgMembershipReadWriter.

func (*OrgMembershipReadWriter) Descendants added in v1.0.0 

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 added in v1.0.0 

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

GetGroup retrieves the GitHub org with the given ID.

func (*OrgMembershipReadWriter) GetMembers added in v1.0.0 

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 added in v1.0.0 

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 added in v1.0.0 

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 added in v1.0.0 

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

type OrgRWOpt added in v1.0.0 

type OrgRWOpt func(writer *OrgRWConfig)

OrgRWOpt is a configuration option for OrgMembershipReadWriter.

func WithInvitations added in v1.0.1 

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 added in v1.0.0 

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 added in v1.0.0 

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

func (Role) InviteString added in v1.0.0 

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 added in v1.0.0 

func (r Role) String() string

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

type RoleMetadata added in v1.0.0 

type RoleMetadata struct {
	Role Role
}

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

func (*RoleMetadata) Combine added in v1.0.0 

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 added in v1.1.0 

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 added in v1.1.0 

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

NewSCIMClient creates a new client for the GHES SCIM API.

func (*SCIMClient) CreateUser added in v1.1.0 

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

CreateUser provisions a new user.

func (*SCIMClient) DeactivateUser added in v1.1.0 

func (c *SCIMClient) DeactivateUser(ctx context.Context, scimID string) (*github.SCIMUserAttributes, *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 added in v1.1.0 

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 added in v1.1.0 

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

GetUser gets a SCIM provisioned user by their SCIM ID.

func (*SCIMClient) ListUsers added in v1.1.0 

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

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

func (*SCIMClient) ReactivateUser added in v1.1.0 

func (c *SCIMClient) ReactivateUser(ctx context.Context, scimID string) (*github.SCIMUserAttributes, *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 added in v1.1.0 

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

UpdateUser updates a user's attributes.

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 added in v1.0.0 

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.