gitprovider

package
v0.0.8 Latest Latest
Warning

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

 Go to latest Published: Sep 24, 2020 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// TransportTypeHTTPS specifies a clone URL of the form:
	// https://<domain>/<org>/[<sub-orgs...>/]<repo>.git
	TransportTypeHTTPS = TransportType("https")
	// TransportTypeGit specifies a clone URL of the form:
	// git@<domain>:<org>/[<sub-orgs...>/]<repo>.git
	TransportTypeGit = TransportType("git")
	// TransportTypeSSH specifies a clone URL of the form:
	// ssh://git@<domain>/<org>/[<sub-orgs...>/]<repo>
	TransportTypeSSH = TransportType("ssh")
)
View Source 
const (
	// RepositoryVisibilityPublic specifies that the repository should be publicly accessible.
	RepositoryVisibilityPublic = RepositoryVisibility("public")
	// RepositoryVisibilityInternal specifies that the repository should accessible within the
	// own organization.
	RepositoryVisibilityInternal = RepositoryVisibility("internal")
	// RepositoryVisibilityPrivate specifies that the repository should only be accessible by
	// specifically added team members.
	RepositoryVisibilityPrivate = RepositoryVisibility("private")
)
View Source 
const (
	// RepositoryPermissionPull ("pull") - team members can pull, but not push to or administer this repository
	// This is called "guest" in GitLab.
	RepositoryPermissionPull = RepositoryPermission("pull")

	// RepositoryPermissionTriage ("triage") - team members can proactively manage issues and pull requests without write access.
	// This is called "reporter" in GitLab.
	RepositoryPermissionTriage = RepositoryPermission("triage")

	// RepositoryPermissionPush ("push") - team members can pull and push, but not administer this repository
	// This is called "developer" in GitLab.
	RepositoryPermissionPush = RepositoryPermission("push")

	// RepositoryPermissionMaintain ("maintain") - team members can manage the repository without access to sensitive or destructive actions.
	// This is called "maintainer" in GitLab.
	RepositoryPermissionMaintain = RepositoryPermission("maintain")

	// RepositoryPermissionAdmin ("admin") - team members can pull, push and administer this repository
	// This is called "admin" or "owner" in GitLab.
	RepositoryPermissionAdmin = RepositoryPermission("admin")
)
View Source 
const (
	// LicenseTemplateApache2 specifies use of the Apache 2.0 license, see
	// https://choosealicense.com/licenses/apache-2.0/
	LicenseTemplateApache2 = LicenseTemplate("apache-2.0")
	// LicenseTemplateMIT specifies use of the MIT license, see
	// https://choosealicense.com/licenses/mit/
	LicenseTemplateMIT = LicenseTemplate("mit")
	// LicenseTemplateGPL3 specifies use of the GNU General Public License v3.0, see
	// https://choosealicense.com/licenses/gpl-3.0/
	LicenseTemplateGPL3 = LicenseTemplate("gpl-3.0")
)
View Source 
const (
	// IdentityTypeUser represents an identity for a user account.
	IdentityTypeUser = IdentityType("user")
	// IdentityTypeOrganization represents an identity for an organization.
	IdentityTypeOrganization = IdentityType("organization")
	// IdentityTypeSuborganization represents an identity for a sub-organization.
	IdentityTypeSuborganization = IdentityType("suborganization")
)

Variables

View Source 
var (
	// ErrNoProviderSupport describes that the provider doesn't support the requested feature.
	ErrNoProviderSupport = errors.New("no provider support for this feature")
	// ErrDomainUnsupported describes the case where e.g. a GitHub provider used for trying to get
	// information from e.g. "gitlab.com".
	ErrDomainUnsupported = errors.New("the client doesn't support handling requests for this domain")

	// ErrNotTopLevelOrganization describes the case where it's mandatory to specify a top-level organization
	// (e.g. to access teams), but a sub-organization was passed as the OrganizationRef.
	ErrNotTopLevelOrganization = errors.New("expected top-level organization, received sub-organization instead")
	// ErrInvalidArgument describes a generic error where an invalid argument have been specified to a function.
	ErrInvalidArgument = errors.New("invalid argument specified")
	// ErrUnexpectedEvent describes a case where something really unexpected happened in the program.
	ErrUnexpectedEvent = errors.New("an unexpected error occurred")

	// ErrAlreadyExists is returned by .Create() requests if the given resource already exists.
	// Use .Reconcile() instead if you want to idempotently create the resource.
	ErrAlreadyExists = errors.New("resource already exists, cannot create object. Use Reconcile() to create it idempotently")
	// ErrNotFound is returned by .Get() and .Update() calls if the given resource doesn't exist.
	ErrNotFound = errors.New("the requested resource was not found")
	// ErrInvalidServerData is returned when the server returned invalid data, e.g. missing required fields in the response.
	ErrInvalidServerData = errors.New("got invalid data from server, don't know how to handle")

	// ErrURLUnsupportedScheme is returned if an URL without the HTTPS scheme is parsed.
	ErrURLUnsupportedScheme = errors.New("unsupported URL scheme, only HTTPS supported")
	// ErrURLUnsupportedParts is returned if an URL with fragment, query values and/or user information is parsed.
	ErrURLUnsupportedParts = errors.New("URL cannot have fragments, query values nor user information")
	// ErrURLInvalid is returned if an URL is invalid when parsing.
	ErrURLInvalid = errors.New("invalid organization, user or repository URL")
	// ErrURLMissingRepoName is returned if there is no repository name in the URL.
	ErrURLMissingRepoName = errors.New("missing repository name")

	// ErrInvalidClientOptions is the error returned when calling NewClient() with
	// invalid options (e.g. specifying mutually exclusive options).
	ErrInvalidClientOptions = errors.New("invalid options given to NewClient()")
	// ErrDestructiveCallDisallowed happens when the client isn't set up with WithDestructiveAPICalls()
	// but a destructive action is called.
	ErrDestructiveCallDisallowed = errors.New("destructive call was blocked, disallowed by client")
	// ErrInvalidTransportChainReturn is returned if a ChainableRoundTripperFunc returns nil, which is invalid.
	ErrInvalidTransportChainReturn = errors.New("the return value of a ChainableRoundTripperFunc must not be nil")

	// ErrInvalidPermissionLevel is the error returned when there is no mapping
	// from the given level to the gitprovider levels.
	ErrInvalidPermissionLevel = errors.New("invalid permission level")
)

