githosts

package module
v2.3.0 Latest Latest
Warning

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

Go to latest
Published: Oct 8, 2026 License: MIT Imports: 29 Imported by: 0

README

githosts-utils

githosts-utils is a Go library for backing up repositories from major hosting providers. It powers soba and can be embedded in your own tools.

Features

  • Minimal dependencies and portable code
  • Supports GitHub, GitLab, Bitbucket, Azure DevOps, Gitea, Codeberg, and Sourcehut
  • Clones repositories using git --mirror and stores timestamped bundle files
  • Encryption support: Optional age-based encryption for bundles and manifests
  • Optional reference comparison to skip cloning when refs have not changed
  • Ability to keep a configurable number of previous bundles
  • Optional Git LFS archival alongside each bundle
  • Pluggable HTTP client and simple logging via the GITHOSTS_LOG environment variable

Installation

go get github.com/jonhadfield/githosts-utils

Requires Go 1.22 or later.

Quick Start

Create a host for the provider you want to back up and call Backup() on it. Each provider has its own input struct with the required options. The example below backs up a set of GitHub repositories:

package main

import (
    "log"
    "os"

    "github.com/jonhadfield/githosts-utils"
)

func main() {
    backupDir := "/path/to/backups"

    host, err := githosts.NewGitHubHost(githosts.NewGitHubHostInput{
        Caller:               "example",
        BackupDir:            backupDir,
        Token:                os.Getenv("GITHUB_TOKEN"),
        BackupLFS:            true,
        EncryptionPassphrase: os.Getenv("BUNDLE_PASSPHRASE"), // Optional encryption
    })
    if err != nil {
        log.Fatal(err)
    }

    results := host.Backup()
    for _, r := range results.BackupResults {
        log.Printf("%s: %s", r.Repo, r.Status)
    }
}

Backup() returns a ProviderBackupResult containing the status of each repository. Bundles are written beneath <backupDir>/<provider>/<owner>/<repo>/.

Diff Remote Method

Each host accepts a DiffRemoteMethod value of either "clone" or "refs":

  • clone (default) – always clone and create a new bundle
  • refs – fetch remote references first and skip cloning when the refs match the latest bundle
Codeberg

Codeberg runs Forgejo, which serves the same /api/v1 surface as Gitea, so it has its own host rather than reusing the Gitea one. The difference is ownership: the Gitea host discovers repositories through the instance-admin endpoints (/admin/users and /orgs), which a Codeberg personal access token cannot reach, and whose /orgs listing would return every organisation on the instance rather than yours. The Codeberg host uses the token-scoped endpoints (/user/repos and /user/orgs) instead.

host, err := githosts.NewCodebergHost(githosts.NewCodebergHostInput{
    BackupDir: backupDir,
    Token:     os.Getenv("CODEBERG_TOKEN"),
    Orgs:      []string{"*"}, // "*" expands to every org the token belongs to
})

APIURL defaults to https://codeberg.org/api/v1 and can be pointed at any other Forgejo instance. The "*" entry expands to every organisation the token belongs to and is combined with any organisations named alongside it, so organisations the token is not a member of can still be backed up. Two further options control the breadth of the backup:

  • SkipUserRepos – omit /user/repos, backing up only the organisations named in Orgs
  • LimitUserOwned – keep only repositories owned by the authenticated user, excluding those they are merely a collaborator on

/user/repos already includes repositories owned by your organisations, so repositories reachable both ways are backed up once.

Codeberg is a donation-funded shared host, so this provider defaults to lower concurrency and a longer delay between repositories than the Gitea one. Override the delay with CODEBERG_WORKER_DELAY (milliseconds) and the number of repositories backed up at once with CODEBERG_MAX_CONCURRENT.

Listing Repositories

Every host also implements Lister, for tools that need a provider's repositories without backing them up:

host, err := githosts.NewGitHubHost(githosts.NewGitHubHostInput{Token: os.Getenv("GITHUB_TOKEN")})
if err != nil {
    log.Fatal(err)
}

