README
¶
plakar-integration-github
A plakar importer and exporter for GitHub — backs up and restores repositories (git content and files) and issues for both personal accounts and organizations.
Features
- Backs up full git repository content as a tarball (via GitHub archive API)
- Backs up issues as individual JSON records (pull requests excluded)
- Supports personal accounts and organizations (auto-detected)
- Backs up a single repo or all repos under an owner
- Restores repositories to GitHub: creates the repo if missing, pushes git content, recreates issues
- Skips duplicate issues on restore (use
force=trueto override) - Authenticates via GitHub PAT or fine-grained PAT
Requirements
- plakar v1.0.6+
Installation
Download the .ptar package for your platform from the latest release and install it:
# Replace <version>, <os>, and <arch> with the appropriate values (e.g. v0.0.1, linux, amd64)
curl -fsSL -O https://github.com/damoun/plakar-integration-github/releases/download/<version>/integration-github_<version>_<os>_<arch>.ptar
plakar pkg add ./integration-github_<version>_<os>_<arch>.ptar
Build from source
git clone https://github.com/damoun/plakar-integration-github
cd plakar-integration-github
make install
Token Permissions
Classic PAT
Scope: repo (full repository access).
Fine-grained PAT
| Permission | Backup | Restore |
|---|---|---|
| Contents | read | write |
| Issues | read | write |
| Metadata | read | read |
| Workflows | — | write |
The Workflows permission is required to restore .github/workflows/ files. Without it, workflow files are skipped and all other content is still restored.
Configuration
Backup (importer)
plakar source add mygithub "github://owner[/repo]" token=ghp_xxx
| Key | Required | Description |
|---|---|---|
token |
yes | GitHub PAT |
owner |
no | GitHub username or org (extracted from location if unset) |
repo |
no | Specific repo name (defaults to all repos for the owner) |
Restore (exporter)
plakar destination add mydest "github://owner[/repo]" token=ghp_xxx
| Key | Required | Description |
|---|---|---|
token |
yes | GitHub PAT with write access |
owner |
no | Destination owner (extracted from location if unset) |
repo |
no | Override destination repo name (single-repo restores only) |
force |
no | Set true to recreate issues even if they already exist |
Usage
Backup all repos for a user or org:
plakar source add mygithub "github://damoun" token=ghp_xxx
plakar at /path/to/repo backup @mygithub
Backup a single repository:
plakar source add myrepo "github://damoun/plakar-integration-github" token=ghp_xxx
plakar at /path/to/repo backup @myrepo
Restore a snapshot to GitHub:
plakar destination add mydest "github://damoun/new-repo" token=ghp_xxx
plakar at /path/to/repo restore -latest -to @mydest
Restore and rename the repo:
plakar destination add mydest "github://damoun" token=ghp_xxx repo=new-name
plakar at /path/to/repo restore -latest -to @mydest
Backup Layout
Each repository produces three record types:
{repo}/manifest.json # Repository metadata (JSON)
{repo}/git.tar.gz # Full git archive (tarball from GitHub API)
{repo}/issues/{id}.json # One file per issue (pull requests skipped)
License
ISC — see LICENSE.
Documentation
¶
Index ¶
- func IsOrg(ctx context.Context, client *github.Client, owner string) (bool, error)
- func ListIssues(ctx context.Context, client *github.Client, owner, repo string) ([]*github.Issue, error)
- func ListRepos(ctx context.Context, client *github.Client, owner string, org bool) ([]*github.Repository, error)
- func NewExporter(ctx context.Context, _ *kloset_exporter.Options, _ string, ...) (kloset_exporter.Exporter, error)
- func NewGitHubClient(_ context.Context, token string) *github.Client
- func NewImporter(ctx context.Context, _ *importer.Options, _ string, config map[string]string) (importer.Importer, error)
- func ParseLocation(loc string) (owner, repo string)
- type GitHubExporter
- func (e *GitHubExporter) Close(_ context.Context) error
- func (e *GitHubExporter) CreateDirectory(_ context.Context, _ string) error
- func (e *GitHubExporter) CreateLink(_ context.Context, _, _ string, _ kloset_exporter.LinkType) error
- func (e *GitHubExporter) Root(_ context.Context) (string, error)
- func (e *GitHubExporter) SetPermissions(_ context.Context, _ string, _ *objects.FileInfo) error
- func (e *GitHubExporter) StoreFile(ctx context.Context, pathname string, fp io.Reader, _ int64) error
- type GitHubImporter
- func (g *GitHubImporter) Close(_ context.Context) error
- func (g *GitHubImporter) Flags() location.Flags
- func (g *GitHubImporter) Origin(_ context.Context) (string, error)
- func (g *GitHubImporter) Root(_ context.Context) (string, error)
- func (g *GitHubImporter) Scan(ctx context.Context) (<-chan *importer.ScanResult, error)
- func (g *GitHubImporter) Type(_ context.Context) (string, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ListIssues ¶
func ListIssues(ctx context.Context, client *github.Client, owner, repo string) ([]*github.Issue, error)
ListIssues returns all open and closed issues for the given repo.
func ListRepos ¶
func ListRepos(ctx context.Context, client *github.Client, owner string, org bool) ([]*github.Repository, error)
ListRepos returns all repositories for the given owner (user or org).
func NewExporter ¶
func NewExporter(ctx context.Context, _ *kloset_exporter.Options, _ string, config map[string]string) (kloset_exporter.Exporter, error)
NewExporter is the constructor called by the plakar SDK.
func NewGitHubClient ¶
NewGitHubClient returns an authenticated GitHub client.
func NewImporter ¶
func NewImporter(ctx context.Context, _ *importer.Options, _ string, config map[string]string) (importer.Importer, error)
NewImporter is the constructor called by the plakar SDK.
func ParseLocation ¶
ParseLocation extracts owner and optional repo from a location string like "github://owner/repo" or "github://owner".
Types ¶
type GitHubExporter ¶
type GitHubExporter struct {
// contains filtered or unexported fields
}
GitHubExporter implements the plakar exporter interface for GitHub.
func NewGitHubExporter ¶
func NewGitHubExporter(client *github.Client, owner, repoOverride string) *GitHubExporter
NewGitHubExporter creates an exporter directly from an existing client (used in tests).
func (*GitHubExporter) CreateDirectory ¶
func (e *GitHubExporter) CreateDirectory(_ context.Context, _ string) error
func (*GitHubExporter) CreateLink ¶
func (e *GitHubExporter) CreateLink(_ context.Context, _, _ string, _ kloset_exporter.LinkType) error
func (*GitHubExporter) SetPermissions ¶
type GitHubImporter ¶
type GitHubImporter struct {
// contains filtered or unexported fields
}
GitHubImporter implements the plakar importer interface for GitHub.
func NewGitHubImporter ¶
func NewGitHubImporter(client *github.Client, owner, repo string) *GitHubImporter
func (*GitHubImporter) Flags ¶
func (g *GitHubImporter) Flags() location.Flags
Flags returns the location flags for this importer (0 = remote API).
func (*GitHubImporter) Scan ¶
func (g *GitHubImporter) Scan(ctx context.Context) (<-chan *importer.ScanResult, error)
Scan returns a channel of ScanResults covering all repos, their manifests, git archives, and issues.
Source Files
Directories