Functions

func BoolVar 

func BoolVar(b bool) *bool

BoolVar returns a pointer to the given bool.

func BuildClientFromTransportChain 

func BuildClientFromTransportChain(chain []ChainableRoundTripperFunc) (*http.Client, error)

BuildClientFromTransportChain builds a *http.Client from a chain of ChainableRoundTripperFuncs. The first function in the chain is called with "in" == nil. "out" of the first function in the chain, is passed as "in" to the second function, and so on. "out" of the last function in the chain is used as net/http Client.Transport.

func GetCloneURL 

func GetCloneURL(rs RepositoryRef, transport TransportType) string

GetCloneURL returns the URL to clone a repository for a given transport type. If the given TransportType isn't known an empty string is returned.

func StringVar 

func StringVar(s string) *string

StringVar returns a pointer to the given string.

func ValidateAndDefaultInfo 

func ValidateAndDefaultInfo(info DefaultedInfoRequest) error

ValidateAndDefaultInfo can be used in client Create() and Reconcile() functions, where the request object, which implements InfoRequest, shall be first validated, and then defaulted. Defaulting happens at Create(), because we want to consistently apply this library's defaults across providers. Defaulting also happens at Reconcile(), because as the object has been created with defaults, the actual state fetched from the server will contain those defaults, and would result in a diff between the (possibly non-defaulted) request and actual state. TODO: Unit and integration test this. TODO: Document in Create() and Reconcile() that req is modified (?) and should not be used anymore.

func ValidateLicenseTemplate 

func ValidateLicenseTemplate(t LicenseTemplate) error

ValidateLicenseTemplate validates a given LicenseTemplate. Use as errs.Append(ValidateLicenseTemplate(template), template, "FieldName").

func ValidateRepositoryPermission 

func ValidateRepositoryPermission(p RepositoryPermission) error

ValidateRepositoryPermission validates a given RepositoryPermission. Use as errs.Append(ValidateRepositoryPermission(permission), permission, "FieldName").

func ValidateRepositoryVisibility 

func ValidateRepositoryVisibility(r RepositoryVisibility) error

ValidateRepositoryVisibility validates a given RepositoryVisibility. Use as errs.Append(ValidateRepositoryVisibility(visibility), visibility, "FieldName").

Types

type ChainableRoundTripperFunc 

type ChainableRoundTripperFunc func(in http.RoundTripper) (out http.RoundTripper)

ChainableRoundTripperFunc is a function that returns a higher-level "out" RoundTripper, chained to call the "in" RoundTripper internally, with extra logic. This function must be able to handle "in" being nil, and use the http.DefaultTransport default RoundTripper in that case. "out" must never be nil.

type Client 

type Client interface {
	// The Client allows accessing all known resources.
	ResourceClient

	// SupportedDomain returns the domain endpoint for this client, e.g. "github.com", "gitlab.com" or
	// "my-custom-git-server.com:6443". This allows a higher-level user to know what Client to use for
	// what endpoints.
	// This field is set at client creation time, and can't be changed.
	SupportedDomain() string

	// ProviderID returns the provider ID (e.g. "github", "gitlab") for this client.
	// This field is set at client creation time, and can't be changed.
	ProviderID() ProviderID

	// Raw returns the Go client used under the hood to access the Git provider.
	Raw() interface{}
}

Client is an interface that allows talking to a Git provider.

type CommonClientOptions 

type CommonClientOptions struct {
	// Domain specifies the target domain for the client. If unset, the default domain for the
	// given provider will be used (often exposed as DefaultDomain in respective package).
	// The behaviour when setting this flag might vary between providers, read the documentation on
	// NewClient for more information.
	Domain *string

	// EnableDestructiveAPICalls is a flag specifying whether destructive API calls (like
	// deleting a repository) are allowed in the Client. Default: false
	EnableDestructiveAPICalls *bool

	// PreChainRoundTripper is a function to get a custom RoundTripper that is given as the Transport
	// to the *http.Client given to the provider-specific Client. It can be set for doing arbitrary
	// modifications to HTTP requests. "in" might be nil, if so http.DefaultTransport is recommended.
	// The "chain" looks like follows:
	// Git provider API <-> "Post Chain" <-> Provider Specific (e.g. auth, caching) (in) <-> "Pre Chain" (out) <-> *http.Client
	PreChainTransportHook ChainableRoundTripperFunc

	// PostChainTransportHook is a function to get a custom RoundTripper that is the "final" Transport
	// in the chain before talking to the backing API. It can be set for doing arbitrary
	// modifications to HTTP requests. "in" is always nil. It's recommended to internally use http.DefaultTransport.
	// The "chain" looks like follows:
	// Git provider API (in==nil) <-> "Post Chain" (out) <-> Provider Specific (e.g. auth, caching) <-> "Pre Chain" <-> *http.Client
	PostChainTransportHook ChainableRoundTripperFunc
}

CommonClientOptions is a struct containing options that are generic to all clients.

func (*CommonClientOptions) ApplyToCommonClientOptions 

func (opts *CommonClientOptions) ApplyToCommonClientOptions(target *CommonClientOptions) error

ApplyToCommonClientOptions applies the currently set fields in opts to target. If both opts and target has the same specific field set, ErrInvalidClientOptions is returned.

type DefaultedInfoRequest 

type DefaultedInfoRequest interface {
	// DefaultedInfoRequest is a superset of InfoRequest
	InfoRequest

	// Default will be run after validation, setting optional pointer fields to their
	// default values before doing the POST request. This function MUST be registered with
	// the base struct as a pointer receiver.
	Default()
}

DefaultedInfoRequest is a superset of InfoRequest, also including a Default() function that can modify the underlying object, adding default values. ValidateAndDefaultInfo() can be used to first validate, and then default.

type Deletable 

type Deletable interface {
	// Delete deletes the current resource irreversibly.
	//
	// ErrNotFound is returned if the resource doesn't exist anymore.
	Delete(ctx context.Context) error
}

Deletable is an interface which all objects that can be deleted using the Client implement.

type DeployKey 

type DeployKey interface {
	// DeployKey implements the Object interface,
	// allowing access to the underlying object returned from the API.
	Object
	// The deploy key can be updated.
	Updatable
	// The deploy key can be reconciled.
	Reconcilable
	// The deploy key can be deleted.
	Deletable
	// RepositoryBound returns repository reference details.
	RepositoryBound

	// Get returns high-level information about this deploy key.
	Get() DeployKeyInfo
	// Set sets high-level desired state for this deploy key. In order to apply these changes in
	// the Git provider, run .Update() or .Reconcile().
	Set(DeployKeyInfo) error
}

DeployKey represents a short-lived credential (e.g. an SSH public key) used to access a repository.

type DeployKeyClient 

type DeployKeyClient interface {
	// Get a DeployKey by its name.
	//
	// ErrNotFound is returned if the resource does not exist.
	Get(ctx context.Context, name string) (DeployKey, error)

	// List all deploy keys for the given repository.
	//
	// List returns all available deploy keys for the given type,
	// using multiple paginated requests if needed.
	List(ctx context.Context) ([]DeployKey, error)

	// Create a deploy key with the given specifications.
	//
	// ErrAlreadyExists will be returned if the resource already exists.
	Create(ctx context.Context, req DeployKeyInfo) (DeployKey, error)

	// Reconcile makes sure the given desired state (req) becomes the actual state in the backing Git provider.
	//
	// If req doesn't exist under the hood, it is created (actionTaken == true).
	// If req doesn't equal the actual state, the resource will be updated (actionTaken == true).
	// If req is already the actual state, this is a no-op (actionTaken == false).
	Reconcile(ctx context.Context, req DeployKeyInfo) (resp DeployKey, actionTaken bool, err error)
}

DeployKeyClient operates on the access credential list for a specific repository. This client can be accessed through Repository.DeployKeys().

type DeployKeyInfo 

type DeployKeyInfo struct {
	// Name is the human-friendly interpretation of what the key is for (and does).
	// +required
	Name string `json:"name"`

	// Key specifies the public part of the deploy (e.g. SSH) key.
	// +required
	Key []byte `json:"key"`

	// ReadOnly specifies whether this DeployKey can write to the repository or not.
	// Default value at POST-time: true.
	// +optional
	ReadOnly *bool `json:"readOnly,omitempty"`
}

DeployKeyInfo contains high-level information about a deploy key.

func (*DeployKeyInfo) Default 

func (dk *DeployKeyInfo) Default()

Default defaults the DeployKey fields.

func (DeployKeyInfo) Equals 

func (dk DeployKeyInfo) Equals(actual InfoRequest) bool

Equals can be used to check if this *Info request (the desired state) matches the actual passed in as the argument.

func (DeployKeyInfo) ValidateInfo 

func (dk DeployKeyInfo) ValidateInfo() error

ValidateInfo validates the object at {Object}.Set() and POST-time.

type HTTPError 