repos, err := host.ListOrgRepos(ctx, "my-org")
Host ListOwnRepos(ctx) ListUserRepos(ctx, user) ListOrgRepos(ctx, org) ListOrgMembers(ctx, org)
GitHub the token owner's repositories, honouring LimitUserOwned repositories the user owns the organisation's repositories member logins (read:org shows private members)
GitLab projects at ProjectMinAccessLevel or above the user's personal projects the group's projects, including subgroups (org is the full path) usernames, including inherited members
Bitbucket repositories in the configured or discovered workspaces the user's personal workspace (user is its workspace ID or UUID) the workspace's repositories member UUIDs in braces, which ListUserRepos accepts
Azure DevOps every repository in the first configured organisation, as Backup() processes not supported every repository in every project of the organisation users' principal names (needs the Member Entitlement Management read scope)
Gitea every user's repositories, through the admin endpoints Backup() uses (needs a site-admin token) the user's repositories the organisation's repositories member logins (non-members see public members only)
Codeberg the token's repositories (/user/repos), honouring LimitUserOwned the user's repositories the organisation's repositories member logins (non-members see public members only)
Sourcehut the token owner's public repositories, as Backup() processes the user's repositories the token can see (~ optional) not supported not supported

Each Repository reports IsFork, IsArchived, IsEmpty, IsPrivate and SizeKB, and carries a CloneURL without credentials plus the Auth it needs, so a caller can clone with its own git implementation without credentials appearing in URLs. A method a provider cannot support returns an error wrapping ErrNotSupported. Where a provider has no such field, the value is false or 0:

  • SizeKB is 0 for GitLab and Sourcehut, which do not report a size.
  • IsArchived is always false for Bitbucket, Azure DevOps and Sourcehut, which have no archived state. A disabled Azure DevOps repository cannot be cloned at all, so it is not reported as archived.
  • IsFork is always false for Sourcehut.
  • GitLab internal projects, Gitea and Codeberg internal repositories, and Sourcehut unlisted repositories count as private.

The GitLab, Gitea and Codeberg listers also work without a token, listing only public repositories and returning no Auth; their ListOwnRepos still needs one. Sourcehut's lister needs a token with git.sr.ht's read-only objects scope, to tell whether a repository is empty.

Retaining Bundles

Set BackupsToRetain to keep only the most recent n bundle files per repository. Older bundles are automatically deleted after a successful backup.

Encryption

The library supports optional age-based encryption for all backup bundles and their associated manifests. When encryption is enabled:

  • Bundle files are encrypted and saved with a .age extension (e.g., repo.20240101000000.bundle.age)
  • Manifest files containing bundle metadata and git refs are also encrypted
  • The system can seamlessly work with both encrypted and unencrypted bundles in the same repository
Enabling Encryption

You can enable encryption in two ways:

  1. Via environment variable: Set BUNDLE_PASSPHRASE to your encryption passphrase
  2. Via host configuration: Pass the EncryptionPassphrase parameter when creating a host
host, err := githosts.NewGitHubHost(githosts.NewGitHubHostInput{
    BackupDir:            backupDir,
    Token:                token,
    EncryptionPassphrase: "your-secure-passphrase",
})
Encryption Behavior
  • When using the refs diff method, the system can compare encrypted bundles without decrypting them by using manifest files
  • If you switch from encrypted to unencrypted backups (or vice versa), the system handles this gracefully
  • Wrong passphrases are detected and reported with appropriate error messages
  • Corrupted encrypted files are handled safely with fallback mechanisms

Environment Variables

The library reads the following variables where relevant:

  • GITHOSTS_LOG – set to debug to emit verbose logs
  • GIT_BACKUP_DIR – used by the tests to determine the backup location
  • BUNDLE_PASSPHRASE – optional passphrase for encrypting backup bundles

Provider-specific tests require credentials through environment variables such as GITHUB_TOKEN, GITLAB_TOKEN, BITBUCKET_KEY, BITBUCKET_SECRET, AZURE_DEVOPS_USERNAME, AZURE_DEVOPS_PAT, GITEA_TOKEN, and SOURCEHUT_TOKEN.

Running Tests

export GIT_BACKUP_DIR=$(mktemp -d)
go test ./...

Integration tests are skipped unless the corresponding provider credentials are present.

License

This project is licensed under the MIT License. See LICENSE for details.

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

View Source
const (
	BitbucketProviderName = "BitBucket"

	// Auth Type
	AuthTypeBitbucketOAuth2   = AuthTypeBearerToken
	AuthTypeBitbucketAPIToken = AuthTypeBasicAuthHeader
	AuthTypeBasicAuthHeader   = "basic-auth-header"
	AuthTypeBearerToken       = "bearer-token"
)
View Source
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         = "*/*"
)
View Source
const (
	AzureDevOpsProviderName = "AzureDevOps"
)
View Source
const (
	// GitLabDefaultMinimumProjectAccessLevel https://docs.gitlab.com/ee/user/permissions.html#roles
	GitLabDefaultMinimumProjectAccessLevel = 20
)

