GitHub Action: Template Repository Sync

Keep projects in sync with the template repository they came from

Why?

The [Template Repository][] feature is a great way to accelerate creation of new projects. However, after you "use" the template for first time, the two repositories will forever be out of sync *(any changes made to the template repository will not be reflected in the project repository)*

Usage

This action will automatically detect all repositories within your account (user or org) that has been "initialized" from the template repository (referred to as "dependents" in this doc)

[!NOTE] There is currently a bug in the GitHub APIs preventing this action from automatically detecting dependent repositories, until this is tis resolved, please use additional property in the config file to manually include repositories you want to sync

[!IMPORTANT] MUST USE Fine-grained Personal Access Token, for whatever reason, Classic tokens stopped working with the "contents" scope, which is required for this action to work

`.github/workflows/template-sync.yml`

on: [push, pull_request]

jobs:
  template-sync:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2 # important!
      - uses: ahmadnassri/action-template-repository-sync@v2
        with:
          github-token: ${{ secrets.GH_TOKEN }}
          dry-run: true

A more practical example

``` yaml name: template-sync on: pull_request: # run on pull requests to preview changes before applying workflow_run: # setup this workflow as a dependency of others workflows: [test, release] # don't sync template unless tests and other important workflows have passed jobs: template-sync: timeout-minutes: 20 runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - uses: ahmadnassri/action-workflow-run-wait@v1 # wait for workflow_run to be successful - uses: ahmadnassri/action-workflow-queue@v1 # avoid conflicts, by running this template one at a time - uses: ahmadnassri/action-template-repository-sync@v1 with: github-token: ${{ secrets.GH_TOKEN }} ```

[!WARNING] HIGHLY RECOMMEND to set dry-run: true for the first time you use this action, inspect the output to confirm if the affected repositories list is what you wanted to commit files to

`.github/template-sync.yml`

dependents:
  - "api-*" # include
  - "!lib-*" # exclude

additional:
  - "another-one-*" # include
  - "!not-this-*" # exclude

files:
  - ".gitignore" # include
  - "!package.json" # exclude
  - "!(package-lock.json|yarn.lock)"

  # you probably want to exclude these files:
  - "!.github/workflows/template-sync.yml"
  - "!.github/template-sync.yml"

  # remap file names at destination repo
  - .gitignore-example: .gitignore

Config File

`dependents`

a list of repository name patterns

when not present or empty, the action will update EVERY DEPENDENT repository

`additional`

a list of repository name patterns

expands the list of repos in addition to the detected dependant repos, use this to sync repos that were not originally initialized from the template repository.

`files`

a list of filename patterns to include or exclude

NOTE: You can set a different destination for synced files using the object syntax: source_path: destination_path

Example

files:
  # remap file names at destination repo
  - templates/.gitignore-example: .gitignore

Pattern syntax

[!WARNING] Always use forward-slashes in glob expressions and backslashes for escaping characters.

[!TIP] This package uses a micromatch as a library for pattern matching.

Inputs

input	required	default	description
`github-token`	✔️	`-`	The GitHub token used to call the GitHub API
`config`	❌	`.github/template-sync.yml`	path to config file
`dry-run`	❌	`false`	toggle info mode (commits wont occur)

:warning: Operational Logic

The action will only run on the following event types: schedule,workflow_dispatch,repository_dispatch,pull_request,release,workflow_run,push.
The when run in pull_request, the action will post post a comment on the the Pull Request with the diff view of files to be changed.
The action will look for files under the GITHUB_WORKSPACE environment path
The action will read file contents AT RUNTIME (so you can run build steps or modify content before running the action if you so wish)
If no config file is present indicating which files to filter, the action will sync ALL FILES in the template repository
The action will respect .gitignore files
Files on target repos WILL BE CREATED if they do not exist

Author: Ahmad Nassri • Twitter: @AhmadNassri

ahmadnassri / action-template-repository-sync

readme