gitdr

https://gitdr.io/docs/
Admin
gitdr backs up GitHub and GitLab organizations to WORM-immutable object storage to protect...
Tokens:13,012
Snippets:111
Trust Score:2.1
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install gitdr binary (container or via Go)

Source: https://gitdr.io/docs/quickstart.md

Shows two ways to get the gitdr binary: via a container image or via go install. The container method runs the 'version' subcommand. Go 1.26+ is required.

```sh
# container
docker run --rm ghcr.io/gitdr-io/gitdr version
# or via Go (1.26+)
go install gitdr.io/gitdr/cmd/gitdr@latest
```

--------------------------------

### Install gitdr binary via Go

Source: https://gitdr.io/docs/install.md

Installs the gitdr binary via Go. Static Linux binaries for amd64 and arm64 are also available on the releases page.

```sh
go install gitdr.io/gitdr/cmd/gitdr@latest
```

--------------------------------

### Full YAML configuration example

Source: https://gitdr.io/docs/configuration.md

Complete gitdr configuration file showing all available options: source (GitHub/GitLab), destination (S3/GCS/Azure), backup, manifest, metrics, encryption, worm, and log settings. Secrets are not included here; they are provided via environment variables.

```yaml
source:
  type: github                 # github | gitlab
  baseURL: ""                  # GHES /api/v3, or self-managed GitLab URL
  repo: "octo-org/octo-repo"   # single repo; empty = all accessible (filtered)
  include: []
  exclude: []
  github:
    appID: 0
    installationID: 0
    privateKeyPath: ""         # or GITDR_GITHUB_APP_PRIVATE_KEY

destination:
  type: s3                     # s3 (AWS + S3-compatible) | gcs | azure
  s3:
    bucket: "my-worm-bucket"
    region: "us-east-1"
    endpoint: ""               # empty = AWS; e.g. MinIO http://localhost:9000
    usePathStyle: false        # true for MinIO and most S3-compatible stores
  gcs:
    bucket: ""                 # bucket with a LOCKED retention policy
  azure:
    account: ""                # uses DefaultAzureCredential
    container: ""              # container with an immutability policy
  retention:
    mode: COMPLIANCE           # COMPLIANCE (true WORM) or GOVERNANCE, S3 only
    days: 30

backup:
  concurrency: 4               # repos backed up in parallel
  resume: true                 # skip repos already backed up for the run date
  lfs: true                    # fetch LFS objects (separate .lfs.tar artifact)

manifest:
  signingKeyPath: ""           # ed25519 private key (or GITDR_MANIFEST_SIGNING_KEY)
  publicKeyPath: ""            # ed25519 public key, needed by `gitdr verify`

metrics:
  textfilePath: ""             # node_exporter textfile .prom; empty = off

encryption:
  enabled: false               # client-side envelope encryption before upload

worm:
  require: false               # true = fail closed when immutability isn't confirmed

log:
  level: info                  # debug|info|warn|error
  format: json                 # json|text

```

--------------------------------

### Run-manifest example (gitdr.manifest/v2)

Source: https://gitdr.io/docs/output.md

Example of the run-manifest (gitdr.manifest/v2) JSON output. The manifest is signed, making destination.wormImmutable a tamper-evident record of the immutability observed at write time. status can be success, failed, or skipped; artifacts[].kind can be bundle, meta, sha256, or lfs.

```json
{
  "schema": "gitdr.manifest/v2",
  "runId": "20260613T120000Z-a1b2c3d4e5f6",
  "tool": { "name": "gitdr", "version": "v0.1.0 (abc123def456)" },
  "source": { "type": "github", "host": "github.com" },
  "destination": {
    "type": "s3", "bucket": "my-worm-bucket",
    "wormMode": "COMPLIANCE", "wormImmutable": true,
    "wormDetails": "Object Lock enabled; default retention COMPLIANCE"
  },
  "startedAt": "2026-06-13T12:00:00Z",
  "finishedAt": "2026-06-13T12:03:00Z",
  "status": "success",
  "repos": [
    {
      "slug": "octo/hello",
      "status": "success",
      "artifacts": [
        { "kind": "bundle", "key": "github.com/octo/hello/2026-06-13/hello.bundle",
          "size": 12345, "sha256": "…", "retainUntil": "2026-07-13T12:00:00Z" }
      ]
    }
  ]
}
```

--------------------------------

### Install gitdr Helm chart

Source: https://gitdr.io/docs/install.md

Installs the gitdr Helm chart from an OCI artifact. The chart is cosign-signed the same way as the container image.

```sh
helm install gitdr oci://ghcr.io/gitdr-io/charts/gitdr
```