type HTTPError struct {
	// HTTP response that caused this error.
	Response *http.Response `json:"-"`
	// Full error message, human-friendly and formatted.
	ErrorMessage string `json:"errorMessage"`
	// Message about what happened.
	Message string `json:"message"`
	// Where to find more information about the error.
	DocumentationURL string `json:"documentationURL"`
}

HTTPError is an error that contains context about the HTTP request/response that failed.

func (*HTTPError) Error 

func (e *HTTPError) Error() string

Error implements the error interface.

type IdentityRef 

type IdentityRef interface {
	// IdentityRef implements ValidateTarget so it can easily be validated as a field.
	validation.ValidateTarget

	// GetDomain returns the URL-domain for the Git provider backend,
	// e.g. "github.com" or "self-hosted-gitlab.com:6443".
	GetDomain() string

	// GetIdentity returns the user account name or a slash-separated path of the
	// <organization-name>[/<sub-organization-name>...] form. This can be used as
	// an identifier for this specific actor in the system.
	GetIdentity() string

	// GetType returns what type of identity this instance represents. If IdentityTypeUser is returned
	// this IdentityRef can safely be casted to an UserRef. If any of IdentityTypeOrganization or
	// IdentityTypeSuborganization are returned, this IdentityRef can be casted to a OrganizationRef.
	GetType() IdentityType

	// String returns the HTTPS URL, and implements fmt.Stringer.
	String() string
}

IdentityRef references an organization or user account in a Git provider.

type IdentityType 

type IdentityType string

IdentityType is a typed string for what kind of identity type an IdentityRef is.

type InfoRequest 

type InfoRequest interface {
	// ValidateInfo validates the object at {Object}.Set() and POST-time, before defaulting.
	// Set (non-nil) and required fields should be validated.
	ValidateInfo() error

	// Equals can be used to check if this *Info request (the desired state) matches the actual
	// passed in as the argument.
	Equals(actual InfoRequest) bool
}

InfoRequest is an interface which all {Object}Info objects that can be used as Create() or Reconcile() requests in the Client should implement. Most likely, the struct should also implement DefaultedInfoRequest, as most objects have optional, defaulted fields.

type InvalidCredentialsError 

type InvalidCredentialsError struct {
	// InvalidCredentialsError extends HTTPError.
	HTTPError `json:",inline"`
}

InvalidCredentialsError describes that that the request login credentials (e.g. an Oauth2 token) was invalid (i.e. a 401 Unauthorized or 403 Forbidden status was returned). This does NOT mean that "the login was successful but you don't have permission to access this resource". In that case, a 404 Not Found error would be returned.

type LicenseTemplate 

type LicenseTemplate string

LicenseTemplate is an enum specifying a license template that can be used when creating a repository. Examples of available licenses are here: https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/licensing-a-repository#searching-github-by-license-type

func LicenseTemplateVar 

func LicenseTemplateVar(t LicenseTemplate) *LicenseTemplate

LicenseTemplateVar returns a pointer to a LicenseTemplate.

type Object 

type Object interface {
	// APIObject returns the underlying value that was returned from the server.
	// This is always a pointer to a struct.
	APIObject() interface{}
}

Object is the interface all types should implement.

type OrgRepositoriesClient 

type OrgRepositoriesClient interface {
	// Get returns the repository for the given reference.
	//
	// ErrNotFound is returned if the resource does not exist.
	Get(ctx context.Context, r OrgRepositoryRef) (OrgRepository, error)

	// List all repositories in the given organization.
	//
	// List returns all available repositories, using multiple paginated requests if needed.
	List(ctx context.Context, o OrganizationRef) ([]OrgRepository, error)

	// Create creates a repository for the given organization, with the data and options.
	//
	// ErrAlreadyExists will be returned if the resource already exists.
	Create(ctx context.Context, r OrgRepositoryRef, req RepositoryInfo, opts ...RepositoryCreateOption) (OrgRepository, error)

	// Reconcile makes sure the given desired state (req) becomes the actual state in the backing Git provider.
	//
	// If req doesn't exist under the hood, it is created (actionTaken == true).
	// If req doesn't equal the actual state, the resource will be updated (actionTaken == true).
	// If req is already the actual state, this is a no-op (actionTaken == false).
	Reconcile(ctx context.Context, r OrgRepositoryRef, req RepositoryInfo, opts ...RepositoryReconcileOption) (resp OrgRepository, actionTaken bool, err error)
}

OrgRepositoriesClient operates on repositories for organizations.

type OrgRepository 

type OrgRepository interface {
	// OrgRepository is a superset of UserRepository.
	UserRepository

	// TeamAccess returns a TeamsAccessClient for operating on teams' access to this specific repository.
	TeamAccess() TeamAccessClient
}

OrgRepository describes a repository owned by an organization.

type OrgRepositoryRef 

type OrgRepositoryRef struct {
	// OrgRepositoryRef embeds OrganizationRef inline.
	OrganizationRef `json:",inline"`

	// RepositoryName specifies the Git repository name. This field is URL-friendly,
	// e.g. "kubernetes" or "cluster-api-provider-aws".
	// +required
	RepositoryName string `json:"repositoryName"`
}

OrgRepositoryRef is a struct with information about a specific repository owned by an organization.

func ParseOrgRepositoryURL 

func ParseOrgRepositoryURL(r string) (*OrgRepositoryRef, error)

ParseOrgRepositoryURL parses a HTTPS clone URL into a OrgRepositoryRef object.

func (OrgRepositoryRef) GetCloneURL 

func (r OrgRepositoryRef) GetCloneURL(transport TransportType) string

GetCloneURL gets the clone URL for the specified transport type.

func (OrgRepositoryRef) GetRepository 

func (r OrgRepositoryRef) GetRepository() string

GetRepository returns the repository name for this repo.

func (OrgRepositoryRef) String 

func (r OrgRepositoryRef) String() string

String returns the HTTPS URL to access the repository.

func (OrgRepositoryRef) ValidateFields 

func (r OrgRepositoryRef) ValidateFields(validator validation.Validator)

ValidateFields validates its own fields for a given validator.

type Organization 

type Organization interface {
	// Organization implements the Object interface,
	// allowing access to the underlying object returned from the API.
	Object
	// OrganizationBound returns organization reference details.
	OrganizationBound

	// Get returns high-level information about the organization.
	Get() OrganizationInfo

	// Teams gives access to the TeamsClient for this specific organization
	Teams() TeamsClient
}

Organization represents an organization in a Git provider. For now, the organization is read-only, i.e. there aren't set/update methods.

type OrganizationBound 

type OrganizationBound interface {
	// Organization returns the OrganizationRef associated with this object.
	Organization() OrganizationRef
}

OrganizationBound describes an object that is bound to a given organization, e.g. a team.

type OrganizationInfo 

type OrganizationInfo struct {
	// Name is the human-friendly name of this organization, e.g. "Flux" or "Kubernetes SIGs".
	Name *string `json:"name"`

	// Description returns a description for the organization.
	Description *string `json:"description"`
}

OrganizationInfo represents an (top-level- or sub-) organization.

type OrganizationRef 

type OrganizationRef struct {
	// Domain returns e.g. "github.com", "gitlab.com" or a custom domain like "self-hosted-gitlab.com" (GitLab)
	// The domain _might_ contain port information, in the form of "host:port", if applicable.
	// +required
	Domain string `json:"domain"`

	// Organization specifies the URL-friendly, lowercase name of the organization or user account name,
	// e.g. "fluxcd" or "kubernetes-sigs".
	// +required
	Organization string `json:"organization"`

	// SubOrganizations point to optional sub-organizations (or sub-groups) of the given top-level organization
	// in the Organization field. E.g. "gitlab.com/fluxcd/engineering/frontend" would yield ["engineering", "frontend"]
	// +optional
	SubOrganizations []string `json:"subOrganizations,omitempty"`
}

OrganizationRef is an implementation of OrganizationRef.

func ParseOrganizationURL 

func ParseOrganizationURL(o string) (*OrganizationRef, error)

ParseOrganizationURL parses an URL to an organization into a OrganizationRef object.

func (OrganizationRef) GetDomain 

func (o OrganizationRef) GetDomain() string

GetDomain returns the the domain part of the endpoint, can include port information.

func (OrganizationRef) GetIdentity 

func (o OrganizationRef) GetIdentity() string

GetIdentity returns the identity of this actor, which in this case is the user login name.

func (OrganizationRef) GetType 

func (o OrganizationRef) GetType() IdentityType

GetType marks this UserRef as being a IdentityTypeUser.

func (OrganizationRef) String 

func (o OrganizationRef) String() string

String returns the HTTPS URL to access the Organization.

func (OrganizationRef) ValidateFields 

func (o OrganizationRef) ValidateFields(validator validation.Validator)

ValidateFields validates its own fields for a given validator.

type OrganizationsClient 

type OrganizationsClient interface {
	// Get a specific organization the user has access to.
	// This might also refer to a sub-organization.
	//
	// ErrNotFound is returned if the resource does not exist.
	Get(ctx context.Context, o OrganizationRef) (Organization, error)

	// List all top-level organizations the specific user has access to.
	//
	// List returns all available organizations, using multiple paginated requests if needed.
	List(ctx context.Context) ([]Organization, error)

	// Children returns the immediate child-organizations for the specific OrganizationRef o.
	// The OrganizationRef may point to any existing sub-organization.
	//
	// This is not supported in GitHub.
	//
	// Children returns all available organizations, using multiple paginated requests if needed.
	Children(ctx context.Context, o OrganizationRef) ([]Organization, error)
}

OrganizationsClient operates on organizations the user has access to.

type ProviderID 

type ProviderID string

ProviderID is a typed string for a given Git provider The provider constants are defined in their respective packages.

type RateLimitError 

type RateLimitError struct {
	// RateLimitError extends HTTPError.
	HTTPError `json:",inline"`

	// The number of requests per hour the client is currently limited to.
	Limit int `json:"limit"`
	// The number of remaining requests the client can make this hour.
	Remaining int `json:"remaining"`
	// The timestamp at which point the current rate limit will reset.
	Reset time.Time `json:"reset"`
}

RateLimitError is an error, extending HTTPError, that contains context about rate limits.

type Reconcilable 

