Skip to content
You're viewing an older version of this GitHub Action. Do you want to see the latest version instead?
cloud

GitHub Action

actions-template-sync

v0.6.0-draft Pre-release

actions-template-sync

cloud

actions-template-sync

Synchronises changes of the template repository

Installation

Copy and paste the following snippet into your .yml file.

              

- name: actions-template-sync

uses: AndreasAugustin/actions-template-sync@v0.6.0-draft

Learn more about this action in AndreasAugustin/actions-template-sync

Choose a version

actions-template-sync

All Contributors

Lint

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.

Features

  • Sync other public or private repository (e.q. template repositories) with the current repository
  • Ignore files and folders from syncing using a .templatesyncignore file
  • many configuration options

Usage

Update

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

GitHub Actions

Add this configuration to your github action

# 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.6.0-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.

Configuration parameters

Variable Description Required [Default]
github_token Token for the repo. Can be passed in using $\{{ secrets.GITHUB_TOKEN }} true
source_repo_path Repository path of the template true
upstream_branch The target branch true main
source_repo_ssh_private_key [optional] private ssh key for the source repository. see false
pr_branch_name_prefix [optional] the prefix of branches created by this action false chore/template_sync
pr_title [optional] the title of PRs opened by this action. Must be already created. false upstream merge template repository
pr_labels [optional] comma separated list. pull request labels. Must be already created. false
pr_commit_msg [optional] commit message in the created pull request false chore(template): merge template changes :up:
hostname [optional] the hostname of the repository false github.com
is_dry_run [optional] set to true if you do not want to push the changes and not want to create a PR false

Example

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

Trigger

You can use all triggers which are supported for GitHub actions

Private template repository

If you have a private template repository.

Using github app

You can create and use a GitHub App to handle the access to your private 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.6.0-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

SSH

You have various options to use ssh keys with GitHub. An example are deployment keys. For our use case write permissions are not needed.i Within the 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.

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.6.0-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

Ignore Files

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.

Debug

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."

DEV

The development environment targets are located in the Makefile

make help

For some architectural notes please have a look into docs

Contributors ✨

Thanks goes to these wonderful people (emoji key):

andy Augustin
andy Augustin

📖 💻 👀 🛡️ 🤔 💬 💡
Ugo Pattacini
Ugo Pattacini

📖
Jose Gabrielle Rivera
Jose Gabrielle Rivera

💻
P.D. Rittenhouse
P.D. Rittenhouse

🤔
Daniel Boll
Daniel Boll

🐛
albertschwarzkopf
albertschwarzkopf

🤔
Akul Pillai
Akul Pillai

🛡️
Stefan Riembauer
Stefan Riembauer

🤔
Fabrizio Cacicia
Fabrizio Cacicia

🛡️ 🐛
Justin Tunis
Justin Tunis

🤔 💻 🐛
Michael Matos
Michael Matos

🐛
Gavin Williams
Gavin Williams

🤔
Marc Siebeneicher
Marc Siebeneicher

🤔 💻 🐛 📖
Luís Henrique A. Schünemann
Luís Henrique A. Schünemann

🤔 📖 💻

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