Netpicker

External Git repository sync

This feature allows automatic syncing of Git repositories to external Git providers (e.g., GitHub, GitLab). When enabled, any push to the local repository will automatically be mirrored to the configured external repository.

Prerequisites

  1. Create the target repositories on your external Git provider (e.g., GitHub)
  2. Generate a Personal Access Token (PAT) with appropriate repository permissions
  • For GitHub: Create a token at Settings > Developer settings > Personal access tokens
  • Required permissions: ‘repo’ (Full control of private repositories)

Configuration

Add the following environment variables to your Docker Compose file:

  gitd:
    image: netpicker/gitd
    environment:
      # Enable external push functionality
      - ENABLE_EXTERNAL_PUSH=true
      # GitHub username
      - EXTERNAL_GIT_USERNAME=your-github-username
      # Personal Access Token
      - EXTERNAL_GIT_TOKEN=ghp_your_personal_access_token
      # Repository mappings (JSON format)
      - EXTERNAL_GIT_MAPPINGS='{"rules/default.git":"https://github.com/your-org/rules-repo.git","configs/default.git":"https://github.com/your-org/configs-repo.git"}'

Environment Variables Explained

  • ENABLE_EXTERNAL_PUSH: Set to ‘true’ to enable the mirroring functionality
  • EXTERNAL_GIT_USERNAME: Your GitHub username
  • EXTERNAL_GIT_TOKEN: Your GitHub Personal Access Token
  • EXTERNAL_GIT_MAPPINGS: JSON object mapping local repository paths to external repository URLs
  • Keys: Local repository paths, either rules/$tenant-name or configs/$tenant-name
  • Values: External repository URLs

How It Works

  1. When a push is made to a local repository, the post-receive hook checks if external pushing is enabled
  2. If enabled, it looks up the external repository URL from the mappings
  3. If a mapping exists, it:
  • Adds the external repository as a remote
  • Pushes the changes to the external repository

Security Notes

  • Ensure your Personal Access Token has the minimum required permissions
  • The token should be kept confidential and rotated periodically

Troubleshooting

  • Verify that the external repositories exist and are accessible
  • Ensure the Personal Access Token has sufficient permissions
  • Check that the repository mappings are valid JSON and the paths match your local repository structure