type Reconcilable interface {
	// Reconcile makes sure the desired state in this object (called "req" here) becomes
	// the actual state in the backing Git provider.
	//
	// If req doesn't exist under the hood, it is created (actionTaken == true).
	// If req doesn't equal the actual state, the resource will be updated (actionTaken == true).
	// If req is already the actual state, this is a no-op (actionTaken == false).
	//
	// The internal API object will be overridden with the received server data if actionTaken == true.
	Reconcile(ctx context.Context) (actionTaken bool, err error)
}

Reconcilable is an interface which all objects that can be reconciled using the Client implement.

type RepositoryBound 

type RepositoryBound interface {
	// Repository returns the RepositoryRef associated with this object.
	Repository() RepositoryRef
}

RepositoryBound describes an object that is bound to a given repository, e.g. a deploy key.

type RepositoryCreateOption 

type RepositoryCreateOption interface {
	// ApplyToRepositoryCreateOptions should apply relevant options to the target.
	ApplyToRepositoryCreateOptions(target *RepositoryCreateOptions)
}

RepositoryCreateOption is an interface for applying options to when creating repositories.

type RepositoryCreateOptions 

type RepositoryCreateOptions struct {
	// AutoInit can be set to true in order to automatically initialize the Git repo with a
	// README.md and optionally a license in the first commit.
	// Default: nil (which means "false, don't create")
	AutoInit *bool

	// LicenseTemplate lets the user specify a license template to use when AutoInit is true.
	// Default: nil.
	// Available options: See the LicenseTemplate enum.
	LicenseTemplate *LicenseTemplate
}

RepositoryCreateOptions specifies optional options when creating a repository.

func MakeRepositoryCreateOptions 

func MakeRepositoryCreateOptions(opts ...RepositoryCreateOption) (RepositoryCreateOptions, error)

MakeRepositoryCreateOptions returns a RepositoryCreateOptions based off the mutator functions given to e.g. RepositoriesClient.Create(). The returned validation error may be ignored in the case that the client allows e.g. other license templates than those that are common. validation.ErrFieldEnumInvalid is returned if the license template doesn't match known values.

func (*RepositoryCreateOptions) ApplyToRepositoryCreateOptions 

func (opts *RepositoryCreateOptions) ApplyToRepositoryCreateOptions(target *RepositoryCreateOptions)

ApplyToRepositoryCreateOptions applies the options defined in the options struct to the target struct that is being completed.

func (*RepositoryCreateOptions) ValidateOptions 

func (opts *RepositoryCreateOptions) ValidateOptions() error

ValidateInfo validates that the options are valid.

type RepositoryInfo 

type RepositoryInfo struct {
	// Description returns a description for the repository.
	// No default value at POST-time.
	// +optional
	Description *string `json:"description"`

	// DefaultBranch describes the default branch for the given repository. This has
	// historically been "master" (and is as of writing still the Git default), but is
	// expected to be changed to e.g. "main" shortly in the future.
	// Default value at POST-time: master (but this can and will change in future library versions!).
	// +optional
	DefaultBranch *string `json:"defaultBranch"`

	// Visibility returns the desired visibility for the repository.
	// Default value at POST-time: RepositoryVisibilityPrivate.
	// +optional
	Visibility *RepositoryVisibility `json:"visibility"`
}

RepositoryInfo represents a Git repository provided by a Git provider.

func (*RepositoryInfo) Default 

func (r *RepositoryInfo) Default()

Default defaults the Repository, implementing the InfoRequest interface.

func (RepositoryInfo) Equals 

func (r RepositoryInfo) Equals(actual InfoRequest) bool

Equals can be used to check if this *Info request (the desired state) matches the actual passed in as the argument.

func (RepositoryInfo) ValidateInfo 

func (r RepositoryInfo) ValidateInfo() error

ValidateInfo validates the object at {Object}.Set() and POST-time.

type RepositoryPermission 

type RepositoryPermission string

RepositoryPermission is an enum specifying the access level for a certain team or person for a given repository.

func RepositoryPermissionVar 

func RepositoryPermissionVar(p RepositoryPermission) *RepositoryPermission

RepositoryPermissionVar returns a pointer to a RepositoryPermission.

type RepositoryReconcileOption 

type RepositoryReconcileOption interface {
	// RepositoryCreateOption is embedded, as reconcile uses the create options.
	RepositoryCreateOption
}

RepositoryReconcileOption is an interface for applying options to when reconciling repositories.

type RepositoryRef 

type RepositoryRef interface {
	// RepositoryRef is a superset of IdentityRef.
	IdentityRef

	// GetRepository returns the repository name for this repo.
	GetRepository() string

	// GetCloneURL gets the clone URL for the specified transport type.
	GetCloneURL(transport TransportType) string
}

RepositoryRef describes a reference to a repository owned by either a user account or organization.

type RepositoryVisibility 

type RepositoryVisibility string

RepositoryVisibility is an enum specifying the visibility of a repository.

func RepositoryVisibilityVar 

func RepositoryVisibilityVar(r RepositoryVisibility) *RepositoryVisibility

RepositoryVisibilityVar returns a pointer to a RepositoryVisibility.

type ResourceClient 