--------------------------------

### Install gitdr Helm CronJob with schedule

Source: https://gitdr.io/docs/schedule.md

Installs gitdr via Helm with a CronJob schedule set to run daily at 2 AM. Secrets mount from Kubernetes Secrets into env, config from a ConfigMap. Prefer workload identity (IRSA, GKE WI, Azure MI) on the pod's service account over static keys.

```sh
helm install gitdr oci://ghcr.io/gitdr-io/charts/gitdr \
  --set cronjob.schedule="0 2 * * *"
```

--------------------------------

### backup

Source: https://gitdr.io/docs/cli.md

Clones repositories, creates bundles, checksums them, uploads create-only, and signs the run-manifest. Prints the manifest key on success, or the full signed run-manifest with --output json.

```APIDOC
## gitdr backup

### Description
Clones, bundles, checksums, uploads create-only, and signs the run-manifest. Prints the manifest key on success, or the full signed run-manifest with --output json.

### Usage
```sh
gitdr backup --config config.yaml [--repo owner/name] [--require-worm]
```

### Flags
- **--config** (string) - Required - Path to the config YAML. Can be set via $GITDR_CONFIG. Default is $GITDR_CONFIG.
- **--repo** (string) - Optional - Back up one repo, overrides source.repo.
- **--require-worm** (boolean) - Optional - Fail closed if the destination isn't confirmed immutable.
- **--output** (string) - Optional - Result format on stdout: text or json. Default is text.
- **--log-level** (string) - Optional - Log level: debug, info, warn, error. Default from config.
- **--log-format** (string) - Optional - Log format: json or text. Default from config.

### Output
- With --output text: Prints the manifest key on success.
- With --output json: stdout is the full signed run-manifest.
```

--------------------------------

### Verify the backup with gitdr verify

Source: https://gitdr.io/docs/quickstart.md

Runs verification using the manifest key from step 7. Output 'signature valid: true, artifacts N/N ok' indicates success.

```sh
gitdr verify --config config.yaml --manifest <manifest-key-from-step-7>
```

--------------------------------

### Verify release download with cosign and sha256sum

Source: https://gitdr.io/docs/install.md

Verifies a release download by checking the checksums.txt signature and then verifying the checksums of all files. The signature covers checksums.txt, which covers everything else.

```sh
cosign verify-blob checksums.txt \
  --certificate checksums.txt.pem --signature checksums.txt.sig \
  --certificate-identity-regexp 'https://github.com/gitdr-io/gitdr' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
sha256sum -c checksums.txt --ignore-missing
```

--------------------------------

### restore

Source: https://gitdr.io/docs/cli.md

Fetches a bundle, re-checks its checksum, verifies with git bundle verify, and clones it out to a specified directory. Requires read access to the bucket and optional encryption key.

```APIDOC
## gitdr restore

### Description
Fetch a bundle, re-check its checksum, verify with git bundle verify, and clone it out.

### Usage
```sh
gitdr restore --config config.yaml \
  --repo acme/api --host github.com --date 2026-06-01 --out ./restore/api
```

### Flags
- **--config** (string) - Required - Path to the config YAML. Can be set via $GITDR_CONFIG.
- **--repo** (string) - Required - Owner/name of the repository.
- **--host** (string) - Optional - Source host. Default is github.com.
- **--date** (string) - Required - Backup date in YYYY-MM-DD format.
- **--out** (string) - Required - Output directory.
- **--output** (string) - Optional - Result format on stdout: text or json. Default text.
- **--log-level** (string) - Optional - Log level: debug, info, warn, error.
- **--log-format** (string) - Optional - Log format: json or text.

### Access
- Needs only read access to the bucket.
- If backups were encrypted, set GITDR_ENCRYPTION_KEY.
```

--------------------------------

### Run gitdr doctor and backup

Source: https://gitdr.io/docs/quickstart.md

Two commands: first checks the config, source authentication, and WORM lock; then performs the backup (clone, bundle, sha256, immutable upload, signed manifest). The backup exits non-zero on any failure.

```sh
gitdr doctor --config config.yaml     # checks config, source auth, and the WORM lock
gitdr backup --config config.yaml     # clone, bundle, sha256, immutable upload, signed manifest
```

--------------------------------

### gitdr verify command with --manifest

Source: https://gitdr.io/docs/cli.md

Verifies a backup by checking the manifest signature and re-downloading every artifact to recompute its SHA-256. Requires manifest.publicKeyPath and read access; does not need the encryption key. Non-zero exit on any signature or checksum mismatch.

```sh
gitdr verify --config config.yaml --manifest <manifest-object-key>
```

