Skip to content
file-text

GitHub Action

synchronise-upstream

v1.0.2 Latest version

synchronise-upstream

file-text

synchronise-upstream

A GitHub Action for synchronising template changes from upstream into a downstream repository through a pull request

Installation

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

              

- name: synchronise-upstream

uses: n3tuk/[email protected]

Learn more about this action in n3tuk/action-synchronise-upstream

Choose a version

n3tuk Upstream Template Synchroniser

A GitHub Action for running 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.

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

Upstream

The codebase for this GitHub Action is an update on the 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.

Usage

You can use the synchronise-upstream GitHub Action in a GitHub Workflow by configuring a YAML file in your GitHub repository (under .github/workflows/synchronise-upstream.yaml), with the following contents:

---
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 []