Documentation
¶
Overview ¶
Package github provides a GitHub repository backend for omnistorage.
This backend provides read and write access to files in GitHub repositories. It uses the GitHub Contents API to read and write file contents.
Basic usage:
cfg := github.Config{
Owner: "grokify",
Repo: "omnistorage",
Token: os.Getenv("GITHUB_TOKEN"),
}
backend, err := github.New(cfg)
Index ¶
- Variables
- type Backend
- func (b *Backend) Close() error
- func (b *Backend) Copy(ctx context.Context, src, dst string) error
- func (b *Backend) Delete(ctx context.Context, filePath string) error
- func (b *Backend) Exists(ctx context.Context, filePath string) (bool, error)
- func (b *Backend) Features() omnistorage.Features
- func (b *Backend) List(ctx context.Context, prefix string) ([]string, error)
- func (b *Backend) Mkdir(ctx context.Context, filePath string) error
- func (b *Backend) Move(ctx context.Context, src, dst string) error
- func (b *Backend) NewBatch(ctx context.Context, message string) (*Batch, error)
- func (b *Backend) NewReader(ctx context.Context, filePath string, opts ...omnistorage.ReaderOption) (io.ReadCloser, error)
- func (b *Backend) NewWriter(ctx context.Context, filePath string, opts ...omnistorage.WriterOption) (io.WriteCloser, error)
- func (b *Backend) Rmdir(ctx context.Context, filePath string) error
- func (b *Backend) Stat(ctx context.Context, filePath string) (omnistorage.ObjectInfo, error)
- type Batch
- type BatchOperation
- type BatchOperationType
- type CommitAuthor
- type Config
Constants ¶
This section is empty.
Variables ¶
var ( ErrOwnerRequired = errors.New("github: owner is required") ErrRepoRequired = errors.New("github: repo is required") ErrTokenRequired = errors.New("github: token is required") )
Config errors.
Functions ¶
This section is empty.
Types ¶
type Backend ¶
type Backend struct {
// contains filtered or unexported fields
}
Backend implements omnistorage.ExtendedBackend for GitHub repositories.
func (*Backend) Delete ¶
Delete removes a file from the repository. This creates a new commit that deletes the file. Returns nil if the file does not exist (idempotent).
func (*Backend) Features ¶
func (b *Backend) Features() omnistorage.Features
Features returns the capabilities of the GitHub backend.
func (*Backend) List ¶
List lists paths with the given prefix. Uses GitHub Trees API: GET /repos/{owner}/{repo}/git/trees/{branch}?recursive=1
func (*Backend) NewBatch ¶
NewBatch creates a new batch for accumulating file operations. The message is used as the commit message when Commit is called.
func (*Backend) NewReader ¶
func (b *Backend) NewReader(ctx context.Context, filePath string, opts ...omnistorage.ReaderOption) (io.ReadCloser, error)
NewReader creates a reader for the given path. Uses GitHub Contents API: GET /repos/{owner}/{repo}/contents/{path}?ref={branch}
func (*Backend) NewWriter ¶
func (b *Backend) NewWriter(ctx context.Context, filePath string, opts ...omnistorage.WriterOption) (io.WriteCloser, error)
NewWriter creates a writer for the given path. The content is buffered and committed to GitHub when Close() is called. Each Close() creates a new commit in the repository.
func (*Backend) Stat ¶
func (b *Backend) Stat(ctx context.Context, filePath string) (omnistorage.ObjectInfo, error)
Stat returns metadata about an object.
type Batch ¶
type Batch struct {
// contains filtered or unexported fields
}
Batch accumulates multiple file operations to be committed atomically. Use NewBatch to create a batch, then call Write/Delete to queue operations, and finally Commit to apply all changes in a single commit.
func (*Batch) Commit ¶
Commit applies all queued operations in a single commit. This uses the Git Data API (Trees and Commits) to create an atomic commit.
The process: 1. Get the current commit SHA from the branch reference 2. Get the current tree SHA from that commit 3. Create blobs for all new/updated file contents 4. Create a new tree with the changes 5. Create a new commit pointing to the new tree 6. Update the branch reference to the new commit
func (*Batch) Delete ¶
Delete queues a file delete operation. The file will be deleted when Commit is called. If the file doesn't exist at commit time, it is ignored (no error).
type BatchOperation ¶
type BatchOperation struct {
Type BatchOperationType
Path string
Content []byte
}
BatchOperation represents a single operation in a batch.
type BatchOperationType ¶
type BatchOperationType int
BatchOperationType indicates the type of batch operation.
const ( // BatchOpWrite represents a write (create/update) operation. BatchOpWrite BatchOperationType = iota // BatchOpDelete represents a delete operation. BatchOpDelete )
type CommitAuthor ¶
CommitAuthor represents the author of a commit.
type Config ¶
type Config struct {
// Owner is the repository owner (user or organization). Required.
Owner string
// Repo is the repository name. Required.
Repo string
// Branch is the branch to read from. Default: "main".
Branch string
// Token is the GitHub personal access token. Required.
// Needs "repo" scope for private repos, or "public_repo" for public repos.
Token string
// BaseURL is the GitHub API base URL. Default: "https://api.github.com/".
// Set this for GitHub Enterprise (e.g., "https://github.example.com/api/v3/").
BaseURL string
// UploadURL is the GitHub upload URL. Default: "https://uploads.github.com/".
// Set this for GitHub Enterprise.
UploadURL string
// CommitMessage is the commit message template for write operations.
// Use {path} as a placeholder for the file path.
// Default: "Update {path} via omnistorage"
CommitMessage string
// CommitAuthor is the author for commits. If nil, uses the authenticated user.
CommitAuthor *CommitAuthor
}
Config holds configuration for the GitHub backend.
func ConfigFromEnv ¶
func ConfigFromEnv() Config
ConfigFromEnv creates a Config from environment variables. Environment variables:
- OMNISTORAGE_GITHUB_OWNER or GITHUB_OWNER: repository owner
- OMNISTORAGE_GITHUB_REPO or GITHUB_REPO: repository name
- OMNISTORAGE_GITHUB_BRANCH: branch name (default: "main")
- OMNISTORAGE_GITHUB_TOKEN or GITHUB_TOKEN: personal access token
- OMNISTORAGE_GITHUB_BASE_URL or GITHUB_API_URL: API base URL
- OMNISTORAGE_GITHUB_UPLOAD_URL: upload URL
- OMNISTORAGE_GITHUB_COMMIT_MESSAGE: commit message template
- OMNISTORAGE_GITHUB_COMMIT_AUTHOR_NAME: commit author name
- OMNISTORAGE_GITHUB_COMMIT_AUTHOR_EMAIL: commit author email
func ConfigFromMap ¶
ConfigFromMap creates a Config from a string map. Supported keys:
- owner: repository owner (required)
- repo: repository name (required)
- branch: branch name (default: "main")
- token: GitHub personal access token (required)
- base_url: GitHub API base URL (for GitHub Enterprise)
- upload_url: GitHub upload URL (for GitHub Enterprise)
- commit_message: commit message template (default: "Update {path} via omnistorage")
- commit_author_name: commit author name
- commit_author_email: commit author email
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns a Config with sensible defaults.
func (*Config) FormatCommitMessage ¶
FormatCommitMessage formats the commit message with the given path.
Source Files