--------------------------------

### gitdr backup command

Source: https://gitdr.io/docs/cli.md

Runs a backup: clone, bundle, checksum, upload create-only, and sign the run-manifest. Use --repo to back up a single repo, and --require-worm to fail closed if the destination isn't immutable. Prints the manifest key on success; with --output json, stdout is the full signed run-manifest.

```sh
gitdr backup --config config.yaml [--repo owner/name] [--require-worm]
```

--------------------------------

### verify

Source: https://gitdr.io/docs/cli.md

Checks the manifest signature, then re-downloads every artifact and recomputes its SHA-256. Does not need the encryption key as checksums cover the stored ciphertext.

```APIDOC
## gitdr verify

### Description
Check the manifest signature, then re-download every artifact and recompute its SHA-256. Non-zero exit on any signature or checksum mismatch.

### Usage
```sh
gitdr verify --config config.yaml --manifest <manifest-object-key>
```

### Flags
- **--config** (string) - Required - Path to the config YAML. Can be set via $GITDR_CONFIG.
- **--manifest** (string) - Required (unless --drill given) - Manifest object key.
- **--drill** (string) - Optional - Drill report object key, instead of --manifest. Exactly one of --manifest or --drill must be given.
- **--output** (string) - Optional - Result format on stdout: text or json.
- **--log-level** (string) - Optional - Log level: debug, info, warn, error.
- **--log-format** (string) - Optional - Log format: json or text.

### Access
- Needs manifest.publicKeyPath and read access to the bucket.
- Does not need the encryption key; checksums cover the stored ciphertext.

### Notes
- The two forms refuse each other's documents.
- With --drill, it checks a drill report's signature and prints what the document says: which manifest it tested, whether that manifest's own signature was checked, and how many repositories came back. It reads nothing out of the bucket beyond the report and its .sig, and does not re-run the drill.
```

--------------------------------

### version

Source: https://gitdr.io/docs/cli.md

Prints the version of the gitdr CLI.

```APIDOC
## gitdr version

### Description
Prints the version of the gitdr CLI.

### Usage
```sh
gitdr version
```

### Flags
- None.
```

--------------------------------

### Object layout per run

Source: https://gitdr.io/docs/output.md

Shows the object layout for a single run, including the bundle, metadata, checksum, LFS archive, and signed manifest files. Every object is written create-only, under object-lock retention when the bucket has it.

```text
{host}/{org}/{repo}/{YYYY-MM-DD}/{repo}.bundle      git data, git bundle --all HEAD
{host}/{org}/{repo}/{YYYY-MM-DD}/{repo}.meta.json   metadata dump (gitdr.meta/v1)
{host}/{org}/{repo}/{YYYY-MM-DD}/{repo}.sha256      sha256sum line for the bundle
{host}/{org}/{repo}/{YYYY-MM-DD}/{repo}.lfs.tar     LFS objects, when present
{host}/{org}/manifests/{YYYYMMDDThhmmssZ}.manifest.json       signed run-manifest
{host}/{org}/manifests/{YYYYMMDDThhmmssZ}.manifest.json.sig   detached signature
```

--------------------------------

### List manifests with aws s3 ls

Source: https://gitdr.io/docs/restore.md

Lists the manifests in the destination bucket to identify the run to restore. Use your cloud's CLI (e.g., aws s3 ls, gcloud storage ls, az storage blob list) to list the manifests prefix.

```sh
aws s3 ls s3://my-worm-bucket/github.com/acme/manifests/
```

--------------------------------

### drill

Source: https://gitdr.io/docs/cli.md

Restores the backups and proves they carry the history they claim. Compares each repository against the bundle's own header and the ref map signed by the manifest.

```APIDOC
## gitdr drill

### Description
Restore the backups and prove they carry the history they claim. Each repository is compared twice: against the bundle's own header, and against the ref map the manifest signed when the copy was made. Non-zero exit if any repository fails to restore or comes back at a different commit.

### Usage
```sh
gitdr drill --config config.yaml --manifest <manifest-object-key> --output json
```

### Flags
- **--config** (string) - Required - Path to the config YAML. Can be set via $GITDR_CONFIG.
- **--manifest** (string) - Optional - Manifest object key to drill; defaults to the most recent. If not given, --host and --owner are required.
- **--host** (string) - Optional - Source host, e.g. github.com; needed when --manifest is not given.
- **--owner** (string) - Optional - Organisation; needed when --manifest is not given.
- **--sample** (integer) - Optional - Restore at most this many repositories, in slug order; 0 means all.
- **--workdir** (string) - Optional - Where to restore; defaults to the system temp directory.
- **--output** (string) - Optional - Result format on stdout: text or json.
- **--log-level** (string) - Optional - Log level: debug, info, warn, error.
- **--log-format** (string) - Optional - Log format: json or text.

### Notes
- Refs a clone creates nothing for (e.g. refs/merge-requests/*) are counted apart and named rather than folded into the total.
- Needs manifest.publicKeyPath, read access to the bucket, and enough disk in --workdir for the repositories it restores. It writes nothing to the destination.
```

