add template engine functionality to support generic templates

.github/workflows/copy-workflow.yml

@@ -55,7 +55,8 @@ jobs:
       # See https://github.com/protocol/.github/blob/38135c75e47839623bf9b2748275d8c6167a8fa8/.github/workflows/copy-workflow.yml#L163-L168 for an example, how we used to make use of this.
       run: |
         files=${{ toJson(toJson(matrix.cfg.files)) }}
-        files=$(echo -e "$files" | jq -c '.')
+        extra_files=${{ toJson(toJson(matrix.cfg.extra_files)) }}
+        files=$(echo -e "$files" "$extra_files" | jq -nc '[inputs] | add')
         echo "FILES=$files" >> $GITHUB_ENV
     - name: is initial workflow deployment
       # INITIAL_WORKFLOW_DEPLOYMENT=1 iff none of the files in the target repository exist yet
@@ -101,13 +102,26 @@ jobs:
       uses: ./template-repo/.github/actions/copy-workflow-versioning
     - name: Add files
       run: |
+        config=${{ toJson(toJson(matrix.cfg)) }}
+        config=$(echo -e "$config" | jq -c '.')
+        github="{\"default_branch\":\"${{ env.DEFAULT_BRANCH }}\"}"
+        context="{\"config\":$config,\"github\":$github}"
+        # matches trimmed string between template context delimiters
+        regexp='\$\{\{\{\s*(.*?)\s*\}\}\}'
+        # replacement is a perl script that:
+        # 1. prepends . to the matched string to create a filter
+        # 2. escapes single quotes by replacing ' with '"'"' in filter
+        # 3. prints context escaped in the same manner
+        # 4. applies jq with filter to the stdout
+        replacement="\$filter = \".\$1\"; \$filter =~ s/'/'\"'\"'/g; \`echo '${context//\'/\'\"\'\"\'}' | jq -jc '\$filter'\`"
         for f in $(jq -r '.[]' <<< ${{ toJson(env.FILES) }}); do
           echo -e "\nProcessing $f."
           # add DO NOT EDIT header
           tmp=$(mktemp)
           cat $TEMPLATE_REPO_DIR/$TEMPLATE_DIR/header.yml $TEMPLATE_REPO_DIR/$TEMPLATE_DIR/$f > $tmp
-          # replace $default-branch with this repo's GitHub default branch
-          sed -i "s:\$default-branch:${{ env.DEFAULT_BRANCH }}:g" $tmp
+          # replace template contexts with values from the JSON context object
+          perl -pi -e "s#$regexp#$replacement#ge" $tmp
+          mv $tmp $TEMPLATE_REPO_DIR/$TEMPLATE_DIR/$f
           # create commit, if necessary
           commit_msg=""
           if [[ ! -f "$TARGET_REPO_DIR/$f" ]]; then

templates/README.md

@@ -0,0 +1,125 @@
+# Templates
+
+This directory contains template files that can be expanded and copied over to the configured repositories.
+
+## Header
+
+The [header](header.yml) is prepended to all the files before they are copied to the target repositories.
+
+## Contexts
+
+You can access context information during template expansion (before copy is performed).
+
+### About contexts
+
+Contexts are a way to access information about the repository configuration object and repository GitHub settings. Contexts use the following syntax:
+
+```
+${{{ <context> }}}
+```
+
+| Context name | Type | Description |
+| --- | --- | --- |
+| `config` | `object` | Configuration object because of which the file is being copied. For more information, see [config context](#config-context) |
+| `github` | `object` | Information about the target repository the file is being copied to. For more information, see [github context](#github-context) |
+
+The context container is generated automatically before template expansion is performed.
+
+#### `config` context
+
+The `config` context is the configuration object because of which the file is being copied. It is created by merging the `defaults` object with a `repository` object (from the `repositories` array) from a JSON configuration file.
+
+| Property name | Type | Always present | Description |
+| --- | --- | --- | --- |
+| `config` | `object` | `true` | The top-level context. | true |
+| `config.files` | `array` | `true` | The files that are being copied. |
+| `config.extra_files` | `array` | `false` | The additional files that are also being copied. |
+| `config.target` | `string` | `true` | The name of the target repository in `{owner}/{repo}` format. |
+| `config.deploy_go` | `boolean` | `false` | Flag controling if Go specific setup should be applied to the repository. |
+| `config.deploy_versioning` | `boolean` | `false` | Flag controling if `versions.json` file should be deployed to the repository. |
+| `config.dist` | `string` | `false` | The name of the distribution built from the repository. |
+
+#### `github` context
+
+The `github` context contains information about the target repository the file is being copied to. It is created on the fly before template expansion is performed.
+
+| Property name | Type | Always present | Description |
+| --- | --- | --- | --- |
+| `github` | `object` | `true` | The top-level context. |
+| `github.default_branch` | `string` | `true` | The name of the default branch of the target repository. |
+
+### Examples
+
+#### JSON configuration
+
+```json
+{
+  "defaults": {
+    "files": [".github/workflows/automerge.yml"],
+    "is_example": false
+  },
+  "repositories": [
+    {
+      "target": "protocol/.github-test-target",
+      "extra_files": [".github/workflows/example.yml"],
+      "example": {
+        "greeting": "Hello"
+      },
+      "is_example": true
+    }
+  ]
+}
+```
+
+#### Context container
+
+*created automatically before template expansion is performed*
+
+```json
+{
+  "config": {
+    "target": "protocol/.github-test-target",
+    "files": [".github/workflows/automerge.yml"],
+    "extra_files": [".github/workflows/example.yml"],
+    "example": {
+      "greeting": "Hello"
+    },
+    "is_example": true
+  },
+  "github": {
+    "default_branch": "master"
+  }
+}
+```
+
+#### Template
+
+```yaml
+name: Hello
+on:
+  push:
+    branches:
+      - ${{{ github.default_branch }}}
+jobs:
+  echo:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo ${{{ config.example.greeting }}}
+        shell: bash
+```
+
+#### Expanded template
+
+```yaml
+name: Hello
+on:
+  push:
+    branches:
+      - master
+jobs:
+  echo:
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo Hello
+        shell: bash
+```