https://github.com/n3tuk/action-synchronise-upstream
A GitHub Action to help synchronise changes to upstream template repositories to downstream copies.
https://github.com/n3tuk/action-synchronise-upstream
bats cookiecutter cookiecutter-template github-action github-workflows release-drafter shell-scripts
Last synced: 5 days ago
JSON representation
A GitHub Action to help synchronise changes to upstream template repositories to downstream copies.
- Host: GitHub
- URL: https://github.com/n3tuk/action-synchronise-upstream
- Owner: n3tuk
- License: mit
- Created: 2023-05-17T23:27:31.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-19T17:18:26.000Z (about 1 year ago)
- Last Synced: 2025-03-08T09:03:38.921Z (7 months ago)
- Topics: bats, cookiecutter, cookiecutter-template, github-action, github-workflows, release-drafter, shell-scripts
- Language: Shell
- Size: 50.8 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# n3tuk Upstream Template Synchroniser
A GitHub Action for running [`cookiecutter`][cookiecutter] from upstream
template repositories in the `n3tuk` Organisation and apply them over the
templates repositories and submit any changes as a pull request for review and
merging.
[cookiecutter]: https://github.com/cookiecutter/cookiecutter
## Features
This GitHub Action provides the following features:
- Merge upstream changes to the `cookiecutter.json` default configuration file
with the downstream `cookiecutter.json` configuration for each templated
repository, allowing new settings to be automatically added with the provided
default value.
- Optionally re-render the upstream template files with the downstream
`cookiecutter.json` configuration (with updates, if updated) and apply over
the current repository files.
- Allow the downstream repository to ignore upstream changes to selected files
with `.templateignore` in the root directory in the same format as
`.gitignore`. Follow the [glob pattern][glob-pattern] in defining the files
and folders that the action should excluded.
- Add support for updates and removal of files inside the downstream repository
as configured inside the `cookiecutter.json` file, allowing easier migration
of existing files and removal of old files as part of standard updates.
[glob-pattern]: https://en.wikipedia.org/wiki/Glob_(programming)
## Upstream
The codebase for this GitHub Action is an update on the
[`actions-template-sync`][actions-template-sync] GitHub Action, with handling of
templated file overrides (ignores), merging of upstream and downstream
cookiecutter configurations, and building the cookiecutter repository upstream
and overlaying it downstream.
[actions-template-sync]: https://github.com/AndreasAugustin/actions-template-sync
## Usage
You can use the [synchronise-upstream GitHub
Action][synchronise-upstream-marketplace] in a [GitHub
Workflow][github-workflow] by configuring a YAML file in your GitHub repository
(under `.github/workflows/synchronise-upstream.yaml`), with the following contents:
[github-workflow]: https://help.github.com/en/articles/about-github-actions
[synchronise-upstream-marketplace]: https://github.com/marketplace/actions/synchronise-upstream
```yaml
---
name: Synchronise Upstream
on:
# Run at 18:15 on Wednesdays
schedule:
- cron: "15 18 * * 3"
# Allow this GitHub Action to be manually triggered
workflow_dispatch:
permissions:
contents: write
packages: read
issues: write
pull-requests: write
jobs:
template-sync:
name: Template Synchronise
runs-on: ubuntu-latest
env:
SYNCHRONISER_TOKEN: ${{ secrets.SYNCHRONISER_TOKEN || secrets.GITHUB_TOKEN } }
steps:
- name: Checkout the repository
uses: actions/checkout@v3
with:
token: ${{ env.SYNCHRONISER_TOKEN }}
- name: Render and synchronise the template repository
uses: n3tuk/action-synchronise-upstream@v1
with:
token: ${{ env.SYNCHRONISER_TOKEN }}
repository: n3tuk/template-terraform-module
labels: release/skip,dependencies
```
## Inputs
| Variable | Description | Required | Default |
| :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: | :------------------------------------ |
| `token` | The GitHub Token to fetch the template repository and to make changes against the local repository. This is typically set to `secrets.GITHUB_TOKEN`. | `true` | |
| `repository` | The owner/name (i.e. n3tuk/template-terraform-module) of the GitHub repository used to provide the cookiecutter templates for this local repository. | `true` | |
| `branch` | The name of the branch to use in the GitHub repository used to provide the cookiecutter templates for the local repository. | `false` | `main` |
| `target` | The target branch of the local repository to raise the pull request against whem procesing for changes in the template repository or local configuration. | `false` | `main` |
| `prefix` | The prefix for the name of the pull request branch created by this GitHub Action when processing for changes in the template repository or local configuration. | `false` | `chore/synchronise-upstream/` |
| `title` | The title of the pull request set by this GitHub Action when processing for changes in the template repository or local configuration. | `false` | Synchronise Upstream Template Changes |
| `labels` | A comma-separated list of pull request labels to add by this GitHub Action on any created pull request. | `false` | `[]` |