--------------------------------

### Minimal GitHub to S3 config.yaml

Source: https://gitdr.io/docs/quickstart.md

A minimal configuration for a GitHub source to an S3 destination. The YAML sets the source repo, GitHub app credentials, destination bucket, retention policy, manifest public key path, and WORM behavior (warn on non-WORM).

```yaml
source:
  type: github
  repo: "acme/api"
  github: { appID: 123456, installationID: 7890123 }
destination:
  type: s3
  s3: { bucket: my-worm-bucket, region: us-east-1 }
  retention: { mode: COMPLIANCE, days: 30 }
manifest:
  publicKeyPath: ./manifest-public.pem
worm: { require: false } # warn on non-WORM and proceed. true means fail closed
```

--------------------------------

### Run gitdr container image

Source: https://gitdr.io/docs/install.md

Runs the gitdr container image to check the version. The image is Wolfi-based, non-root, with a read-only rootfs and no shell, and supports amd64 and arm64. Pin by digest in production rather than by tag.

```sh
docker run --rm ghcr.io/gitdr-io/gitdr:latest version
```

--------------------------------

### Create Google Cloud Storage bucket with locked retention policy

Source: https://gitdr.io/docs/worm.md

Commands to create a GCS bucket with a 30-day retention period and then lock the retention policy. The lock is irreversible.

```sh
gcloud storage buckets create gs://my-worm-bucket --location=US \
  --uniform-bucket-level-access --public-access-prevention --retention-period=30d
gcloud storage buckets update gs://my-worm-bucket --lock-retention-period
```

--------------------------------

### gitdr version command

Source: https://gitdr.io/docs/cli.md

Prints the version of the gitdr CLI.

```sh
gitdr version
```

--------------------------------

### Verify container image signature with cosign

Source: https://gitdr.io/docs/install.md

Verifies the container image signature using keyless Sigstore with cosign. The certificate identity and OIDC issuer are specified to match the GitHub Actions build.

```sh
cosign verify ghcr.io/gitdr-io/gitdr:latest \
  --certificate-identity-regexp 'https://github.com/gitdr-io/gitdr' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
```

--------------------------------

### doctor

Source: https://gitdr.io/docs/cli.md

Runs preflight checks: git on PATH, config validation, source auth, and WORM lock. Writes nothing.

```APIDOC
## gitdr doctor

### Description
Run preflight checks before the first backup and after any credential or bucket change. Checks tooling (git on PATH), validates config, checks source auth, and checks the WORM lock. Writes nothing.

### Usage
```sh
gitdr doctor --config config.yaml
```

### Flags
- **--config** (string) - Required - Path to the config YAML. Can be set via $GITDR_CONFIG.
- **--output** (string) - Optional - Result format on stdout: text or json.
- **--log-level** (string) - Optional - Log level: debug, info, warn, error.
- **--log-format** (string) - Optional - Log format: json or text.
```

--------------------------------

### Create AWS S3 bucket with Object Lock and set compliance retention

Source: https://gitdr.io/docs/worm.md

Commands to create an S3 bucket with Object Lock enabled and set a compliance retention policy of 30 days. COMPLIANCE mode is true WORM and cannot be shortened.

```sh
aws s3api create-bucket --bucket my-worm-bucket --region us-east-1 \
  --object-lock-enabled-for-bucket
aws s3api put-object-lock-configuration --bucket my-worm-bucket \
  --object-lock-configuration \
  '{"ObjectLockEnabled":"Enabled","Rule":{"DefaultRetention":{"Mode":"COMPLIANCE","Days":30}}}'
```

--------------------------------

### Verify a backup run with gitdr verify

Source: https://gitdr.io/docs/restore.md

Verifies a backup run before restoring. Checks the ed25519 signature and re-downloads every artifact to confirm its SHA-256. Exit code is non-zero on any signature or checksum mismatch; a clean run prints 'signature valid: true, artifacts N/N ok'.

```sh
gitdr verify --config config.yaml \
  --manifest github.com/acme/manifests/2026-06-01T02:00:00Z.manifest.json
```

--------------------------------

### Sanity-check restored repo with git log, fsck, for-each-ref

