Automatically sync documentation and configuration files across multiple GitHub repositories using happi-file-sync-gh, a GitHub Action that makes keeping files in sync suck less.

Have you ever maintained multiple GitHub repositories that share common documentation or configuration files? Keeping these files in sync is a tedious and error-prone task. What if there was a way to automatically update these files across repositories whenever changes are made?

Well there is probably loads of solutions out there, happy-file-sync-gh is mine.

The Problem: Documentation Drift

One of the big challenges in maintaining multiple repositories is keeping shared documentation and configuration files synchronized. Whether it's:

• README files that need to be consistent across related projects
• Shared configuration files that define common settings
• Documentation tools that source content from multiple locations
• License files that need to be kept up to date

Manual synchronization is time-consuming and often leads to documentation drift. I mean, it's not fun, your're being pushed to deliver more tickets and future you isn't here to give you an earful. The tendency to developers "forgetting" to push the information to where it needs to be seems to be a symptom of a busy engineering department that has forgotten about delayed gratification. If we can make the process hands off, that it's "forgettable" becomes less of a problem.

The Solution: Automated File Synchronization

happi-file-sync-gh automatically creates pull requests to sync files between repositories whenever changes are detected. It's not high-brow, but it works well enough for out use case. Here's the detail:

1. You specify which files to monitor and where they should be synced
2. When changes are made to these files, the action automatically:
   • Creates a new branch in the target repository
   • Copies the updated file(s)
   • Creates a pull request with the changes

Getting Started

Setting up happi-file-sync-gh is straightforward. Here's a basic example:

1. Create a workflow file in your repository:

name: Sync Files
on:
  pull_request_target:
    types: [closed]
    branches:
      - main
    paths:
      - "README.md"
  workflow_dispatch:

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: happi-file-sync-gh@v1
        with:
          github-token: $
          file-mappings: |
            {
              "readme": {
                "sourcePath": ".",
                "sourceFilename": "README.md",
                "destRepo": "other-org/other-repo",
                "destPath": ".",
                "destFilename": "README.md"
              }
            }

Advanced Features

Smart Branch Handling

The action provides three strategies for handling existing branches:

1. Update Mode (default): Updates existing pull requests, keeping everything in one place
2. Create New: Generates unique branches with timestamps for separate pull requests
3. Fail Fast: Stops if a branch exists, giving you manual control

Multiple File Mappings

You can sync multiple files to different repositories in a single configuration:

file-mappings: |
  {
    "docs": {
      "sourcePath": "docs",
      "sourceFilename": "API.md",
      "destRepo": "api-docs-repo",
      "destPath": "reference",
      "destFilename": "latest.md"
    },
    "config": {
      "sourcePath": "config",
      "sourceFilename": "eslint.json",
      "destRepo": "shared-configs",
      "destPath": "eslint",
      "destFilename": "base.json"
    }
  }

Roadmap

The project is actively being developed nudged along when my team complain enough. That being said there are several planned improvements that have been identified:

• Support syncing entire directories
• Improve logging with operation summaries
• Clean up error outputs for better debugging
• Improve error handling and exit codes