Variables

View Source
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 AddBasicAuthToURL(originalURL, username, password string) (string, error)

func SetLogOutput added in v2.2.0

func SetLogOutput(w io.Writer)

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 ToPtr

func ToPtr[T any](v T) *T

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 (*AzureDevOpsHost) ListOrgMembers added in v2.3.0

func (ad *AzureDevOpsHost) ListOrgMembers(ctx context.Context, org string) ([]string, error)

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 BasicAuth

type BasicAuth struct {
	User     string `json:"user,omitempty"`
	Password string `json:"password,omitempty"`
}

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

func (bb *BitbucketHost) ListOrgMembers(ctx context.Context, workspace string) ([]string, error)

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

func (cb *CodebergHost) ListOrgMembers(ctx context.Context, org string) ([]string, error)

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

func (gh *GitHubHost) ListOrgMembers(ctx context.Context, org string) ([]string, error)

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

func (gl *GitLabHost) ListOrgMembers(ctx context.Context, group string) ([]string, error)

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

func (g *GiteaHost) ListOrgMembers(ctx context.Context, org string) ([]string, error)

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

func (g *GiteaHost) 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 (*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

func (g *GiteaHost) 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 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 NewAzureDevOpsHostInput struct {
	HTTPClient           *retryablehttp.Client
	Caller               string
	BackupDir            string
	DiffRemoteMethod     string
	UserName             string
	PAT                  string
	Orgs                 []string
	BackupsToRetain      int
	LogLevel             int
	BackupLFS            bool
	EncryptionPassphrase string
}

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 NewGitHubHostInput struct {
	HTTPClient           *retryablehttp.Client
	Caller               string
	APIURL               string
	DiffRemoteMethod     string
	BackupDir            string
	Token                string
	LimitUserOwned       bool
	SkipUserRepos        bool
	Orgs                 []string
	BackupsToRetain      int
	LogLevel             int
	BackupLFS            bool
	EncryptionPassphrase string
}

type NewGitLabHostInput

type NewGitLabHostInput struct {
	Caller                string
	HTTPClient            *retryablehttp.Client
	APIURL                string
	DiffRemoteMethod      string
	BackupDir             string
	Token                 string
	ProjectMinAccessLevel int
	BackupsToRetain       int
	LogLevel              int
	BackupLFS             bool
	EncryptionPassphrase  string
}

type NewGiteaHostInput

type NewGiteaHostInput struct {
	Caller               string
	HTTPClient           *retryablehttp.Client
	APIURL               string
	DiffRemoteMethod     string
	BackupDir            string
	Token                string
	Orgs                 []string
	BackupsToRetain      int
	LogLevel             int
	BackupLFS            bool
	EncryptionPassphrase string
}

type NewSourcehutHostInput

type NewSourcehutHostInput struct {
	HTTPClient           *retryablehttp.Client
	Caller               string
	APIURL               string
	DiffRemoteMethod     string
	BackupDir            string
	PersonalAccessToken  string
	LimitUserOwned       bool
	SkipUserRepos        bool
	Orgs                 []string
	BackupsToRetain      int
	LogLevel             int
	BackupLFS            bool
	EncryptionPassphrase string
}

type Project

type Project struct {
	Id             string    `json:"id"`
	Url            string    `json:"url"`
	Name           string    `json:"name"`
	State          string    `json:"state"`
	Revision       int       `json:"revision"`
	Visibility     string    `json:"visibility"`
	Description    string    `json:"description"`
	LastUpdateTime time.Time `json:"lastUpdateTime"`
}

type ProviderBackupResult

type ProviderBackupResult struct {
	BackupResults []RepoBackupResults
	Error         errors.E
}

type RepoBackupResults

type RepoBackupResults struct {
	Repo   string   `json:"repo,omitempty"`
	Status string   `json:"status,omitempty"` // ok, failed
	Error  errors.E `json:"error,omitempty"`
}

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

func (sh *SourcehutHost) ListOrgMembers(context.Context, string) ([]string, error)

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.

type WorkerConfig

type WorkerConfig struct {
	LogLevel             int
	BackupDir            string
	DiffRemoteMethod     string
	BackupsToKeep        int
	BackupLFS            bool
	DefaultDelay         int
	DelayEnvVar          string
	Secrets              []string
	SetupRepo            func(*repository) // Function to set up authentication on the repo
	EncryptionPassphrase string
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL