OSOE-735: Introduce versioning and releases

.github/actions/set-gha-refs/Set-Called-GHA-Refs.ps1

@@ -0,0 +1,46 @@
+param(
+    [String[]] $CalledRepoBaseIncludeList,
+    [String[]] $AdditionalPatternIncludeList,
+    [String[]] $PathIncludeList,
+    [String[]] $FileIncludeList,
+    [String] $ExpectedRef
+)
+
+if ($CalledRepoBaseIncludeList.Count -eq 0)
+{
+    Write-Output '::warning file=Check-Called-GHA-refs.ps1,line10::CalledRepoBaseIncludeList is empty which is unexpected. If this was intentional, you can ignore this warning.'
+}
+else
+{
+    $CalledRepoBaseIncludeList = $CalledRepoBaseIncludeList.ForEach({ 'uses:\s*' + $PSItem + '.*@(?<ref>[aA-zZ,0-9,-,\.,/,_]*)' })
+
+    $matchedRefs = Get-ChildItem -Path $PathIncludeList -Include $FileIncludeList -Force -Recurse |
+        Select-String -Pattern $CalledRepoBaseIncludeList
+
+    $additionalRefs = Get-ChildItem -Path $PathIncludeList -Include $FileIncludeList -Force -Recurse |
+        Select-String -Pattern $AdditionalPatternIncludeList
+
+    $matchedRefs = $matchedRefs + $additionalRefs
+
+    if ($matchedRefs.Count -gt 0)
+    {
+        foreach ($matched in $matchedRefs)
+        {
+            $oldline = $matched.Line
+            $newline = $matched.Line -Replace $matched.Matches[0].Groups['ref'].Value, "$ExpectedRef"
+
+            if ($oldine -ne $newline)
+            {
+                Write-Output "$oldline => $newline"
+
+                $filename = $matched.RelativePath($pwd)
+                $linenumber = $mismatch.LineNumber
+                $title = "GHA Ref pinned to '$ExpectedRef'"
+
+                (Get-Content $filename).Replace($oldline, $newline) | Set-Content $filename
+
+                Write-Output "::notice file=$filename,line=$linenumber,title=$title::GHA Ref changed to '$ExpectedRef'"
+            }
+        }
+    }
+}

.github/actions/set-gha-refs/action.yml

@@ -0,0 +1,52 @@
+name: Set GitHub Actions References
+description: >
+  Explicitly sets all called GitHub Action and Workflow references to an expected version.
+
+inputs:
+  path-include-list:
+    required: false
+    default: '@(".github")'
+    description: >
+      PowerShell string array of paths, relative to the repository root, to search for GHA files, e.g. '@(".github")' or '@(".github/actions", ".github/workflows")'. The
+      parameter must be a PowerShell string array.
+  file-include-list:
+    required: false
+    default: '@("*.yml","*.yaml")'
+    description: >
+      PowerShell string array of file name patterns to include when evaluating GHA files, e.g. '@("*.yml")' or '@("*.yml", "*.yaml")'. The
+      parameter must be a PowerShell string array.
+  called-repo-base-include-list:
+    required: false
+    default: '@("${{ github.repository }}")'
+    description: >
+      PowerShell string array of repository base URLs to include when evaluating called GHA Workflows and Actions, e.g '@("Lombiq/GitHub-Actions")' or
+      '@("Lombiq/GitHub-Actions", "Lombiq/Open-Source-Orchard-Core-Extensions")'. The parameter must be a PowerShell string array.
+  additional-pattern-include-list:
+    required: false
+    default: '@()'
+    description: >
+      PowerShell string array of additional RegEx patterns to include when searching for branch references that need to be
+      updated, e.g. 'https://raw.githubusercontent.com/Lombiq/GitHub-Actions/(?<ref>[aA-zZ,0-9,-,\.,/,_]*)/.github/'. The pattern MUST include a regex named capture group (?<ref>[aA-zZ,0-9,-,\.,/,_]*) so the captured ref
+      can be updated correctly. The parameter must be a PowerShell string array.
+  expected-ref:
+    required: true
+    description: The expected reference value to set for all called GHA Workflows and Actions.
+runs:
+  using: "composite"
+  steps:
+    - name: Setup
+      shell: pwsh
+      run: |
+        "${{ github.action_path }}" >> $Env:GITHUB_PATH
+
+    - name: Set References
+      shell: pwsh
+      run: |
+        $params = @{
+            PathIncludeList = ${{ inputs.path-include-list }}
+            FileIncludeList = ${{ inputs.file-include-list }}
+            CalledRepoBaseIncludeList = ${{ inputs.called-repo-base-include-list }}
+            AdditionalPatternIncludeList = ${{ inputs.additional-pattern-include-list }}
+            ExpectedRef = "${{ inputs.expected-ref }}"
+        }
+        Set-Called-GHA-Refs @params

.github/workflows/tag-version-this-repo.yml

@@ -0,0 +1,13 @@
+name: Tag Version (this repo)
+on:
+  push:
+    branches:
+      - release/**
+
+jobs:
+  run:
+    name: Tag Version Automation
+    if: github.event.pusher.name != 'LombiqBot'
+    uses: Lombiq/GitHub-Actions/.github/workflows/tag-version.yml@issue/OSOE-735
+    secrets:
+      TAG_VERSION_TOKEN: ${{ secrets.LOMBIQBOT_GITHUB_PERSONAL_ACCESS_TOKEN }}

.github/workflows/tag-version.yml

@@ -0,0 +1,51 @@
+name: Tag Version
+
+on:
+  workflow_call:
+    secrets:
+      # We can't access org secrets here so they need to be passed in.
+      TAG_VERSION_TOKEN:
+        required: false
+        description: >
+          An authentication token, like a personal access token (PAT), that provides 'Workflow' permission with write access
+          to the workflow files of the repository and can be used to modify GitHub actions and workflows. This is necessary
+          because when a pull request is merged while being authenticated with the default GITHUB_TOKEN of a workflow run,
+          then the merge won't trigger other workflows (like a build workflow on the target branch). This is an intentional limitation, see:
+          https://docs.github.com/en/actions/using-workflows/triggering-a-workflow#triggering-a-workflow-from-a-workflow.
+          Thus, we need to use an alternative authentication token. See
+          https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token
+          for info on how to create PATs; you'll need one with the "work" scope. We recommend creating such a token from under a bot user
+          account only used for such operations, so it's not tied to a natural person.
+jobs:
+  run:
+    name: Set GitHub Action/Workflow to Version Tag
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: Lombiq/GitHub-Actions/.github/actions/checkout@dev
+        with:
+          token: ${{ secrets.TAG_VERSION_TOKEN }}
+      - name: Determine Version Tag Name from Branch Name
+        id: determine-tag
+        shell: pwsh
+        run: |
+          $refname = "${{ github.ref_name }}"
+          $tagname = $refname -replace 'release/', ''
+          $output = "tagname=$tagname"
+          Write-Output "output=$output"
+          $output >> $env:GITHUB_OUTPUT
+      - name: Set Ref for GitHub Actions and Workflows
+        uses: Lombiq/GitHub-Actions/.github/actions/set-gha-refs@issue/OSOE-735
+        with:
+          additional-pattern-include-list: '@("https://raw.githubusercontent.com/Lombiq/GitHub-Actions/(?<ref>[aA-zZ,0-9,-,\.,/,_]*)/.github")'
+          expected-ref: '${{ steps.determine-tag.outputs.tagname }}'
+      - name: Commit and Push Changes
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+          commit_message: 'Set GitHub Actions/Workflows to tag ${{ steps.determine-tag.outputs.tagname }}'
+          tagging_message: ${{ steps.determine-tag.outputs.tagname }}
+      - name: Force Push Tag
+        continue-on-error: true
+        shell: pwsh
+        run: |
+          git push --tags --force