Source: https://gitdr.io/docs/restore.md

Sanity-checks the restored repository: view recent commits, run a full fsck, and list all refs to confirm branches and tags are present. LFS objects (if any) are in the run's .lfs.tar and must be unpacked and re-added with git lfs per the LFS docs.

```sh
cd ./restore/api
git log --oneline -5
git fsck --full
git for-each-ref            # all branches and tags present?
```

--------------------------------

### Re-home restored repo with git remote add and push --mirror

Source: https://gitdr.io/docs/restore.md

Re-homes the restored repository to a new VCS host. Adds a new remote and pushes with --mirror to push all branches and tags. Re-create the org or project on the new host first; gitdr restores git data, not org settings.

```sh
git remote add new https://new-host/acme/api.git
git push --mirror new
```

--------------------------------

### gitdr command syntax

Source: https://gitdr.io/docs/cli.md

Shows the general command structure for gitdr. All commands follow this pattern, with logs to stderr, results to stdout, and non-zero exit on failure.

```bash
gitdr <command> [flags]
```

--------------------------------

### gitdr drill command

Source: https://gitdr.io/docs/cli.md

Restores backups and proves they carry the history they claim. Compares each repository against the bundle header and the signed ref map. Use --output json for structured output. Needs manifest.publicKeyPath, read access, and enough disk in --workdir. Non-zero exit if any repository fails to restore or differs.

```sh
gitdr drill --config config.yaml --manifest <manifest-object-key> --output json
```

--------------------------------

### Generate ed25519 manifest signing key pair

Source: https://gitdr.io/docs/quickstart.md

Creates the private and public key pair used to sign manifests each run. Keep the private key secret and off the runner if possible; verify only needs the public key.

```sh
openssl genpkey -algorithm ed25519 -out manifest-signing.pem
openssl pkey -in manifest-signing.pem -pubout -out manifest-public.pem
```

--------------------------------

### gitdr doctor command

Source: https://gitdr.io/docs/cli.md

Preflight check: verifies git is on PATH, validates config, checks source auth, and checks the WORM lock. Writes nothing. Run before the first backup and after any credential or bucket change.

```sh
gitdr doctor --config config.yaml
```

--------------------------------

### Restore a repository with gitdr restore

Source: https://gitdr.io/docs/restore.md

Restores a single repository from a backup run. Downloads the bundle, re-checks its checksum, runs 'git bundle verify', and clones it into --out. If encryption was used, set GITDR_ENCRYPTION_KEY first.

```sh
gitdr restore --config config.yaml \
  --host github.com \
  --repo acme/api \
  --date 2026-06-01 \
  --out ./restore/api
```

--------------------------------

### Pipe backup JSON output to jq

Source: https://gitdr.io/docs/output.md

Command to pipe the backup command's JSON output to jq to extract the status field. Logs stay on stderr, so this works without interference.

```bash
gitdr backup --output json | jq .status
```

--------------------------------

### gitdr verify command with --drill

Source: https://gitdr.io/docs/cli.md

Verifies a drill report's signature and prints what the document claims: which manifest it tested, whether that manifest's signature was checked, and how many repositories came back. Reads only the report and its .sig; does not re-run the drill. The two forms refuse each other's documents.

```sh
gitdr verify --config config.yaml --drill <drill-report-object-key>
```

--------------------------------

### Export environment secrets for gitdr

Source: https://gitdr.io/docs/quickstart.md

Commands to export secrets as environment variables. The private key path is also set for the GitHub app. These are the only way to pass secrets; they must not appear in the YAML.

```sh
export GITDR_GITHUB_APP_PRIVATE_KEY="$(cat github-app.pem)"
export GITDR_MANIFEST_SIGNING_KEY="$(cat manifest-signing.pem)"
export AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=...   # or use an instance role
```

--------------------------------

### Prometheus alert for stale gitdr backup

Source: https://gitdr.io/docs/schedule.md

Prometheus rule that alerts when the last successful run is older than 2 days. Catches every failure mode including crashed jobs, wedged runners, revoked credentials, and full disks. Alert on staleness, not on job failure.

```yaml
- alert: GitBackupStale
  expr: time() - gitdr_last_successful_run > 86400 * 2
  annotations:
    summary: "git org backup hasn't succeeded in 2 days"
```

--------------------------------

### gitdr textfile metric for node_exporter

Source: https://gitdr.io/docs/schedule.md

When metrics.textfilePath is set, gitdr writes a .prom file for node_exporter's textfile collector. The metric records the Unix timestamp of the last successful run.

```text
gitdr_last_successful_run <unix-timestamp>
```
Tokens:
Raw