It is possible to create repositories within Github with GitHub templates. This is a nice approach to have some boilerplate within your repository. Over the time the template repository will get some code changes. The problem is that the already created repositories won't know about those changes. This GitHub action will help you to keep track of the template changes.

• Sync other public or private repository (e.g. template repositories) with the current repository
• Ignore files and folders from syncing using a .templatesyncignore file
• many configuration options
• different lifecycle hooks are supported
• different git provider. Default is GitHub, GitLab is also tested. See .github/workflows/test_ssh_gitlab.yml for an example.

Usage changes depending on whether the template repository is public or private, regardless of the visibility of current repository.

Add this configuration to a github action in the current repository:

# File: .github/workflows/template-sync.yml

on:
    # cronjob trigger
  schedule:
  - cron:  "0 0 1 * *"
  # manual trigger
  workflow_dispatch:
jobs:
  repo-sync:
    runs-on: ubuntu-latest

    steps:
      # To use this repository's private action, you must check out the repository
      - name: Checkout
        uses: actions/checkout@v3
      - name: actions-template-sync
        uses: AndreasAugustin/actions-template-sync@v0.7.2-draft
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          source_repo_path: <owner/repo>
          upstream_branch: <target_branch> # defaults to main
          pr_labels: <label1>,<label2>[,...] # optional, no default

You will receive a pull request within your repository if there are some changes available in the template.

If your current repository was created from a private template, there are 2 possibilities.

You can create and use a GitHub App to handle the access to the private template repository. To generate a token for your app you can use a separate action like tibdex/github-app-token.

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

    steps:
     - name: Generate token to read from source repo # see: https://github.com/tibdex/github-app-token
        id: generate_token
        uses: tibdex/github-app-token@v1
        with:
          app_id: ${{ secrets.APP_ID }}
          private_key: ${{ secrets.PRIVATE_KEY }}

      - name: actions-template-sync
        uses: AndreasAugustin/actions-template-sync@v0.7.2-draft
        with:
          github_token: ${{ steps.generate_token.outputs.token }}
          source_repo_path: <owner/repo>
          upstream_branch: <target_branch> # defaults to main
          pr_labels: <label1>,<label2>[,...] # optional, no default

You have various options to use ssh keys with GitHub. An example are deployment keys. For our use case write permissions are not needed. Within the current repository, where the GitHub action is enabled, add a secret (e.q. SOURCE_REPO_SSH_PRIVATE_KEY) with the content of your private SSH key. Make sure that the read permissions of that secret fulfil your use case. Set the optional source_repo_ssh_private_key input parameter. It is also possible to use a different git provider, e.g. GitLab.

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

    steps:
      # To use this repository's private action, you must check out the repository
      - name: Checkout
        uses: actions/checkout@v3
      - name: actions-template-sync
        uses: AndreasAugustin/actions-template-sync@v0.7.2-draft
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          source_repo_path: ${{ secrets.SOURCE_REPO_PATH }} # <owner/repo>, should be within secrets
          upstream_branch: ${{ secrets.TARGET_BRANCH }} #<target_branch> # defaults to main
          pr_labels: <label1>,<label2>[,...] # optional, no default
          source_repo_ssh_private_key: ${{ secrets.SOURCE_REPO_SSH_PRIVATE_KEY }} # contains the private ssh key of the private repository

This repo uses this template and this action from the marketplace. See the definition here.

If you look for a more detailed guide you can have a look at Dev.to or GitHub

You can use all triggers which are supported for GitHub actions

Create a .templatesyncignore file. Just like writing a .gitignore file, follow the glob pattern in defining the files and folders that should be excluded from syncing with the template repository.

It can also be stored inside .github folder.

Note: It is not possible to sync also the .templatesyncignore itself. Any changes from the template repository will be restored automatically.

Different lifecycle hooks are supported. You need enable the functionality with the option is_allow_hooks and set it to true ⚠️ use this functionality with caution. You can use one of the available docker images to test it out. With great power comes great responsibility.

• dockerhub andyaugustin/actions-template-sync
• github andreasaugustin/actions-template-sync

In addition you need a configuration file with the name templatesync.yml within the root of the target repository.

Following hooks are supported (please check docs/ARCHITECTURE.md for a better understanding of the lifecycles).

• install is executed after the container has started and after reading and setting up the environment.
• prepull is executed before the code is pulled from the source repository
• prepush is executed before the push is executed, right after the commit
• prepr is executed before the PR is done

Remark The underlying OS is defined by an alpine container. E.q. for the installation phase you need to use commands like apk add --update --no-cache python3

Schema and example for the temlatesync.yml

hooks:
  install:
    commands:
      - apk add --update --no-cache python3
      - python3 --version
  prepull:
    commands:
      - echo 'hi, we are within the prepull phase'
      - echo 'maybe you want to do adjustments on the local code'
  prepush:
    commands:
      - echo 'hi, we are within the prepush phase'
      - echo 'maybe you want to add further changes and commits'
  prepr:
    commands:
      - echo 'hi, we are within the prepr phase'
      - echo 'maybe you want to change the code a bit and do another push before creating the pr'

• refusing to allow a GitHub App to create or update workflow .github/workflows/******.yml without workflows permission

This happens because the template repository is trying to overwrite some files inside .github/workflows/. Currently a github action can't overwrite these files. To ignore those, simply create a file in the root directory named .templatesyncignore with the content .github/workflows/.

• pull request create failed: GraphQL: GitHub Actions is not permitted to create or approve pull requests (createPullRequest)

Open your project Settings > Actions > General and select the checkbox Allow Github Actions to create and approve pull requests under the Workflow permissions section.

starting with version v0.5.2-draft the templateversionrc file is not needed anymore. You can delete that file from the target repositories.

You must create a secret named ACTIONS_STEP_DEBUG with the value true to see the debug messages set by this command in the log. For more information, see "Enabling debug logging."

The development environment targets are located in the Makefile

make help

For some architectural notes please have a look into docs

Thanks goes to these wonderful people (emoji key):

andy Augustin 📖 💻 👀 🛡️ 🤔 💬 💡 🖋 📝	Ugo Pattacini 📖	Jose Gabrielle Rivera 💻	P.D. Rittenhouse 🤔	Daniel Boll 🐛	albertschwarzkopf 🤔	Akul Pillai 🛡️
Stefan Riembauer 🤔	Fabrizio Cacicia 🛡️ 🐛	Justin Tunis 🤔 💻 🐛	Michael Matos 🐛	Gavin Williams 🤔	Marc Siebeneicher 🤔 💻 🐛 📖	Luís Henrique A. Schünemann 🤔 📖 💻
George 💬 📖

This project follows the all-contributors specification. Contributions of any kind welcome!