GitHub Action to encapsulate our git Publish (push) workflows

[QuintinWillison]

h3. Actions are working for us
The SDK Team here at [Ably|https://github.com/ably] starting working on Ably's first [GitHub Action|https://docs.github.com/en/actions/creating-actions/about-custom-actions#about-custom-actions] back in early 2021. You can find it at [ably/sdk-upload-action|https://github.com/ably/sdk-upload-action].

It's performing well for us and has [significantly simplified and reduced the amount of workflow script (yaml)|https://github.com/ably/ably-flutter/pull/117] that's required for us to deploy to our S3 bucket, presented at {{sdk.ably.com}}.

It makes a lot of sense for us to continue to encapsulate our patterns and processes as actions once we realise that we're using them in more than one place, or we have the opportunity to do so.

h3. {{git}} push downstream in action
I've encapsulated my preference for keeping source code repositories as purely source code under ably/sdk-upload-action#31.

That preference has been realised in a couple of places already:

• [ably-common|https://github.com/ably/ably-common] publishes to [ably-common-go|https://github.com/ably/ably-common-go], [because Go Modules|https://go.dev/blog/publishing-go-modules]: see [publish-go.sh, invoked from the publish workflow|https://github.com/ably/ably-common/blob/5e695725f801831fbe5523fdd27aa01986ff01fc/.github/workflows/publish.yml#L35]
• [repository-audit|https://github.com/ably/repository-audit] publishes to [repository-audit-report-internal|https://github.com/ably/repository-audit-report-internal], because [we designed it that way|https://github.com/ably/repository-audit#how]: see [publish.sh, invoked from the run workflow|https://github.com/ably/repository-audit/blob/1e25629ee912a386b9970edf6e2820be903a0456/.github/workflows/run.yml#L46]
  ** at the time of writing this issue the {{repository-audit}} source code repository is yet to be made public (Make this repository and the associated GitHub App public repository-audit#5)
  ** that tool will soon also publish to [repository-audit-report|https://github.com/ably/repository-audit-report] (Split the output to two reports, public and private repository-audit#24), which will be made public - the {{repository-audit-report-internal}} repository will remain private

h3. {{git}} push downstream in a GitHub Action
If we consider [a typical example of usage|https://github.com/ably/ably-asset-tracking-android/blob/c8d57f0c7f8c5299db68424e9bdba12deba576cf/.github/workflows/docs.yml#L31] of our existing SDK Upload Action (workflow > job > [step|https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idstepsuses]):

{code:yaml}

• uses: ably/sdk-upload-action@v1
  with:
  s3AccessKeyId: ${{ secrets.SDK_S3_ACCESS_KEY_ID }}
  s3AccessKey: ${{ secrets.SDK_S3_ACCESS_KEY }}
  sourcePath: build/dokka/htmlMultiModule
  githubToken: ${{ secrets.GITHUB_TOKEN }}
  artifactName: dokka
  {code}
  And we then consider the contents of the bash scripts mentioned earlier in this opening comment for this issue, we can extract a prototype for how the invocation of this new action might look in a workflow for the {{ably-common-go}} use case...

h4. Example: {{ably-common}} to {{ably-common-go}}
{code:yaml}

• uses: ably/git-publish-action@v1
  with:
  sshPrivateKey: ${{ secrets.SSH_PRIVATE_KEY }}
  actingWorkflow: Common Publish
  sourcePath: output
  targetRepository: ably-common-go
  {code}
  Where:

• both {{user.name}} and {{user.email}} Git configurations can be generated in the current conformed form from the single {{actingWorkflow}} argument:
  ** {{user.email}}: {{Ably Common Publish Workflow [bot]}}
  ** {{user.email}}: {{ably-common-publish-workflow[bot]@noreply.ably.com}}

h4. Example: {{repository-audit}} to {{repository-audit-report}} ({{main}} branch, 'run')
Replace [this step|https://github.com/ably/repository-audit/blob/1e25629ee912a386b9970edf6e2820be903a0456/.github/workflows/run.yml#L36] with:

{code:yaml}

• uses: ably/git-publish-action@v1
  with:
  sshPrivateKey: ${{ secrets.ABLY_REPOSITORY_AUDIT_REPORT_SSH_KEY }}
  actingWorkflow: Repository Audit
  sourcePath: output/public
  targetRepository: repository-audit-report
  {code}
  h4. Example: {{repository-audit}} to {{repository-audit-report}} (pull request preview branch, 'rehearse')
  Replace the 'Publish Report Preview' step proposed in Generate Report Preview for Pull Requests repository-audit#35 with:

{code:yaml}

• uses: ably/git-publish-action@v1
  with:
  sshPrivateKey: ${{ secrets.ABLY_REPOSITORY_AUDIT_REPORT_SSH_KEY }}
  actingWorkflow: Repository Audit
  sourcePath: output/public
  targetRepository: repository-audit-report
  isPreview: true
  {code}
  Where the action will enforce that the GitHub event name is {{'pull_request'}} and use {{github.event.number}} to obtain the pull request number, because {{isPreview}} is {{true}} (it would be an optional argument, with the default being {{false}}).

[QuintinWillison]

This action should also generate deployments. This is well described in ably/repository-audit#36.