type ResourceClient interface {
	// Organizations returns the OrganizationsClient handling sets of organizations.
	Organizations() OrganizationsClient

	// OrgRepositories returns the OrgRepositoriesClient handling sets of repositories in an organization.
	OrgRepositories() OrgRepositoriesClient

	// UserRepositories returns the UserRepositoriesClient handling sets of repositories for a user.
	UserRepositories() UserRepositoriesClient
}

ResourceClient allows access to resource-specific sub-clients.

type Team 

type Team interface {
	// Team implements the Object interface,
	// allowing access to the underlying object returned from the API.
	Object
	// OrganizationBound returns organization reference details.
	OrganizationBound

	// Get returns high-level information about this team.
	Get() TeamInfo
}

Team represents a team in an organization in a Git provider. For now, the team is read-only, i.e. there aren't set/update methods.

type TeamAccess 

type TeamAccess interface {
	// TeamAccess implements the Object interface,
	// allowing access to the underlying object returned from the API.
	Object
	// The deploy key can be updated.
	Updatable
	// The deploy key can be reconciled.
	Reconcilable
	// The deploy key can be deleted.
	Deletable
	// RepositoryBound returns repository reference details.
	RepositoryBound

	// Get returns high-level information about this team access for the repository.
	Get() TeamAccessInfo
	// Set sets high-level desired state for this team access object. In order to apply these changes in
	// the Git provider, run .Update() or .Reconcile().
	Set(TeamAccessInfo) error
}

TeamAccess describes a binding between a repository and a team.

type TeamAccessClient 

type TeamAccessClient interface {
	// Get a team's permission level of this given repository.
	//
	// ErrNotFound is returned if the resource does not exist.
	Get(ctx context.Context, name string) (TeamAccess, error)

	// List the team access control list for this repository.
	//
	// List returns all available team access lists, using multiple paginated requests if needed.
	List(ctx context.Context) ([]TeamAccess, error)

	// Create adds a given team to the repository's team access control list.
	//
	// ErrAlreadyExists will be returned if the resource already exists.
	Create(ctx context.Context, req TeamAccessInfo) (TeamAccess, error)

	// Reconcile makes sure the given desired state (req) becomes the actual state in the backing Git provider.
	//
	// If req doesn't exist under the hood, it is created (actionTaken == true).
	// If req doesn't equal the actual state, the resource will be updated (actionTaken == true).
	// If req is already the actual state, this is a no-op (actionTaken == false).
	Reconcile(ctx context.Context, req TeamAccessInfo) (resp TeamAccess, actionTaken bool, err error)
}

TeamAccessClient operates on the teams list for a specific repository. This client can be accessed through Repository.TeamAccess().

type TeamAccessInfo 

type TeamAccessInfo struct {
	// Name describes the name of the team. The team name may contain slashes.
	// +required
	Name string `json:"name"`

	// Permission describes the permission level for which the team is allowed to operate.
	// Default: pull.
	// Available options: See the RepositoryPermission enum.
	// +optional
	Permission *RepositoryPermission `json:"permission,omitempty"`
}

TeamAccessInfo contains high-level information about a team's access to a repository.

func (*TeamAccessInfo) Default 

func (ta *TeamAccessInfo) Default()

Default defaults the TeamAccess fields.

func (TeamAccessInfo) Equals 

func (ta TeamAccessInfo) Equals(actual InfoRequest) bool

Equals can be used to check if this *Info request (the desired state) matches the actual passed in as the argument.

func (TeamAccessInfo) ValidateInfo 

func (ta TeamAccessInfo) ValidateInfo() error

ValidateInfo validates the object at {Object}.Set() and POST-time.

type TeamInfo 

type TeamInfo struct {
	// Name describes the name of the team. The team name may contain slashes.
	Name string `json:"name"`

	// Members points to a set of user names (logins) of the members of this team.
	Members []string `json:"members"`
}

TeamInfo is a representation for a team of users inside of an organization.

type TeamsClient 

type TeamsClient interface {
	// Get a team within the specific organization.
	//
	// name may include slashes, but must not be an empty string.
	// Teams are sub-groups in GitLab.
	//
	// ErrNotFound is returned if the resource does not exist.
	Get(ctx context.Context, name string) (Team, error)

	// List all teams (recursively, in terms of subgroups) within the specific organization.
	//
	// List returns all available organizations, using multiple paginated requests if needed.
	List(ctx context.Context) ([]Team, error)
}

TeamsClient allows reading teams for a specific organization. This client can be accessed through Organization.Teams().

type TransportType 

type TransportType string

TransportType is an enum specifying the transport type used when cloning a repository.

type Updatable 

type Updatable interface {
	// Update will apply the desired state in this object to the server.
	// Only set fields will be respected (i.e. PATCH behaviour).
	// In order to apply changes to this object, use the .Set({Resource}Info) error
	// function, or cast .APIObject() to a pointer to the provider-specific type
	// and set custom fields there.
	//
	// ErrNotFound is returned if the resource does not exist.
	//
	// The internal API object will be overridden with the received server data.
	Update(ctx context.Context) error
}

Updatable is an interface which all objects that can be updated using the Client implement.

type UserRef 

