GitHub Action
actions-template-sync
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.q. template repositories) with the current repository
- Ignore files and folders from syncing using a
.templatesyncignore
file - many configuration options
- different lifecycle hooks are supported
starting with version v0.5.2-draft the templateversionrc
file is not needed anymore. You can delete that file from the target repositories.
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/[email protected]
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.
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 |
|
is_allow_hooks | [optional] set to true if you want to enable lifecycle hooks. Use this with caution! |
false |
false |
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
If you have a private template repository.
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/[email protected]
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.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/[email protected]
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
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
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 repositoryprepush
is executed before the push is executed, right after the commitprepr
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'
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):
This project follows the all-contributors specification. Contributions of any kind welcome!