Start turning GitGitGadget into a set of GitHub Actions and workflows

[dscho]

This is based on the discussion at #609.

Migration Plan: Azure Pipelines to GitHub Actions

This document outlines the strategy for migrating GitGitGadget's automation from Azure Pipelines to GitHub Actions.

Background & Motivation

For years, we have relied on a set of Azure Pipelines backed by a database maintained in Git notes. This global state required careful handling of concurrency, which we solved by running all jobs inside a dedicated Azure Pipeline runner on a single Azure VM. This setup guaranteed exclusive access, allowing the pipeline to read, update, and push Git notes without concurrent interference.

However, this approach is fragile and problematic:

• During a lengthy Azure Pipeline run (looking at you, Update GitGitGadget's PRs, no other Azure Pipeline can run, which often results in delays of, say, /submiting patch series.
• It depends on the self-hosted runner and on my personal Azure account.
• The Pipelines are not YAML-based, making modifications less transparent and contributions impossible.
• The current setup is full of hacks to accommodate for compatibility issues with certain Git versions (that I have to upgrade manually on that runner) and various other issues I had to address over the years.
• Keeping the GitGitGadget checkout up to date on that runner, and transpiled, adds to some unwanted complexity.
• Persistent repositories between runs can retain unwanted information, and are susceptible to attacks where one workflow run (that has to accept untrusted input) could lead to a change of behavior that persists when running subsequent workflow runs (including those runs that are supposed to be safe from untrusted input and has access to sensitive credentials).

Project Goal

My overarching goal is to make GitGitGadget more robust, maintainable, and contributor-friendly by migrating to GitHub Actions and workflows.

Migration Approach

• Restructure GitGitGadget's source code so it can be executed via GitHub Actions. All functionality currently in Azure Pipelines will be available in GitHub Actions, with each Action corresponding to one or more of the existing Azure Pipelines.
• The main codebase remains in TypeScript, transpiled to JavaScript. The CIHelper class serves as the main entry point.
• Each GitHub Action is implemented as minimal JavaScript, delegating all core logic to the CI helper.
• The goal is for each GitHub Action to consist of a minimal action.yml and index.js.
• Each GitHub Action is called by exactly one, minimal GitHub workflow, to reduce the complexity of the new approach.

GitHub Actions & Workflows

• When code is updated in the main branch, a GitHub workflow in gitgitgadget/gitgitgadget updates a dedicated v1 branch. This branch contains the full commit history of the main branch (via merging it) but only the transpiled and bundled JavaScript at its tip commit's tree, ready for use as a GitHub Action.
• Versioning is more transparent: Each workflow run updates the v1 branch and maintains an incremental v1.<number> tag.
• GitHub Actions must be triggered by workflows. To keep maintenance simple, each Action will have a corresponding minimal workflow that calls only that Action. These workflows reside in the gitgitgadget-workflows org.

Concurrency Considerations

• Running the workflows in a separate GitHub org addresses concurrency limits, especially when those large pushes by the Git maintainer where dozens of branches are pushed at the same time trigger as many CI runs that each require a whopping 8-12h overall and blocks all other use of GitHub Actions for hours on end.

PR Checks Integration

• One drawback of the migration is losing the PR checks that are provided automatically by Azure Pipelines. To restore this convenience, I plan on developing a new GitHub Action that mirrors check runs from gitgitgadget-workflows to the respective PRs. This approach has been successfully used in the Git for Windows project, and those learnings will be invaluable.

Detailed overview of the new GitHub Actions

• handle-pr-comment
  • replaces:
    1. GitGitGadget PR Handler
    2. GitGitGadget PR Handler (git)
    3. GitGitGadget PR Handler (dscho)
  • triggers on: PR comments by allowed users
  • needs: smtp credentials
• handle-pr-push
  • replaces:
    1. GitGitGadget PR Handler
    2. GitGitGadget PR Handler (git)
    3. GitGitGadget PR Handler (dscho)
  • triggers on: PR pushes
• handle-new-mails
  • replaces:
    1. Mirror Git List to GitGitGadget's PRs
  • triggers on: git-mailing-list-mirror updates
  • needs: git-mailing-list
• update-prs
  • replaces:
    1. Update GitGitGadget's PRs
  • triggers on: seen updates
  • runs: updateOpenPrs(), updateCommitMappings() and handleOpenPRs()
• update-mail-to-commit-notes
  • replaces:
    1. Update GitGitGadget's commit to mail notes
  • triggers on: seen updates
  • TODO: convert from using gitster/seen to upstream/seen
  • needs: git-mailing-list
  • runs:

    rev="$(git -C "$GITGIT_DIR" rev-parse refs/notes/commit-to-mail)"
    ./gitgitgadget/script/lookup-commit.sh --notes update
    if test "$rev" != "$(git -C "$GITGIT_DIR" rev-parse refs/notes/commit-to-mail)"
    then
      ./gitgitgadget/script/update-mail-to-commit-notes.sh
    
      git -C "$GITGIT_DIR" push https://git-for-windows-ci:$(git-for-windows-ci.github.token)@github.com/gitgitgadget/git refs/notes/commit-to-mail refs/notes/mail-to-commit ||
      die "Could not push notes"
    
      no_match="$(git -C "$GITGIT_DIR"/ show refs/notes/commit-to-mail | grep -B2 no\ match | sed -ne 's/\///g' -e 's/^\+\+\+ b//p')"
      test -z "$no_match" ||
      die "Could not find mail(s) for: $no_match"
    fi
    

Oh, and best of all: the way the Azure Pipelines run GitGitGadget via misc-helper will continue working all the way through the migration.

[dscho]

To verify that it all works as intended, I added a commit to add a reaction to dscho/git#29 (comment) (the commit will be dropped before long, of course, it's intention was only to demonstrate that the design works).

There were a few linting issues I had missed, so I added another reaction (via https://github.com/gitgitgadget/gitgitgadget/actions/runs/5916258877).

[webstech]

fyi, I am reviewing this. Just taking some time.

[dscho]

@webstech no worries!

[dscho]

This PR will need to be updated using #1473 once that one is merged, to be used in a post-Action of the init one to ensure that the local refs/notes/gitgitgadget state is synchronized back to https://github.com/gitgitgadget/git.

[dscho]

@webstech 🎉 this workflow run just successfully handled this /preview command to send the preview email to me.

It's slowly all coming together!

[dscho]

@webstech while talking about this PR to @mjcheetham, he brought up the question whether this needs to be a set of Actions or whether it would be better to have a single Action covering all the functionality. I can see pros and cons to both approaches. Just to illustrate the difference:

The approach currently chosen in this PR

+    - uses: gitgitgadget/gitgitgadget/handle-pr-comment@v1
+      with:
+        gitgitgadget-git-access-token: ${{ steps.gitgitgadget-git-token.outputs.token }}
+        git-git-access-token: ${{ steps.git-git-token.outputs.token }}
+        dscho-git-access-token: ${{ steps.dscho-git-token.outputs.token }}
+        smtp-options: '{"user": "[email protected]", "host": "smtp.gmail.com", "pass": ${{ toJSON(secrets.GITGITGADGET_SMTP_PASS) }}}'
+        pr-comment-url: ${{ inputs.pr-comment-url }}

The biggest pro I see here is that it allows for defining exactly which inputs are required for any given functionality (update-mail-to-commit-notes does not require a git-git-access-token, for example).

With a single Action

+    - uses: gitgitgadget/gitgitgadget@v1
+      with:
+        gitgitgadget-git-access-token: ${{ steps.gitgitgadget-git-token.outputs.token }}
+        git-git-access-token: ${{ steps.git-git-token.outputs.token }}
+        dscho-git-access-token: ${{ steps.dscho-git-token.outputs.token }}
+        smtp-options: '{"user": "[email protected]", "host": "smtp.gmail.com", "pass": ${{ toJSON(secrets.GITGITGADGET_SMTP_PASS) }}}'
+        command: handle-pr-comment ${{ inputs.pr-comment-url }}

The biggest pro I see here that we will need only one action.yml/index.js pair and therefore can even make the CIHelper class the GitHub Action (by detecting whether this is the main entry point using if (import.meta.url.endsWith(process.argv[1]) CIHelper.main().catch((e) => { console.error(e); process.exitCode = 1; }).

@webstech what is your opinion?