type UserRef struct {
	// Domain returns e.g. "github.com", "gitlab.com" or a custom domain like "self-hosted-gitlab.com" (GitLab)
	// The domain _might_ contain port information, in the form of "host:port", if applicable
	// +required
	Domain string `json:"domain"`

	// UserLogin returns the user account login name.
	// +required
	UserLogin string `json:"userLogin"`
}

UserRef represents a user account in a Git provider.

func ParseUserURL 

func ParseUserURL(u string) (*UserRef, error)

ParseUserURL parses an URL to an organization into a UserRef object.

func (UserRef) GetDomain 

func (u UserRef) GetDomain() string

GetDomain returns the the domain part of the endpoint, can include port information.

func (UserRef) GetIdentity 

func (u UserRef) GetIdentity() string

GetIdentity returns the identity of this actor, which in this case is the user login name.

func (UserRef) GetType 

func (u UserRef) GetType() IdentityType

GetType marks this UserRef as being a IdentityTypeUser.

func (UserRef) String 

func (u UserRef) String() string

String returns the HTTPS URL to access the User.

func (UserRef) ValidateFields 

func (u UserRef) ValidateFields(validator validation.Validator)

ValidateFields validates its own fields for a given validator.

type UserRepositoriesClient 

type UserRepositoriesClient interface {
	// Get returns the repository at the given path.
	//
	// ErrNotFound is returned if the resource does not exist.
	Get(ctx context.Context, r UserRepositoryRef) (UserRepository, error)

	// List all repositories for the given user.
	//
	// List returns all available repositories, using multiple paginated requests if needed.
	List(ctx context.Context, o UserRef) ([]UserRepository, error)

	// Create creates a repository for the given user, with the data and options
	//
	// ErrAlreadyExists will be returned if the resource already exists.
	Create(ctx context.Context, r UserRepositoryRef, req RepositoryInfo, opts ...RepositoryCreateOption) (UserRepository, error)

	// Reconcile makes sure the given desired state (req) becomes the actual state in the backing Git provider.
	//
	// If req doesn't exist under the hood, it is created (actionTaken == true).
	// If req doesn't equal the actual state, the resource will be updated (actionTaken == true).
	// If req is already the actual state, this is a no-op (actionTaken == false).
	Reconcile(ctx context.Context, r UserRepositoryRef, req RepositoryInfo, opts ...RepositoryReconcileOption) (resp UserRepository, actionTaken bool, err error)
}

UserRepositoriesClient operates on repositories for users.

type UserRepository 

type UserRepository interface {
	// UserRepository and OrgRepository implement the Object interface,
	// allowing access to the underlying object returned from the API.
	Object
	// The repository can be updated.
	Updatable
	// The repository can be reconciled.
	Reconcilable
	// The repository can be deleted.
	Deletable
	// RepositoryBound returns repository reference details.
	RepositoryBound

	// Get returns high-level information about this repository.
	Get() RepositoryInfo
	// Set sets high-level desired state for this repository. In order to apply these changes in
	// the Git provider, run .Update() or .Reconcile().
	Set(RepositoryInfo) error

	// DeployKeys gives access to manipulating deploy keys to access this specific repository.
	DeployKeys() DeployKeyClient
}

UserRepository describes a repository owned by an user.

type UserRepositoryRef 

type UserRepositoryRef struct {
	// UserRepositoryRef embeds UserRef inline.
	UserRef `json:",inline"`

	// RepositoryName specifies the Git repository name. This field is URL-friendly,
	// e.g. "kubernetes" or "cluster-api-provider-aws".
	// +required
	RepositoryName string `json:"repositoryName"`
}

UserRepositoryRef is a struct with information about a specific repository owned by a user.

func ParseUserRepositoryURL 

func ParseUserRepositoryURL(r string) (*UserRepositoryRef, error)

ParseUserRepositoryURL parses a HTTPS clone URL into a UserRepositoryRef object.

func (UserRepositoryRef) GetCloneURL 

func (r UserRepositoryRef) GetCloneURL(transport TransportType) string

GetCloneURL gets the clone URL for the specified transport type.

func (UserRepositoryRef) GetRepository 

func (r UserRepositoryRef) GetRepository() string

GetRepository returns the repository name for this repo.

func (UserRepositoryRef) String 

func (r UserRepositoryRef) String() string

String returns the HTTPS URL to access the repository.

func (UserRepositoryRef) ValidateFields 

func (r UserRepositoryRef) ValidateFields(validator validation.Validator)

ValidateFields validates its own fields for a given validator.

type ValidationError 

type ValidationError struct {
	// RateLimitError extends HTTPError.
	HTTPError `json:",inline"`

	// Errors contain context about what validation(s) failed.
	Errors []ValidationErrorItem `json:"errors"`
}

ValidationError is an error, extending HTTPError, that contains context about failed server-side validation.

type ValidationErrorItem 

type ValidationErrorItem struct {
	// Resource on which the error occurred.
	Resource string `json:"resource"`
	// Field on which the error occurred.
	Field string `json:"field"`
	// Code for the validation error.
	Code string `json:"code"`
	// Message describing the error. Errors with Code == "custom" will always have this set.
	Message string `json:"message"`
}

ValidationErrorItem represents a single invalid field in an invalid request.

Source Files

View all Source files

Directories

Path Synopsis

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.