Backing Up GitHub Repositories on Synology NAS with gickup

GitHub is an operational platform, not a backup strategy. For a long time, that distinction often felt theoretical because GitHub is - usually - highly available and because Git itself already distributes history well. The gap becomes visible once repositories are treated as regulated business assets instead of convenient hosting locations.

Repository backups matter in several real-world situations. European companies may need retention and evidencing rules that go beyond “the platform usually works”. Internal governance teams may require vendor-risk controls and offline recovery paths. Platform outages, even short ones, can block builds and hotfixes. Account suspensions or false-positive trust and safety events can temporarily cut off access. Open source dependencies can also disappear, whether through abandonment, license conflicts or repository deletion.

A backup does not solve every platform risk, but it changes the failure mode. Instead of “the code is only available behind one provider boundary”, the situation becomes “the code can be restored elsewhere”.

Why GitHub repository backups matter

The strongest argument for repository backups is rarely technical convenience. It is operational and organizational control.

For regulated organizations, source code is often part of the audit and retention surface. That does not mean every repository requires the same treatment, but it does mean that “GitHub keeps it for us” is usually not sufficient as a formal control. The same is true for internal governance policies that require exit strategies for critical SaaS platforms.

There is also a more practical engineering argument. Even when a platform outage lasts only a few hours, development and release processes can stall immediately. That may not matter for hobby projects. It matters a lot for teams that need to ship hotfixes, rebuild older releases or prove what existed at a specific point in time.

The account-risk angle is often underestimated as well. Platform moderation systems are not perfect and false positives do happen across many online services. A temporary lockout is annoying for a private profile. For a company, it can become an operational incident.

Finally, repository backups are valuable beyond first-party code. Important upstream dependencies, internal forks and niche open source projects sometimes disappear without much warning. Keeping strategic mirrors of those repositories reduces a surprising amount of supply-chain fragility.

Common approaches to repository backup

Several approaches exist and each solves a slightly different problem.

Using a second Git platform as a mirror is a good option when the primary goal is provider independence. Enterprise backup software is better suited when auditing, policy management and centralized reporting matter more than operational simplicity. Custom PowerShell automation around git clone --mirror works well for teams that want full control over authentication, filtering and retention. Git itself already provides the essential mechanism; the surrounding script mostly adds selection logic, scheduling and reporting.

For small and medium environments, a lightweight tool such as gickup is often the pragmatic middle ground. It keeps the backup model close to Git, adds provider-aware repository collection and avoids building a custom automation stack from scratch.

The important distinction is scope. A Git mirror protects repository contents, branches, tags and refs. It does not automatically protect GitHub-specific metadata such as issues, pull request reviews, branch protection rules, Actions secrets, Discussions or Packages. That boundary is still acceptable for many disaster recovery scenarios, but it should be explicit from the start.

Why a Synology NAS plus gickup is a practical middle ground

A Synology NAS is often already present in small companies, engineering teams or home lab environments. That makes it an attractive backup target: persistent storage exists, Docker or Container Manager is available and operational overhead stays low.

gickup fits this setup well because it combines repository discovery, scheduled execution and Git mirror creation. Under the hood, the resulting backup is still based on standard Git semantics. The important flags in the destination section are bare: true and mirror: true, which produce real mirror repositories instead of ordinary working copies. That matters because mirror repositories preserve all refs and are suitable for direct restoration with git push --mirror.

Compared to a handwritten script around git clone --mirror, the main advantage is not magic. It is repeatability. Repository selection, authentication, scheduling and logging live in one small configuration file and can be adjusted without rebuilding the entire automation.

This approach is also easy to explain internally. The Synology NAS provides durable local storage. Docker keeps the runtime isolated. gickup pulls from GitHub on a fixed schedule and writes plain Git mirrors. There is very little hidden complexity.

Example layout on Synology

A simple layout on the NAS can look like this:

1/volume7/docker/gickup/
2  docker-compose.yml
3  conf.yml
4  logs/

The repository mirrors themselves are stored separately under /volume7/backups/code. That separation keeps configuration, logs and backup data independent from each other and makes storage management easier later.

Docker Compose setup

The container definition is deliberately small:

 1services:
 2  gickup:
 3    image: buddyspencer/gickup:latest
 4    container_name: gickup
 5    restart: unless-stopped
 6    environment:
 7      TZ: ${TZ:-Europe/Berlin}
 8    volumes:
 9      - ./conf.yml:/gickup/conf.yml:ro
10      - /volume7/backups/code:/repos
11      - ./logs:/logs
12    command: ["/gickup/conf.yml"]

This setup mounts the configuration file read-only into the container, stores the generated mirrors under /repos inside the container and maps logs to a local directory on the NAS. The time zone is passed through as an environment variable because scheduled jobs and log timestamps become much easier to reason about once they match the local operating context.

From an operational perspective, the volume mapping to /volume7/backups/code is the important part. That path is the actual backup target. The docker-compose.yml file itself is just the runtime wrapper around it.

Sample gickup configuration

One operational note is worth making before the configuration itself: the sample below keeps token placeholders inline for readability. In production, those values should not live in version control. Fine-grained personal access tokens with read-only permissions are the safer default and on organizational repositories they should be approved with the narrowest repository scope possible.

Creating the GitHub fine-grained access token

For gickup, a fine-grained personal access token is usually the best starting point because it can be limited to one resource owner and to exactly the repositories that should be mirrored. That owner restriction is also the reason why the sample configuration uses separate tokens for the personal account and for repositories that belong to another user or organization.

The token can be created directly in GitHub with a short setup flow:

1. Verify the GitHub account email address if it has not been verified yet.
2. Open the profile menu in GitHub and navigate to Settings.
3. Open Developer settings.
4. Under Personal access tokens, open Fine-grained tokens.
5. Select Generate new token.
6. Enter a descriptive token name, set a short expiration and optionally add a description such as Read-only backup token for gickup.
7. Under Resource owner, select the personal account or organization that owns the repositories to be backed up.
8. If the selected organization requires approval for fine-grained tokens, add a short business justification and wait for approval.
9. Under Repository access, choose the smallest possible scope. In most backup scenarios, Only select repositories is the better choice than broad account-wide access.
10. Under Permissions, keep the token minimal. For plain repository mirror backups, Contents: Read-only is generally the important repository permission.
11. Generate the token and copy it immediately, because GitHub will not display the full value again afterwards.

Two practical details are easy to miss. First, a fine-grained token is bound to a single resource owner, so one token cannot be reused across unrelated organizations. Second, a token that is still in pending state for an organization will not work for private organizational repositories until it is approved.

 1# Simple Synology-friendly gickup config.
 2# Uses fine-grained GitHub tokens and backs up selected personal repositories
 3# plus explicitly listed repositories that need separate access.
 4
 5source:
 6  github:
 7    - token: Fine-grained token for user access here
 8      user: BenjaminAbt
 9      include:
10        - nubrowse
11        - StrongOf
12        - Unio
13        - SustainableCode
14        - MyPrivateRepoHere
15
16  any:
17    - url: https://github.com/mycsharp/private-repo-here.git
18      token: Fine-grained token for org access here
19      user: mycsharp
20
21destination:
22  local:
23    - path: /repos
24      structured: true
25      zip: false
26      bare: true
27      mirror: true
28      lfs: false
29
30# Schedule: Every Monday at 04:00
31cron: "0 04 * * 1"
32
33log:
34  timeformat: 2006-01-02 15:04:05
35  file-logging:
36    dir: /logs
37    file: gickup.log
38    maxage: 14

The sample is selective by design. Not every repository needs identical treatment and in many environments it is better to back up a clearly curated set of business-critical repositories than to mirror everything blindly.

What this configuration does

The source.github block backs up selected repositories from the BenjaminAbt account. The include list is useful when a smaller set of repositories matters more than a broad account-wide export.

The source.any block covers direct repository URLs and allows a second token to be used where access boundaries differ. That is useful for private repositories outside the main account or for repositories where a separate organizational token is required.

On the destination side, structured: true keeps the local folder layout organized, zip: false avoids creating an additional archive layer and bare: true together with mirror: true produces restorable mirror repositories instead of checked-out working trees.

The lfs: false setting is intentional in the sample because it keeps storage demand lower and fits repositories that do not rely on Git LFS. If important repositories use Git LFS, that flag should be reviewed carefully. A mirror without the required large file objects may still be incomplete for practical restoration.

The weekly cron expression is a reasonable default for many teams. Repositories that change constantly or support critical delivery paths may justify a more frequent schedule. The right interval is driven by acceptable data loss, not by technical possibility.

Deployment on Synology

On a Synology system, the deployment can stay very simple. A project directory is created on the NAS, docker-compose.yml and conf.yml are placed into that directory and the stack is deployed through Container Manager or a regular Docker Compose workflow.

The first validation should focus on two things: whether repository mirrors appear under /volume7/backups/code and whether logs/gickup.log shows successful authentication and clone or update activity. A backup job that was never checked is still only a hypothesis.

If immediate validation is required, a temporary short test schedule is often easier than waiting for the weekly production window. Once the first successful run is confirmed, the cron expression can be set back to the intended maintenance slot.

Restore expectations

The main value of this setup is that restoration remains plain Git.

When a repository needs to be recreated on another Git platform or in another GitHub owner scope, a generated mirror can be pushed back with the standard mirror workflow:

1git clone --mirror <path-to-generated-mirror>
2
3cd <repository>.git
4
5git push --mirror https://github.com/example/restored-repository.git

That is precisely why mirror: true matters. The backup is not a proprietary export format. It is still a Git repository, just in bare mirror form.

Regular restore tests are worth the effort. A small periodic validation on a non-production target repository is enough to prove that authentication, refs and repository integrity still behave as expected.

Limitations that should stay explicit

This setup is strong for repository-level backup, but it is not a complete GitHub tenant backup.

Issues, pull request review state, branch protection rules, GitHub Actions secrets, Discussions, Packages and other platform metadata are outside the scope of a plain Git mirror. If those elements are part of a compliance or recovery requirement, additional tooling is needed.

There is another important boundary: a local NAS mirror protects against provider-side loss, account lockout and repository disappearance, but not yet against local hardware failure or site loss. In other words, this is not a full 3-2-1 backup strategy on its own. If the repositories are important, /volume7/backups/code should itself be replicated offsite, for example through a second NAS, object storage or another backup product.

That layered view is often the right one: gickup creates the repository mirrors and a second backup mechanism protects the NAS storage that holds those mirrors.

Conclusion

For many teams, GitHub has become critical infrastructure. That makes repository backup less of a niche concern and more of a basic resilience control. Legal obligations, internal governance, outage preparation, account-risk mitigation and dependency preservation all point in the same direction: source code should not exist in only one place.

A Synology NAS plus gickup is a practical answer when the goal is a low-maintenance, Git-native repository backup. It is easy to explain, easy to operate and built on standard Git behavior instead of proprietary restore logic. As long as the scope is understood clearly and the resulting backup is itself protected, it provides a solid safety net with very little operational weight.