Instead of a GH_PAT, you can use a token from a GitHub App installation via the GH_INSTALLATION_TOKEN input. This allows for more granular access control.

Required Permissions for the App:

• Contents: Read & Write
• Metadata: Read-only
• Pull requests: Read & Write (if using PRs, which is the default)
• Workflows: Read & Write (if syncing workflow files)

Note: If using an installation token, you must also provide the GIT_EMAIL and GIT_USERNAME inputs.

You can render files using Jinja-style template syntax powered by Nunjucks.

To enable templating:

1. Set the template field to true (if no variables are needed) or to a dictionary of context variables.
2. Use {{ variable.name }} syntax within your source files.
3. Use {% extends './path' %} for template inheritance.

Variables provided in the template dictionary are available to the Nunjucks engine during the sync process.

user/repo:
  - source: src/README.md
    template:
      user:
        name: 'Maxi'
        handle: '@BetaHuhn'

src/README.md

Created by {{ user.name }} ({{ user.handle }})

To configure which files are synced to which repositories, create a sync.yml file in the .github directory of your main repository.

Target repositories are specified as top-level keys using the format username/repository-name or username/repository-name@branch. Under each target, you list the files or directories to be synced.

user/repo:
  - path/to/file.txt
user/repo2@develop:
  - path/to/file2.txt

You can sync files by listing their paths directly, or sync entire directories using the source and dest keys.

• Individual files: List the path directly under the repository key.
• Custom destination: Use source for the original path and dest for the target path/filename.
• Directories: Provide a directory path to source and a target directory to dest.

user/repo:
  # List individual files
  - .github/workflows/build.yml
  - LICENSE
  
  # Custom destination path or filename
  - source: workflows/build.yml
    dest: .github/workflows/build.yml
  - source: LICENSE.md
    dest: LICENSE

  # Entire directories
  - source: workflows/
    dest: .github/workflows/

You can target specific branches in the destination repositories by using the @branch suffix in the repository name. This is particularly useful when using groups to sync the same source files to different language or region branches of the same repository.

group:
  repos: |
    foo/bar@de
    foo/bar@es
    foo/bar@fr
  files:
    - source: .github/workflows/
      dest: .github/workflows/

To avoid repetition when syncing the same set of files to multiple repositories, use the group syntax. A group defines a list of repos (as a multi-line string) and a list of files to be applied to all of them.

group:
  - files: 
      - source: workflows/build.yml
        dest: .github/workflows/build.yml
      - source: LICENSE.md
        dest: LICENSE
    repos: |
      user/repo1
      user/repo2

  - files: 
      - source: configs/dependabot.yml
        dest: .github/dependabot.yml
    repos: |
      user/repo3
      user/repo4

To ensure stability, choose your versioning strategy carefully:

• @v1 (Recommended): Uses the latest non-breaking version. This includes bug fixes but prevents breaking changes from disrupting your workflow.
• @latest: Always uses the absolute latest version available. Use this if you want the newest features immediately and are prepared for potential breaking changes.
• Specific version: Use a fixed version number if you need absolute immutability, but remember to update it manually or via Dependabot.

# Recommended for stability
uses: BetaHuhn/repo-file-sync-action@v1

# For latest features (use with caution)
uses: BetaHuhn/repo-file-sync-action@latest

The repo-file-sync-action is a GitHub Action designed to synchronize files or directories from a source repository to a target repository. It automates the process of cloning the target, copying files, committing changes, and optionally creating or updating a Pull Request.

Core Workflow

1. Cloning: The action clones the target repository locally.
2. Syncing: It iterates through the configured files, copying them from the source to the destination path in the target repo.
3. Committing: Depending on configuration, it either commits each file individually or commits all changes in a single batch.
4. Pushing: Changes are pushed to the target repository branch.
5. Pull Request: If enabled, it creates or updates a Pull Request with optional labels, assignees, and reviewers.

Create a .yml file at .github/sync.yml to define which files or directories should be synced to which target repositories.

Supported formats:

• Simple list: Map a user/repository to a list of file paths.
• Explicit mapping: Use source and dest keys to map a specific source file to a different destination path/filename in the target repository.

user/repository:
  - .github/workflows/test.yml
  - .github/workflows/lint.yml

user/repository2:
  - source: workflows/stale.yml
    dest: .github/workflows/stale.yml

When syncing entire directories, you can enable the deleteOrphaned option. If set to true, any files present in the target repository's destination directory that are NOT present in the source directory will be deleted. This option only works for directory syncs and is scoped to the specific directory entry.

user/repo:
  - source: workflows/
    dest: .github/workflows/
    deleteOrphaned: true

When syncing an entire directory, you can prevent specific files from being copied by using the exclude key. The paths provided in exclude must be relative to the source path.

user/repo:
  - source: workflows/
    dest: .github/workflows/
    exclude: |
      node.yml
      lint.yml