Documentation
¶
Overview ¶
getEnvOrFile returns the value of the environment variable if set, otherwise if a corresponding _FILE variable is set, reads the value from the file at that path. If both are set, the environment variable takes precedence.
Index ¶
- Constants
- Variables
- func AddBasicAuthToURL(originalURL, username, password string) (string, error)
- func SetLogOutput(w io.Writer)
- func ToPtr[T any](v T) *T
- func TrimInPlace(s *string)
- type AzureDevOpsHost
- func (ad *AzureDevOpsHost) Backup() ProviderBackupResult
- func (ad *AzureDevOpsHost) ListOrgMembers(ctx context.Context, org string) ([]string, error)
- func (ad *AzureDevOpsHost) ListOrgRepos(ctx context.Context, org string) ([]Repository, error)
- func (ad *AzureDevOpsHost) ListOwnRepos(ctx context.Context) ([]Repository, error)
- func (ad *AzureDevOpsHost) ListUserRepos(context.Context, string) ([]Repository, error)
- type AzureDevOpsRepo
- type BasicAuth
- type BitbucketHost
- func (bb BitbucketHost) Backup() ProviderBackupResult
- func (bb *BitbucketHost) ListOrgMembers(ctx context.Context, workspace string) ([]string, error)
- func (bb *BitbucketHost) ListOrgRepos(ctx context.Context, workspace string) ([]Repository, error)
- func (bb *BitbucketHost) ListOwnRepos(ctx context.Context) ([]Repository, error)
- func (bb *BitbucketHost) ListUserRepos(ctx context.Context, user string) ([]Repository, error)
- type BundleManifest
- type CodebergHost
- func (cb *CodebergHost) Backup() ProviderBackupResult
- func (cb *CodebergHost) ListOrgMembers(ctx context.Context, org string) ([]string, error)
- func (cb *CodebergHost) ListOrgRepos(ctx context.Context, org string) ([]Repository, error)
- func (cb *CodebergHost) ListOwnRepos(ctx context.Context) ([]Repository, error)
- func (cb *CodebergHost) ListUserRepos(ctx context.Context, user string) ([]Repository, error)
- type GitHubHost
- func (gh *GitHubHost) Backup() ProviderBackupResult
- func (gh *GitHubHost) ListOrgMembers(ctx context.Context, org string) ([]string, error)
- func (gh *GitHubHost) ListOrgRepos(ctx context.Context, org string) ([]Repository, error)
- func (gh *GitHubHost) ListOwnRepos(ctx context.Context) ([]Repository, error)
- func (gh *GitHubHost) ListUserRepos(ctx context.Context, user string) ([]Repository, error)
- type GitLabHost
- func (gl *GitLabHost) Backup() ProviderBackupResult
- func (gl *GitLabHost) ListOrgMembers(ctx context.Context, group string) ([]string, error)
- func (gl *GitLabHost) ListOrgRepos(ctx context.Context, group string) ([]Repository, error)
- func (gl *GitLabHost) ListOwnRepos(ctx context.Context) ([]Repository, error)
- func (gl *GitLabHost) ListUserRepos(ctx context.Context, user string) ([]Repository, error)
- type GiteaHost
- func (g *GiteaHost) Backup() ProviderBackupResult
- func (g *GiteaHost) ListOrgMembers(ctx context.Context, org string) ([]string, error)
- func (g *GiteaHost) ListOrgRepos(ctx context.Context, org string) ([]Repository, error)
- func (g *GiteaHost) ListOwnRepos(ctx context.Context) ([]Repository, error)
- func (g *GiteaHost) ListUserRepos(ctx context.Context, user string) ([]Repository, error)
- type LFSManifest
- type Lister
- type NewAzureDevOpsHostInput
- type NewBitBucketHostInput
- type NewCodebergHostInput
- type NewGitHubHostInput
- type NewGitLabHostInput
- type NewGiteaHostInput
- type NewSourcehutHostInput
- type Project
- type ProviderBackupResult
- type RepoBackupResults
- type Repository
- type SourcehutHost
- func (sh *SourcehutHost) Backup() ProviderBackupResult
- func (sh *SourcehutHost) ListOrgMembers(context.Context, string) ([]string, error)
- func (sh *SourcehutHost) ListOrgRepos(context.Context, string) ([]Repository, error)
- func (sh *SourcehutHost) ListOwnRepos(ctx context.Context) ([]Repository, error)
- func (sh *SourcehutHost) ListUserRepos(ctx context.Context, user string) ([]Repository, error)
- type WorkerConfig
Constants ¶
const ( BitbucketProviderName = "BitBucket" // Auth Type AuthTypeBitbucketOAuth2 = AuthTypeBearerToken AuthTypeBitbucketAPIToken = AuthTypeBasicAuthHeader AuthTypeBasicAuthHeader = "basic-auth-header" AuthTypeBearerToken = "bearer-token" )
const ( // HTTP Headers HeaderContentType = "Content-Type" HeaderAuthorization = "Authorization" HeaderAccept = "Accept" // Authentication prefixes AuthPrefixBearer = "Bearer " AuthPrefixToken = "token " AuthPrefixBasic = "Basic " // Content types ContentTypeJSON = "application/json" ContentTypeFormEncoded = "application/x-www-form-urlencoded" ContentTypeAny = "*/*" )
const (
AzureDevOpsProviderName = "AzureDevOps"
)
const (
// GitLabDefaultMinimumProjectAccessLevel https://docs.gitlab.com/ee/user/permissions.html#roles
GitLabDefaultMinimumProjectAccessLevel = 20
)
Variables ¶
var ErrNotSupported = errors.Base("operation not supported by provider")
ErrNotSupported is returned by a Lister method the provider has no equivalent for, such as listing the members of an organisation on a host without organisations. Test for it with errors.Is.
Functions ¶
func AddBasicAuthToURL ¶
func SetLogOutput ¶ added in v2.2.0
SetLogOutput sets where the library writes its log messages, which go to standard output by default. A program embedding the library can route them into its own logging, or pass io.Discard to silence them.
func TrimInPlace ¶
func TrimInPlace(s *string)
Types ¶
type AzureDevOpsHost ¶
type AzureDevOpsHost struct {
Caller string
HttpClient *retryablehttp.Client
Provider string
PAT string
Orgs []string
UserName string
DiffRemoteMethod string
BackupDir string
BackupsToRetain int
LogLevel int
BackupLFS bool
EncryptionPassphrase string
}
func NewAzureDevOpsHost ¶
func NewAzureDevOpsHost(input NewAzureDevOpsHostInput) (*AzureDevOpsHost, error)
func (*AzureDevOpsHost) Backup ¶
func (ad *AzureDevOpsHost) Backup() ProviderBackupResult
func (*AzureDevOpsHost) ListOrgMembers ¶ added in v2.3.0
ListOrgMembers returns the principal names of the organisation's users, falling back to the mail address for a user without one. Azure DevOps identifies users by principal name: the sign-in address of a Microsoft Entra ID or Microsoft account.
It uses User Entitlements - Search User Entitlements, so the PAT needs the Member Entitlement Management (Read) scope, vso.memberentitlementmanagement, which Backup does not.
func (*AzureDevOpsHost) ListOrgRepos ¶ added in v2.3.0
func (ad *AzureDevOpsHost) ListOrgRepos(ctx context.Context, org string) ([]Repository, error)
ListOrgRepos lists the Git repositories of every project in the organisation, as Backup does. Hidden repositories are excluded, as they are by default from the API and from Backup.
Fields are filled from Repositories - List and the project's entry in Projects - List:
- Owner is the organisation and PathWithNamespace is "organisation/project/repository", matching Backup.
- CloneURL is webUrl, which Backup clones. remoteUrl is not used as it carries the organisation as a URL username.
- IsArchived is always false. Azure DevOps has no archived state; the nearest, isDisabled, blocks all access to the repository rather than making it read-only, so it is not reported as archived.
- IsEmpty reports that there is no defaultBranch, which Azure DevOps only sets once the first branch is pushed.
- IsPrivate reports that the project's visibility is not public.
- SizeKB is the compressed size in bytes rounded up to whole kilobytes.
func (*AzureDevOpsHost) ListOwnRepos ¶ added in v2.3.0
func (ad *AzureDevOpsHost) ListOwnRepos(ctx context.Context) ([]Repository, error)
ListOwnRepos lists the repositories Backup processes: those of the first configured organisation, as Backup does not support more than one.
func (*AzureDevOpsHost) ListUserRepos ¶ added in v2.3.0
func (ad *AzureDevOpsHost) ListUserRepos(context.Context, string) ([]Repository, error)
ListUserRepos is not supported: Azure DevOps repositories belong to projects within an organisation, never to a user.
type AzureDevOpsRepo ¶
type AzureDevOpsRepo struct {
Id string `json:"id"`
Url string `json:"url"`
Name string `json:"name"`
Size int64 `json:"size"`
SshUrl string `json:"sshUrl"`
WebUrl string `json:"webUrl"`
Project Project `json:"project"`
RemoteUrl string `json:"remoteUrl"`
DefaultBranch string `json:"defaultBranch"`
}
func ListAllRepositories ¶
func ListAllRepositories(httpClient *retryablehttp.Client, basicAuth, projectName, orgName string) ([]AzureDevOpsRepo, error)
type BitbucketHost ¶
type BitbucketHost struct {
Caller string
HttpClient *retryablehttp.Client
Provider string
APIURL string
DiffRemoteMethod string
BackupDir string
BackupsToRetain int
AuthType string
// API OAuthToken
Email string
APIToken string
BasicAuth BasicAuth
// OAuth2
User string
OAuthToken string
Key string
Secret string
LogLevel int
BackupLFS bool
EncryptionPassphrase string
Workspaces []string
}
func NewBitBucketHost ¶
func NewBitBucketHost(input NewBitBucketHostInput) (*BitbucketHost, error)
func (BitbucketHost) Backup ¶
func (bb BitbucketHost) Backup() ProviderBackupResult
func (*BitbucketHost) ListOrgMembers ¶ added in v2.3.0
ListOrgMembers returns the UUIDs, in braces, of the named workspace's members. Bitbucket no longer reports usernames, and the nickname it documents in their place is not unique, so the UUID is returned instead. A UUID in braces is accepted wherever Bitbucket's API takes a workspace, so a member's UUID can be passed to ListUserRepos.
func (*BitbucketHost) ListOrgRepos ¶ added in v2.3.0
func (bb *BitbucketHost) ListOrgRepos(ctx context.Context, workspace string) ([]Repository, error)
ListOrgRepos lists the repositories in the named workspace that the credentials can see.
func (*BitbucketHost) ListOwnRepos ¶ added in v2.3.0
func (bb *BitbucketHost) ListOwnRepos(ctx context.Context) ([]Repository, error)
ListOwnRepos lists the repositories Backup would: those the authenticated user is a member of in each configured workspace, or in every workspace the user can access when none are configured.
func (*BitbucketHost) ListUserRepos ¶ added in v2.3.0
func (bb *BitbucketHost) ListUserRepos(ctx context.Context, user string) ([]Repository, error)
ListUserRepos lists the repositories in the named user's personal workspace that the credentials can see. Bitbucket separates usernames from workspace IDs, so user is the personal workspace's ID, as shown in the user's repository URLs, or a UUID in braces as ListOrgMembers returns.
type BundleManifest ¶
type BundleManifest struct {
CreationTime string `json:"creation_time"`
BundleHash string `json:"bundle_hash"`
BundleFile string `json:"bundle_file"`
GitRefs map[string]string `json:"git_refs"`
}
BundleManifest represents the metadata for a bundle
type CodebergHost ¶ added in v2.1.7
type CodebergHost struct {
Caller string
Provider string
APIURL string
DiffRemoteMethod string
BackupDir string
Token string
Orgs []string
SkipUserRepos bool
LimitUserOwned bool
BackupsToRetain int
LogLevel int
BackupLFS bool
EncryptionPassphrase string
// contains filtered or unexported fields
}
func NewCodebergHost ¶ added in v2.1.7
func NewCodebergHost(input NewCodebergHostInput) (*CodebergHost, error)
func (*CodebergHost) Backup ¶ added in v2.1.7
func (cb *CodebergHost) Backup() ProviderBackupResult
func (*CodebergHost) ListOrgMembers ¶ added in v2.3.0
ListOrgMembers returns the logins of the named organisation's members, from /orgs/{org}/members. A caller that is not a member of the organisation, or has no token, sees only its public members.
func (*CodebergHost) ListOrgRepos ¶ added in v2.3.0
func (cb *CodebergHost) ListOrgRepos(ctx context.Context, org string) ([]Repository, error)
ListOrgRepos lists the named organisation's repositories that the token can see, from /orgs/{org}/repos.
func (*CodebergHost) ListOwnRepos ¶ added in v2.3.0
func (cb *CodebergHost) ListOwnRepos(ctx context.Context) ([]Repository, error)
ListOwnRepos lists the repositories the token can access through /user/repos, as Backup does before adding the configured organisations: those the user owns, those of organisations they belong to and those they collaborate on. LimitUserOwned keeps only those the token's user owns. SkipUserRepos is ignored, as it only stops Backup from using this listing.
func (*CodebergHost) ListUserRepos ¶ added in v2.3.0
func (cb *CodebergHost) ListUserRepos(ctx context.Context, user string) ([]Repository, error)
ListUserRepos lists the repositories the named user owns that the token can see, from /users/{username}/repos. Without a token, or with another user's, private repositories are left out.
type GitHubHost ¶
type GitHubHost struct {
Caller string
HttpClient *retryablehttp.Client
Provider string
APIURL string
DiffRemoteMethod string
BackupDir string
SkipUserRepos bool
LimitUserOwned bool
BackupsToRetain int
Token string
Orgs []string
LogLevel int
BackupLFS bool
EncryptionPassphrase string
// contains filtered or unexported fields
}
func NewGitHubHost ¶
func NewGitHubHost(input NewGitHubHostInput) (*GitHubHost, error)
func (*GitHubHost) Backup ¶
func (gh *GitHubHost) Backup() ProviderBackupResult
func (*GitHubHost) ListOrgMembers ¶ added in v2.2.0
ListOrgMembers returns the logins of the named organization's members. The token needs the read:org scope to see members who keep their membership private.
func (*GitHubHost) ListOrgRepos ¶ added in v2.2.0
func (gh *GitHubHost) ListOrgRepos(ctx context.Context, org string) ([]Repository, error)
ListOrgRepos lists the named organization's repositories.
func (*GitHubHost) ListOwnRepos ¶ added in v2.2.0
func (gh *GitHubHost) ListOwnRepos(ctx context.Context) ([]Repository, error)
ListOwnRepos lists the authenticated user's repositories, honouring LimitUserOwned.
func (*GitHubHost) ListUserRepos ¶ added in v2.2.0
func (gh *GitHubHost) ListUserRepos(ctx context.Context, user string) ([]Repository, error)
ListUserRepos lists the repositories the named user owns.
type GitLabHost ¶
type GitLabHost struct {
Caller string
APIURL string
DiffRemoteMethod string
BackupDir string
BackupsToRetain int
ProjectMinAccessLevel int
Token string
User gitlabUser
LogLevel int
BackupLFS bool
EncryptionPassphrase string
// contains filtered or unexported fields
}
func NewGitLabHost ¶
func NewGitLabHost(input NewGitLabHostInput) (*GitLabHost, error)
func (*GitLabHost) Backup ¶
func (gl *GitLabHost) Backup() ProviderBackupResult
func (*GitLabHost) ListOrgMembers ¶ added in v2.2.0
ListOrgMembers returns the usernames of the group's members, including those who inherit membership from a parent group.
func (*GitLabHost) ListOrgRepos ¶ added in v2.2.0
func (gl *GitLabHost) ListOrgRepos(ctx context.Context, group string) ([]Repository, error)
ListOrgRepos lists the projects of the group with the given full path, including those in its subgroups.
func (*GitLabHost) ListOwnRepos ¶ added in v2.2.0
func (gl *GitLabHost) ListOwnRepos(ctx context.Context) ([]Repository, error)
ListOwnRepos lists the projects the authenticated user can access at ProjectMinAccessLevel or above. It needs a token, as there is no authenticated user without one.
func (*GitLabHost) ListUserRepos ¶ added in v2.2.0
func (gl *GitLabHost) ListUserRepos(ctx context.Context, user string) ([]Repository, error)
ListUserRepos lists the personal projects of the named user that the token can see.
type GiteaHost ¶
type GiteaHost struct {
Caller string
APIURL string
DiffRemoteMethod string
BackupDir string
BackupsToRetain int
Token string
Orgs []string
LogLevel int
BackupLFS bool
EncryptionPassphrase string
// contains filtered or unexported fields
}
func NewGiteaHost ¶
func NewGiteaHost(input NewGiteaHostInput) (*GiteaHost, error)
func (*GiteaHost) Backup ¶
func (g *GiteaHost) Backup() ProviderBackupResult
func (*GiteaHost) ListOrgMembers ¶ added in v2.3.0
ListOrgMembers returns the logins of the named organisation's members, from /orgs/{org}/members. A caller that is neither a member of the organisation nor a site administrator, or has no token, sees only its public members.
func (*GiteaHost) ListOrgRepos ¶ added in v2.3.0
ListOrgRepos lists the named organisation's repositories that the token can see, from /orgs/{org}/repos.
func (*GiteaHost) ListOwnRepos ¶ added in v2.3.0
func (g *GiteaHost) ListOwnRepos(ctx context.Context) ([]Repository, error)
ListOwnRepos lists the repositories of every user on the instance, as Backup does before adding the configured organisations. Users are enumerated through /admin/users, so the token must belong to a site administrator; any other token is refused with HTTP 403. Each user's repositories come from /users/{username}/repos.
func (*GiteaHost) ListUserRepos ¶ added in v2.3.0
ListUserRepos lists the repositories the named user owns that the token can see, from /users/{username}/repos. Without a token, or with one that belongs to neither the user nor an administrator, private repositories are left out.
type LFSManifest ¶
type LFSManifest struct {
CreationTime string `json:"creation_time"`
ArchiveHash string `json:"archive_hash"`
ArchiveFile string `json:"archive_file"`
}
LFSManifest represents the metadata for an LFS archive
type Lister ¶ added in v2.2.0
type Lister interface {
// ListOwnRepos lists the repositories visible to the authenticated user,
// as selected by the host's configuration; it is the same set Backup
// would process before any organisations are added.
ListOwnRepos(ctx context.Context) ([]Repository, error)
// ListUserRepos lists the repositories owned by the named user.
ListUserRepos(ctx context.Context, user string) ([]Repository, error)
// ListOrgRepos lists the repositories belonging to the named
// organisation, or group on GitLab.
ListOrgRepos(ctx context.Context, org string) ([]Repository, error)
// ListOrgMembers returns the usernames of the named organisation's
// members.
ListOrgMembers(ctx context.Context, org string) ([]string, error)
}
Lister lists repositories and organisation members on a provider. A method the provider cannot support returns an error wrapping ErrNotSupported.
type NewAzureDevOpsHostInput ¶
type NewBitBucketHostInput ¶
type NewBitBucketHostInput struct {
Caller string
HTTPClient *retryablehttp.Client
APIURL string
DiffRemoteMethod string
BackupDir string
// API OAuthToken
Email string
BasicAuth BasicAuth
AuthType string
// API OAuthToken
APIToken string
// OAuth2
User string
Key string
Secret string
OAuthToken string
Username string
BackupsToRetain int
LogLevel int
BackupLFS bool
EncryptionPassphrase string
Workspaces []string
}
type NewCodebergHostInput ¶ added in v2.1.7
type NewCodebergHostInput struct {
Caller string
HTTPClient *retryablehttp.Client
APIURL string
DiffRemoteMethod string
BackupDir string
Token string
// Orgs limits organisation backups to the named organisations. An entry of
// "*" expands to every organisation the token belongs to, and can be
// combined with names of organisations it does not.
Orgs []string
// SkipUserRepos omits /user/repos, backing up only the repositories owned
// by the organisations named in Orgs.
SkipUserRepos bool
// LimitUserOwned restricts /user/repos results to repositories owned by the
// authenticated user, excluding those they merely have access to.
LimitUserOwned bool
BackupsToRetain int
LogLevel int
BackupLFS bool
EncryptionPassphrase string
}
NewCodebergHostInput configures a Codeberg host.
Codeberg runs Forgejo, which serves the same /api/v1 surface as Gitea, but as a shared public instance rather than one you administer. The Gitea host enumerates repositories via the instance-admin endpoints (/admin/users and /orgs), which a Codeberg personal access token cannot reach; this host uses the token-scoped endpoints (/user/repos and /user/orgs) instead.
type NewGitHubHostInput ¶
type NewGitLabHostInput ¶
type NewGiteaHostInput ¶
type NewSourcehutHostInput ¶
type ProviderBackupResult ¶
type ProviderBackupResult struct {
BackupResults []RepoBackupResults
Error errors.E
}
type RepoBackupResults ¶
type Repository ¶ added in v2.2.0
type Repository struct {
// Owner is the user, organisation or group namespace the repository
// belongs to.
Owner string
Name string
// PathWithNamespace is the provider's full path, e.g. "owner/name", or
// "group/subgroup/name" on GitLab.
PathWithNamespace string
// Domain is the host the repository is served from, e.g. "github.com".
Domain string
// CloneURL is the HTTPS clone URL. It never carries credentials: apply
// Auth separately so that credentials cannot leak through the URL into
// logs or error messages.
CloneURL string
SSHURL string
// Auth holds the HTTP basic auth credentials CloneURL requires, in the
// form this provider expects.
Auth BasicAuth
IsFork bool
IsArchived bool
// IsEmpty reports that the repository has no commits. It is only as good
// as the provider's API: a provider that cannot report it leaves it
// false.
IsEmpty bool
// IsPrivate reports that the repository is not public. GitLab's internal
// visibility, which any signed-in user can see, counts as private.
IsPrivate bool
// SizeKB is the repository's size in kilobytes, or 0 when the provider
// does not report it, as GitLab's listings do not.
SizeKB int64
}
Repository describes a repository as reported by a provider's API, with what a caller needs to clone it using its own git implementation.
type SourcehutHost ¶
type SourcehutHost struct {
Caller string
HttpClient *retryablehttp.Client
Provider string
APIURL string
DiffRemoteMethod string
BackupDir string
SkipUserRepos bool
LimitUserOwned bool
BackupsToRetain int
PersonalAccessToken string
Orgs []string
LogLevel int
BackupLFS bool
EncryptionPassphrase string
}
func NewSourcehutHost ¶
func NewSourcehutHost(input NewSourcehutHostInput) (*SourcehutHost, error)
func (*SourcehutHost) Backup ¶
func (sh *SourcehutHost) Backup() ProviderBackupResult
func (*SourcehutHost) ListOrgMembers ¶ added in v2.3.0
ListOrgMembers is not supported: SourceHut has no organisations.
func (*SourcehutHost) ListOrgRepos ¶ added in v2.3.0
func (sh *SourcehutHost) ListOrgRepos(context.Context, string) ([]Repository, error)
ListOrgRepos is not supported: SourceHut has users but no organisations or groups that own repositories.
func (*SourcehutHost) ListOwnRepos ¶ added in v2.3.0
func (sh *SourcehutHost) ListOwnRepos(ctx context.Context) ([]Repository, error)
ListOwnRepos lists the authenticated user's public repositories: the set Backup processes. git.sr.ht's repositories query returns only repositories the token's user owns. Unlisted and private repositories are left out, as Backup skips them; use ListUserRepos with the token's own username to see them.
SourceHut has no forks, archiving or repository sizes in its API, so IsFork and IsArchived are always false and SizeKB is always 0. Domain is "sourcehut", the name Backup files the repositories under, as the API does not report a host.
func (*SourcehutHost) ListUserRepos ¶ added in v2.3.0
func (sh *SourcehutHost) ListUserRepos(ctx context.Context, user string) ([]Repository, error)
ListUserRepos lists the repositories owned by the named user that the token can see: their public repositories, plus any unlisted or private ones the token's user owns or has been granted access to. The user may be given with or without SourceHut's "~" prefix.
IsPrivate is true for both UNLISTED and PRIVATE visibility. An unlisted repository can be read by anyone with its URL, but it is not public in the sense Backup uses, and Backup skips it.