set-docsync

Interactive CLI to set up GitHub Actions workflows that sync documentation between repositories. Supports push (on commit), pull (on schedule), or both — with multi-repo targets.

Quick Start

# Interactive mode
npx set-docsync

# Non-interactive push
npx set-docsync push --src docs/ --to org/wiki:docs/website/@main

# Non-interactive pull
npx set-docsync pull --from org/website:docs/:docs/website/@main

# Multiple targets
npx set-docsync push --src docs/ --to org/wiki:docs/web/ --to org/docs:api/

Run inside any GitHub repository. Generates .github/workflows/docsync.yml.

CLI Options

Usage: set-docsync [push|pull] [options]

No arguments    Interactive mode

Options:
  --src <path>        Source docs path (default: docs/)
  --branch <branch>   Source/commit branch (default: main)
  --to <target>       Push target — owner/repo[:dst_path][@branch]  (repeatable)
  --from <source>     Pull source — owner/repo[:src_path[:dst_path]][@branch]  (repeatable)
  --clean             Clean target directory before push (default: true)
  --no-clean          Don't clean target directory
  -h, --help          Show help

Sync Modes

| Mode | Trigger | Use case | |------|---------|----------| | Push | On commit to source repo | Source repo pushes docs to one or more target repos | | Pull | Daily cron (00:00 UTC) | Wiki/hub repo pulls docs from one or more source repos | | Both | Push + cron | Repo is both a source and a destination |

Each mode supports multiple targets/sources in a single workflow.

Example

$ npx set-docsync

🔄 set-docsync — Configure docs sync workflow

Detected repo: myorg/website (main)

? Sync mode Push — push docs to target repo(s) on commit
? Source docs path (relative to repo root) docs/
? Source branch main
? Target repo owner myorg
? Target repo name wiki
? Target path (files will be copied here) docs/website/
? Target branch main
? Clean target directory before sync? Yes
? Add another push target? No

Configuration summary:
  Mode: push

  Push:
    Source path:   docs/
    Source branch: main
    Target 1: myorg/wiki:docs/website/ (main) clean=true

? Generate workflow file? Yes

✅ Written to /path/to/website/.github/workflows/docsync.yml

Generated Workflows

Push (multi-target via matrix)

name: Sync Docs

on:
  push:
    branches: ["main"]
    paths:
      - "docs/**"
  workflow_dispatch:

jobs:
  push-docs:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - dst_owner: "myorg"
            dst_repo_name: "wiki"
            dst_path: "/docs/website/"
            dst_branch: "main"
            clean: true
    steps:
      - uses: actions/checkout@v4
      - uses: andstor/copycat-action@v3
        with:
          personal_token: ${{ secrets.PAT_DOCSYNC }}
          src_path: "/docs/."
          dst_path: ${{ matrix.dst_path }}
          dst_owner: ${{ matrix.dst_owner }}
          dst_repo_name: ${{ matrix.dst_repo_name }}
          dst_branch: ${{ matrix.dst_branch }}
          src_branch: "main"
          clean: ${{ matrix.clean }}

Pull (multi-source, sequential)

name: Sync Docs

on:
  schedule:
    - cron: "0 0 * * *"
  workflow_dispatch:

jobs:
  pull-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/checkout@v4
        with:
          repository: "myorg/website"
          ref: "main"
          token: ${{ secrets.PAT_DOCSYNC }}
          path: _src_0
          sparse-checkout: "docs"

      - run: |
          mkdir -p docs/website/
          rsync -av --delete _src_0/docs/ docs/website/
          rm -rf _src_0

      - run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add -A
          if git diff --cached --quiet; then
            echo "No changes to sync"
          else
            git commit -m "docs: pull from source repos"
            git push
          fi

Both (combined, conditional jobs)

When mode is "both", push and pull jobs coexist in one file with conditional execution:

• push-docs runs on push and workflow_dispatch
• pull-docs runs on schedule and workflow_dispatch

PAT Setup

The workflow needs a Personal Access Token with repo scope:

1. Create a PAT at github.com/settings/tokens/new
2. Add it as a repository secret:

   gh secret set PAT_DOCSYNC

The secret is added to the repo where the workflow runs.

Requirements

• Node.js >= 20
• Must be run inside a git repository
• GitHub CLI (gh) optional, used for repo validation

License

MIT