flowzone.yml

.flowzone:
  - &ifInternalPullRequest # check if the PR is from a fork by comparing the repository name
    if: github.event.pull_request.head.repo.full_name == github.repository

  - &ifExternalPullRequest # check if the PR is from a fork by comparing the repository name
    if: github.event.pull_request.head.repo.full_name != github.repository

  - &ifPrivateRepository
    if: github.event.repository.private

  - &ifPublicRepository
    if: github.event.repository.private != true

  - &getGitHubAppToken # https://github.com/marketplace/actions/github-app-token
    name: Generate GitHub App installation token
    uses: tibdex/github-app-token@3beb63f4bd073e61482598c45c71c1019b59b73a # v2.1.0
    if: inputs.app_id
    id: gh_app_token
    with: &getGitHubAppTokenWith
      app_id: ${{ inputs.app_id }}
      installation_retrieval_mode: organization
      installation_retrieval_payload: ${{ github.repository_owner }}
      private_key: ${{ secrets.GH_APP_PRIVATE_KEY }}
      permissions: >-
        {
          "contents": "read",
          "metadata": "read"
        }

  # optionally attempt to get AWS login short-lived session credentials over OIDC
  - &configureAWSCredentials # https://github.com/aws-actions/configure-aws-credentials
    name: Configure AWS credentials
    id: aws_credentials
    uses: aws-actions/configure-aws-credentials@4fc4975a852c8cd99761e2de1f4ba73402e44dd9 # v4.0.3
    # skip if the PR is from a fork or aws region is unset
    if: |
      ( matrix.region != '' || inputs.aws_region != '' ) &&
      github.event.pull_request.head.repo.full_name == github.repository
    continue-on-error: true
    with:
      role-to-assume: ${{ matrix.role || inputs.aws_iam_role }}
      role-session-name: github-${{ github.job }}-${{ github.run_id }}-${{ github.run_attempt }}
      aws-region: ${{ matrix.region || inputs.aws_region }}
      # https://github.com/orgs/community/discussions/26636#discussioncomment-3252664
      mask-aws-account-id: false

  - &generatePythonMetadata
    name: Generate Python metadata
    id: python_meta
    run: |
      package="$(poetry version --no-ansi | awk '{print $1}')"
      version="$(poetry version --no-ansi | awk '{print $2}')"
      commit_sha="$(echo ${{ github.event.pull_request.head.sha }} | tr "a-z" "A-Z")"
      decimal_sha="$(echo "ibase=16; $commit_sha" | bc)"
      version_tag="${version}-dev${decimal_sha}"

      echo "package=${package}" >> "${GITHUB_OUTPUT}"
      echo "version=${version}" >> "${GITHUB_OUTPUT}"
      echo "version_tag=${version_tag}" >> "${GITHUB_OUTPUT}"

  - &getTimeStamp
    name: Get and format timestamp
    id: timestamp
    env:
      FORMAT: "%Y-%m-%d-%H%M%S"
    run: |
      echo "datetime=$(date +"${FORMAT}")" >> $GITHUB_OUTPUT

  # https://octokit.github.io/rest.js/v21/#git-create-tag
  # https://docs.github.com/en/rest/git/tags#create-a-tag-object
  - &createTagObject
    name: Create tag object
    id: create_tag
    env:
      TAG: ${{ steps.versionist.outputs.tag }}
      MESSAGE: ${{ steps.versionist.outputs.tag }}
      SHA: ${{ steps.create_commit.outputs.sha }}
    uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
    with:
      github-token: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
      result-encoding: json
      script: |
        const { data: tag } = await github.rest.git.createTag({
          ...context.repo,
          tag: process.env.TAG,
          message: process.env.MESSAGE,
          object: process.env.SHA,
          type: 'commit'
        });
        core.setOutput('sha', tag.sha);
        return tag;

  # https://octokit.github.io/rest.js/v21/#git-update-ref
  # https://docs.github.com/en/rest/git/refs#update-a-reference
  # remove any refs/ prefix from the ref
  - &updateGitReference
    name: Update git reference (force)
    env:
      REF: "heads/${{ github.base_ref }}"
      SHA: ${{ steps.create_commit.outputs.sha }}
    uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
    with:
      github-token: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
      result-encoding: json
      script: |
        const { data: ref } = await github.rest.git.updateRef({
          ...context.repo,
          ref: process.env.REF.replace(/^refs\//, ''),
          sha: process.env.SHA,
          force: true
        });
        return ref;

  # https://octokit.github.io/rest.js/v21/#git-create-ref
  # https://docs.github.com/en/rest/git/refs?apiVersion=2022-11-28#create-a-reference
  - &createGitReference
    name: Create git reference
    env:
      REF: "refs/tags/${{ steps.versionist.outputs.tag }}"
      SHA: ${{ steps.create_tag.outputs.sha }}
    uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
    with:
      github-token: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
      result-encoding: json
      script: |
        const { data: ref } = await github.rest.git.createRef({
          ...context.repo,
          ref: process.env.REF,
          sha: process.env.SHA
        });
        return ref;

  - &checkoutAuth
    token: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
    persist-credentials: false

  - &checkoutPullRequestMergeRef
    # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request
    # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target
    # https://github.com/actions/checkout
    name: Checkout pull request merge ref
    uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
    with:
      fetch-depth: 0
      submodules: "recursive"
      ref: "refs/pull/${{ github.event.number }}/merge"
      <<: *checkoutAuth

  - &checkoutPullRequestHeadSha
    # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request
    # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target
    # https://github.com/actions/checkout
    name: Checkout pull request head sha
    uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
    with:
      fetch-depth: 0
      submodules: "recursive"
      # fallback to an invalid ref if the checkout ref is undefined
      ref: ${{ github.event.pull_request.head.sha || '¯\_(ツ)_/¯' }}
      <<: *checkoutAuth

  - &checkoutEventSha
    # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request
    # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target
    # https://github.com/actions/checkout
    name: Checkout ${{ github.sha }}
    uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
    with:
      fetch-depth: 0
      submodules: "recursive"
      # fallback to an invalid ref if the checkout ref is undefined
      ref: ${{ github.sha || '¯\_(ツ)_/¯' }}
      <<: *checkoutAuth

  - &checkoutVersionedSha # https://github.com/actions/checkout
    name: Checkout versioned commit
    uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
    with:
      fetch-depth: "${{ needs.versioned_source.outputs.depth || 0 }}"
      # Note that fetch-tags is not currently working as described:
      # https://github.com/actions/checkout/issues/1781
      fetch-tags: true
      submodules: "recursive"
      # fallback to an invalid ref if the checkout ref is undefined
      ref: "${{ needs.versioned_source.outputs.sha || '¯\_(ツ)_/¯' }}"
      <<: *checkoutAuth

  - &shallowCheckout # https://github.com/actions/checkout
    name: Checkout source
    uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
    with:
      # Disable submodules and deep cloning.
      fetch-depth: 1
      submodules: false
      # Do not persist credentials.
      persist-credentials: false
      # Use the automatic actions token with contents:read permissions
      token: ${{ github.token }}
      # Use the tip of the pull request branch for pull request (target) events.
      # Use the event sha for other events.
      ref: ${{ github.event.pull_request.head.sha || github.sha }}

  - &resetGitHubDirectory
    # checkout the tip of BASE if the PR is from a fork
    # or the merge commit if the PR is internal
    name: Reset .github directory to ${{ github.ref }}
    env:
      GIT_AUTH_TOKEN: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
    # Use bash without tracing to avoid leaking secrets
    shell: bash
    # Create base64 encoded auth header
    #
    # Use git-c for non-persistent credential configuration
    #
    # The git -c option sets a configuration value for a single Git command invocation.
    # It does not modify any configuration files or persist the setting beyond this specific command.
    #
    # This approach ensures that the authentication credentials are used securely for this
    # specific operation without risk of unintended persistence or exposure in configuration files.
    run: |
      auth_header=$(printf "x-access-token:${GIT_AUTH_TOKEN}" | base64 | tr -d '\n')
      git -c "http.https://github.com/.extraheader=Authorization: basic ${auth_header}" fetch origin ${{ github.ref }}
      git checkout FETCH_HEAD -- .github

  # Resolve tag, semver, sha, and description of current git working copy.
  # tag is the latest tag that points to the current commit.
  # semver is the semantic version of the tag.
  # describe is the output of `git describe --tags --always --dirty`.
  # sha is the full commit hash.
  # depth is set to a default number of commits to fetch on downstream jobs
  # (enough to get last two tags, or 0 for all commits when submodules are present)
  - &describeGitState
    name: Describe git state
    id: git_describe
    run: |
      tag="$(git tag --points-at HEAD | tail -n1)"
      {
        echo "tag=${tag}" ;
        echo "semver=$(npx -q -y -- semver -c -l "${tag}")" ;
        echo "describe=$(git describe --tags --always --dirty | cat)" ;
        echo "sha=$(git rev-parse HEAD)" ;
      } >> "${GITHUB_OUTPUT}"

      if [[ "$(git submodule)" = "" ]]; then
        echo "depth=1" >> "${GITHUB_OUTPUT}"
      else
        echo "depth=0" >> "${GITHUB_OUTPUT}"
      fi

  # Create a local reference for the versioned tag so that it
  # may be consumed by build steps that need to know the version of the source.
  # These refs should already exist on merge/finalize.
  - &createLocalRefs
    name: Create local tag for draft version
    if: github.event.pull_request.state == 'open' && inputs.disable_versioning != true
    run: |
      git update-ref refs/tags/${{ needs.versioned_source.outputs.tag }} ${{ needs.versioned_source.outputs.tag_sha }}

  - &loginWithDockerHub
    name: Login to Docker Hub
    continue-on-error: true
    uses: docker/login-action@9780b0c442fbb1117ed29e0efdff1e18412f7567 # v3.3.0
    with:
      registry: docker.io
      username: ${{ secrets.DOCKERHUB_USER || secrets.DOCKER_REGISTRY_USER }}
      password: ${{ secrets.DOCKERHUB_TOKEN || secrets.DOCKER_REGISTRY_PASS }}

  - &loginWithGitHubContainerRegistry
    name: Login to GitHub Container Registry
    continue-on-error: true
    uses: docker/login-action@9780b0c442fbb1117ed29e0efdff1e18412f7567 # v3.3.0
    with:
      # Feb 2023: as per GitHub support: "You cannot authenticate with a GitHub App token on the GitHub Package Registry"
      # Nov 2024: Still cannot use GitHub App Tokens to authenticate with the GitHub Package Registry (login works, push/pull fails)
      registry: ghcr.io
      username: ${{ github.actor }}
      password: ${{ secrets.GITHUB_TOKEN }}

  - &loginWithECRPublic
    name: Login to AWS/ECR (public)
    if: steps.aws_credentials.outcome == 'success'
    continue-on-error: true
    uses: docker/login-action@9780b0c442fbb1117ed29e0efdff1e18412f7567 # v3.3.0
    with:
      registry: public.ecr.aws

  - &loginWithECRPrivate
    name: Login to AWS/ECR (private)
    if: steps.aws_credentials.outcome == 'success'
    continue-on-error: true
    uses: docker/login-action@9780b0c442fbb1117ed29e0efdff1e18412f7567 # v3.3.0
    with:
      registry: ${{ matrix.image }}

  - &customWorkingDirectory
    defaults:
      run:
        working-directory: ${{ inputs.working_directory }}
        shell: bash --noprofile --norc -eo pipefail -x {0}

  - &rootWorkingDirectory
    defaults:
      run:
        working-directory: .
        shell: bash --noprofile --norc -eo pipefail -x {0}

  - &gitHubCliEnvironment
    # environment variables used by gh CLI
    # https://cli.github.com/manual/gh_help_environment
    GH_DEBUG: "true"
    GH_PAGER: "cat"
    GH_PROMPT_DISABLED: "true"
    GH_REPO: "${{ github.repository }}"

  - &rejectExternalCustomActions
    name: Reject external custom actions
    if: |
      github.event.pull_request.state == 'open' &&
      github.event.pull_request.head.repo.full_name != github.repository &&
      inputs.restrict_custom_actions == true
    run: |
      echo "::error::Custom actions are disabled for external contributors and will be skipped. \
        Please contact a member of the organization for assistance."
      exit 1

  - &logGitHubContext
    name: Log GitHub context
    env:
      GITHUB_CONTEXT: ${{ toJSON(github) }}
    run: echo "${GITHUB_CONTEXT}" || true

  - &deleteDraftGitHubRelease
    name: Delete draft GitHub release
    run: gh release delete --yes "${GITHUB_HEAD_REF}" || true
    env:
      <<: *gitHubCliEnvironment
      GH_TOKEN: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}

  - &jsonArrayBuilder
    name: Build JSON list from comma-separated input
    uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
    with:
      result-encoding: json
      script: |
        // Remove whitespace from input
        const input = process.env.INPUT?.replace(/\s+/g, '') || '';

        // Split by delimiter (will return [''] for empty input)
        return !input ? [''] : input.split(',');

  - &newlineListBuilder
    name: Build newline-separated list from JSON list input
    uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
    with:
      result-encoding: string
      script: |
        return JSON.parse(process.env.INPUT).join('\n');

  - &dockerPlatformSlugMap
    PLATFORM_SLUG_MAP: >
      {
        "linux/386": "i386",
        "linux/amd64": "amd64",
        "linux/arm64": "arm64v8",
        "linux/arm/v7": "arm32v7",
        "linux/arm/v6": "arm32v6",
        "linux/arm/v5": "arm32v5",
        "linux/s390x": "s390x",
        "linux/mips64le": "mips64le",
        "linux/ppc64le": "ppc64le",
        "linux/riscv64": "riscv64",
        "windows/amd64": "windows-amd64"
      }

  - &sanitizeDockerStrings
    name: Sanitize docker strings
    uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
    id: strings
    env:
      TARGET: ${{ matrix.target }}
      IMAGE: ${{ matrix.image }}
      DOCKER_INVERT_TAGS: ${{ inputs.docker_invert_tags }}
    with:
      result-encoding: json
      script: |
        const target = process.env.TARGET;
        const image = process.env.IMAGE;
        const invertTags = process.env.DOCKER_INVERT_TAGS === 'true';

        // Sanitize target to slug
        const targetSlug = target.replace(/[^a-zA-Z0-9]/g, '-');

        if (target && !targetSlug) {
          core.setFailed(`Unsupported platform: ${target}`);
          return;
        }

        // Set prefix/suffix based on target
        let prefixSlug = '';
        let suffixSlug = '';
        if (target !== 'default') {
          if (invertTags) {
            prefixSlug = `${targetSlug}-`;
          } else {
            suffixSlug = `-${targetSlug}`;
          }
        }

        // Process image string
        let imageSlug = '';
        let repoSlug = '';

        if (image) {
          if (image.includes('.')) {
            // tl.d/org/repo(:tag)? -> tl.d/org/repo
            imageSlug = image.split(':')[0];
          } else {
            // org/repo(:tag)? -> docker.io/org/repo
            imageSlug = `docker.io/${image.split(':')[0]}`;
          }
          // tl.d/org/repo -> org/repo
          repoSlug = imageSlug.split('/').slice(1).join('/');
        }

        core.setOutput('image', imageSlug)
        core.setOutput('target', targetSlug)
        core.setOutput('prefix', prefixSlug)
        core.setOutput('suffix', suffixSlug)
        core.setOutput('repo', repoSlug)

  - &dockerTestMetadata # https://github.com/docker/metadata-action
    name: Generate docker metadata
    id: test_meta
    uses: docker/metadata-action@369eb591f429131d6889c46b94e711f089e6ca96 # v5.6.1
    with: &dockerTestMetaWith
      images: |
        sut
        localhost:5000/sut
        ${{ needs.is_docker.outputs.docker_images_crlf }}
      labels: |
        org.opencontainers.image.version=${{ needs.versioned_source.outputs.semver }}
        org.opencontainers.image.ref.name=${{ matrix.target }}
      tags: |
        type=raw,value=${{ github.event.pull_request.head.sha }}
        type=raw,value=build-${{ github.event.pull_request.head.sha }}
        type=raw,value=build-${{ github.event.pull_request.head.ref }}
      flavor: |
        latest=true
        prefix=${{ steps.strings.outputs.prefix }}
        suffix=${{ steps.strings.outputs.suffix }}

  - &dockerCacheFromMetadata
    <<: *dockerTestMetadata
    id: cache_meta
    # ensure docker_images_crlf is not an empty list
    if: needs.is_docker.outputs.docker_images_crlf != ''
    with:
      images: |
        ${{ needs.is_docker.outputs.docker_images_crlf }}
      tags: |
        type=raw,value=${{ github.base_ref || github.ref_name }}
        type=raw,value=${{ github.event.pull_request.head.sha }}
        type=raw,value=build-${{ github.event.pull_request.head.sha }}
        type=raw,value=build-${{ github.event.pull_request.head.ref }}
      flavor: |
        latest=true
        prefix=${{ steps.strings.outputs.prefix }},onlatest=true
        suffix=${{ steps.strings.outputs.suffix }},onlatest=true

  - &dockerDraftMetadata
    <<: *dockerTestMetadata
    id: draft_meta
    with:
      <<: *dockerTestMetaWith
      images: |
        ${{ matrix.image }}
      flavor: |
        latest=false
        prefix=${{ steps.strings.outputs.prefix }}
        suffix=${{ steps.strings.outputs.suffix }}

  - &dockerFinalMetadata
    <<: *dockerTestMetadata
    id: final_meta
    with:
      <<: *dockerTestMetaWith
      images: |
        ${{ matrix.image }}
      # for unversioned merges we will use the base branch as the tag
      # and version tag and semver will be empty
      tags: |
        type=raw,value=${{ github.base_ref || github.ref_name }}
        type=raw,value=${{ needs.versioned_source.outputs.tag }}
        type=raw,value=${{ needs.versioned_source.outputs.semver }}
      flavor: |
        latest=${{ needs.versioned_source.outputs.semver != '' }}
        prefix=${{ steps.strings.outputs.prefix }},onlatest=true
        suffix=${{ steps.strings.outputs.suffix }},onlatest=true

  - &rejectMissingSecrets
    name: Reject missing secrets
    run: |
      if [ -z '${{ secrets.FLOWZONE_TOKEN }}${{ secrets.GH_APP_PRIVATE_KEY }}' ]
      then
        echo '::error::Must specify either GH_APP_PRIVATE_KEY or FLOWZONE_TOKEN.'
        false
      fi

  - &rejectFailedJobs
    name: Reject failed jobs
    run: |
      if [ "${{ contains(needs.*.result, 'failure') }}" = "true" ]
      then
        echo "One or more jobs have failed"
        exit 1
      fi

  - &rejectCancelledJobs
    name: Reject cancelled jobs
    run: |
      if [ "${{ contains(needs.*.result, 'cancelled') }}" = "true" ]
      then
        echo "One or more jobs were cancelled"
        exit 1
      fi

  - &rejectExternalPullRequest
    name: Reject external pull_request events on pull_request
    if: |
      github.event_name == 'pull_request' &&
      github.event.pull_request.head.repo.full_name != github.repository
    run: |
      echo "::error::External workflows can not be used with 'pull_request' events. \
        Please contact a member of the organization for assistance."
      exit 1

  - &rejectInternalPullRequestTarget
    name: Reject internal pull_request events on pull_request_target
    if: |
      github.event_name == 'pull_request_target' &&
      github.event.pull_request.head.repo.full_name == github.repository
    run: |
      echo "::error::Internal workflows should not be used with 'pull_request_target' events. \
        Please consult the documentation for more information."
      exit 1

  - &rejectNonLinearHead
    # This can happen when a PR is updated with a merge commit from main, rather than rebased on main.
    # In the GitHub UI this is represented by the "Update with merge commit" option vs "Update with rebase".
    # https://github.com/actions/github-script
    # https://octokit.github.io/rest.js/v21/#pulls-list-commits
    name: Reject HEAD branches containing merge commits
    if: github.event.pull_request.state == 'open'
    uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
    with:
      github-token: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
      result-encoding: json
      script: |
        const { data: commits } = await github.rest.pulls.listCommits({
          ...context.repo,
          pull_number: context.payload.pull_request.number
        });

        if (commits.some(({ parents }) => parents.length > 1)) {
          throw new Error('Non-linear history detected - merge commit(s) identified in HEAD branch');
        }

  - &rejectNonLinearMerge
    # This can happen if multiple PRs are merged at the same time, typically because
    # one PR is rebased on another PR before merging, where the merge commit in the BASE
    # branch does not include the tip of the HEAD branch as a parent.
    # https://github.com/actions/github-script
    # https://octokit.github.io/rest.js/v21/#repos-get-commit
    name: Reject merge commits that do not include the HEAD commit as a parent
    # This check passes when the PR is open too, but only on pull_request events and not pull_request_target.
    # So only check on merged PRs where the HEAD sha should always be a parent of the merge commit.
    if: github.event.pull_request.merged
    uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
    with:
      github-token: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
      result-encoding: json
      script: |
        console.debug(`Merge commit SHA: ${context.sha}`)
        console.debug(`HEAD commit SHA: ${context.payload.pull_request.head.sha}`)

        const { data: commit } = await github.rest.repos.getCommit({
          ...context.repo,
          ref: context.sha
        });

        console.debug('Commit parents: %s', JSON.stringify(commit.parents, null, 2))

        if (!commit.parents.some(({ sha }) => sha === context.payload.pull_request.head.sha)) {
          throw new Error('Non-linear history detected - HEAD branch commit is not a parent of the merge commit');
        }

  - &setupBuildx # https://github.com/docker/setup-buildx-action
    name: Setup buildx
    id: setup_buildx
    uses: docker/setup-buildx-action@6524bf65af31da8d45b59e8c27de4bd072b392f5 # v3.8.0
    env:
      # renovate: datasource=github-releases depName=docker/buildx
      BUILDX_VERSION: v0.20.0
    with:
      driver-opts: network=host
      install: true
      version: ${{ env.BUILDX_VERSION }}

  - &setupQemuBinfmt # https://github.com/docker/setup-qemu-action
    name: Setup QEMU
    id: qemu_binfmt
    uses: docker/setup-qemu-action@53851d14592bedcffcf25ea515637cff71ef929a # v3.3.0
    env:
      LOG_LEVEL: debug
      # renovate: datasource=docker depName=tonistiigi/binfmt
      BINFMT_VERSION: qemu-v8.0.4-33
    with:
      platforms: ${{ matrix.platform }}
      # https://hub.docker.com/r/tonistiigi/binfmt
      image: tonistiigi/binfmt:${{ env.BINFMT_VERSION }}

  - &setupNode # https://github.com/actions/setup-node
    name: Setup Node.js
    uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0
    env:
      # renovate: datasource=node-version depName=node packageName=node-20.x
      NODE_VERSION: 20.18.2
    with:
      node-version: ${{ env.NODE_VERSION }}

  - &setupCrane # https://github.com/imjasonh/setup-crane
    name: Setup crane
    uses: imjasonh/setup-crane@31b88efe9de28ae0ffa220711af4b60be9435f6e # v0.4
    with:
      version: v0.14.0

  - &setupPython # https://github.com/actions/setup-python
    name: Setup python
    id: setup-python
    uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5.3.0
    with:
      python-version: "3.9"

  - &setupPoetry # https://github.com/abatilo/actions-poetry
    name: Setup poetry
    if: steps.setup-python.outputs.python-version != ''
    uses: abatilo/actions-poetry@3765cf608f2d4a72178a9fc5b918668e542b89b1 # v4.0.0
    with:
      poetry-version: "1.5.1"

  - &setupSkopeo # https://github.com/product-os/setup-skopeo-action
    name: Setup skopeo
    uses: product-os/setup-skopeo-action@5a3989811388c16b01f29554996e0c7e802b410b # v0.0.2
    with:
      # https://github.com/lework/skopeo-binary/releases
      version: "v1.15.0"

  - &setupAwsCli
    name: Setup AWS CLI
    uses: product-os/setup-awscli-action@4a9adeb45575339cd63be25b2c928b59c0ecad7b # v0.0.9
    with:
      version: "2.15.43"

  - &waitForCloudFormation
    name: Wait for resources
    run: |
      stack_status="$(aws cloudformation describe-stacks \
        --stack-name '${{ matrix.stack }}' --output text --query Stacks[*].StackStatus || true)"

      if [[ -n "$stack_status" ]]; then
          aws cloudformation wait stack-exists --stack-name '${{ matrix.stack }}'

          if [[ "$stack_status" =~ CREATE_IN_PROGRESS ]]; then
              aws cloudformation wait stack-create-complete --stack-name '${{ matrix.stack }}'
          fi

          if [[ "$stack_status" =~ UPDATE_IN_PROGRESS ]]; then
              aws cloudformation wait stack-update-complete --stack-name '${{ matrix.stack }}'
          fi

          if [[ "$stack_status" =~ ROLLBACK_IN_PROGRESS ]]; then
              aws cloudformation wait stack-rollback-complete --stack-name '${{ matrix.stack }}'
          fi

          aws cloudformation describe-stacks --stack-name '${{ matrix.stack }}'
      fi

  - &getAWSCallerIdentity
    name: Get caller identity (AWS/whoami)
    if: steps.aws_credentials.outcome == 'success'
    continue-on-error: true
    run: aws sts get-caller-identity

  - &updateKubeconfig
    name: Update kubeconfig
    run: |
      aws eks update-kubeconfig --name "$(echo "${KUBE_CTX}" | awk -F'/' '{print $2}')"

  - &publishSBOMArtifacts
    name: Publish SBOM artifacts
    uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4.6.0

  - &publishSBOMToDependencyTrack
    name: Publish SBOM To Dependency Track
    if: ${{ env.SERVER_HOSTNAME != '' }}
    run: |
      curl -X "PUT" "https://${{ env.SERVER_HOSTNAME }}/api/v1/bom" \
        -H 'Content-Type: application/json' \
        -H 'X-API-Key: ${{env.API_KEY}}' \
         -d '{
          "projectName": "'"${{env.PROJECT_NAME}}"'",
          "projectVersion": "'"${{env.PROJECT_VERSION}}"'",
          "autoCreate": "true",
          "bom": "'"$(base64 -w 0 "${{ env.BOM_FILE }}")"'"
        }'

  - &convenienceFunctions
    name: Convenience functions
    id: functions
    run: |
      # shellcheck disable=SC2034
      EOF="$(openssl rand -hex 16)"

      # https://sre.google/sre-book/addressing-cascading-failures/
      with_backoff="$(mktemp)"
      cat << $EOF > "${with_backoff}"
      function with_backoff() {
          local max_attempts=\${ATTEMPTS-3}
          local timeout=\${TIMEOUT-2}
          local attempt=0
          local exitCode=0
          set +e
          while [[ \$attempt < \$max_attempts ]]; do
              "\$@"
              exitCode=\$?
              [[ \$exitCode == 0 ]] && break
              echo "Failure! Retrying in \$timeout.." 1>&2
              sleep "\$timeout"
              attempt=\$(( attempt + 1 ))
              timeout=\$(( timeout * 2 ))
          done
          [[ \$exitCode != 0 ]] && echo "You've failed me for the last time! (\$*)" 1>&2
          set -e
          return \$exitCode
      }
      $EOF
      echo "with_backoff=${with_backoff}" >> "${GITHUB_OUTPUT}"

  - &randomDelay
    name: Random delay
    run: |
      DELAY="${DELAY-5}"
      random="$(((RANDOM % DELAY) + 1))"
      echo "sleeping for ${random}s"
      sleep "${random}s"

name: Flowzone

on:
  workflow_call:
    secrets:
      # https://github.com/organizations/product-os/settings/secrets/actions/GH_APP_PRIVATE_KEY
      GH_APP_PRIVATE_KEY:
        description: "GitHub App to generate ephemeral access tokens"
        required: false
      FLOWZONE_TOKEN:
        description: ".. or Personal Access Token (PAT) with admin/owner permissions in the org."
        required: false
      NPM_TOKEN:
        description: "The npm auth token to use for publishing"
        required: false
      DOCKERHUB_USER:
        description: "Username to publish to the Docker Hub container registry"
        required: false
      DOCKER_REGISTRY_USER:
        description: "Deprecated, use DOCKERHUB_USER instead"
        required: false
      DOCKERHUB_TOKEN:
        description: "A personal access token to publish to the Docker Hub container registry"
        required: false
      DOCKER_REGISTRY_PASS:
        description: "Deprecated, use DOCKERHUB_TOKEN instead"
        required: false
      BALENA_API_KEY:
        description: "API key for pushing releases to balena applications"
        required: false
      BALENA_API_KEY_PUSH:
        description: "Deprecated, use BALENA_API_KEY instead"
        required: false
      CARGO_REGISTRY_TOKEN:
        description: "A personal access token to publish to a cargo registry"
        required: false
      COMPOSE_VARS:
        description: "Optional base64 encoded docker-compose `.env` file for testing Docker images"
        required: false
      CF_ACCOUNT_ID:
        description: "Cloudflare account ID"
        required: false
      CF_API_TOKEN:
        description: "Cloudflare API token with limited access for Pages projects"
        required: false
      PYPI_TOKEN:
        description: "Token to publish to pypi.org"
        required: false
      PYPI_TEST_TOKEN:
        description: "Token to publish to test.pypi.org"
        required: false
      ZULIP_API_KEY:
        description: "API key to post Zulip messages."
        required: false
      CUSTOM_JOB_SECRET_1:
        description: "Optional secret for using with custom jobs"
        required: false
      CUSTOM_JOB_SECRET_2:
        description: "Optional secret for using with custom jobs"
        required: false
      CUSTOM_JOB_SECRET_3:
        description: "Optional secret for using with custom jobs"
        required: false
      DTRACK_TOKEN:
        description: "API key for Dependency-Track integration"
        required: false

    inputs:
      aws_region:
        description: "AWS region with GitHub OIDC provider IAM configuration"
        type: string
        required: false
        default: "${{ vars.AWS_REGION || '' }}"
      aws_iam_role:
        description: "AWS IAM role ARN to assume with GitHub OIDC provider"
        type: string
        required: false
        default: "${{ vars.AWS_IAM_ROLE || '' }}"
      cloudformation_templates:
        description: |
          AWS CloudFormation templates to deploy (e.g.)

          ```
          {
            "stacks": [
              {
                "name": "foo",
                "template": "aws/bar.yaml",
                "tags": [
                  "Name=foo",
                  "Environment=${FOO}"
                ],
                "capabilities": [
                  "CAPABILITY_IAM",
                  "CAPABILITY_NAMED_IAM"
                ]
              },
              ...
            ]
          }
          ```

          * assumes `aws/bar.yaml` exists.
          * `${ENVVARS}` injected at runtime from `vars` and `secrets` contexts
        type: string
        required: false
        default: ""
      app_id:
        description: "GitHub App ID to impersonate"
        type: string
        required: false
        default: "${{ vars.FLOWZONE_APP_ID || vars.APP_ID }}"
      # not needed if installed on this current org/repo
      installation_id:
        description: "Deprecated, no longer used"
        type: string
        required: false
      token_scope:
        description: "Ephemeral token scope(s)"
        type: string
        required: false
        # https://github.com/organizations/product-os/settings/installations/34040165
        # https://docs.github.com/en/rest/apps/apps?apiVersion=2022-11-28#create-a-scoped-access-token
        default: >-
          {
            "administration": "write",
            "contents": "write",
            "metadata": "read",
            "packages": "write",
            "pages": "write",
            "pull_requests": "read"
          }
      jobs_timeout_minutes:
        description: "Timeout for the job(s)."
        type: number
        required: false
        default: 360
      working_directory:
        description: "GitHub actions working directory"
        type: string
        required: false
        default: "."
      docker_images:
        description: "Comma-delimited string of Docker images (without tags) to publish (skipped if empty)"
        type: string
        required: false
        default: ""
      bake_targets:
        description: "Comma-delimited string of Docker buildx bake targets to publish (skipped if empty)"
        type: string
        required: false
        default: "default"
      docker_invert_tags:
        description: "Invert the tags for the Docker images (e.g. `{tag}-{variant}` becomes `{variant}-{tag}`)"
        type: boolean
        required: false
        default: false
      docker_publish_platform_tags:
        description: "Publish platform-specific tags in addition to multi-arch manifests (e.g. `product-os/flowzone:latest-amd64`)"
        type: boolean
        required: false
        default: false
      balena_environment:
        description: "balenaCloud environment"
        type: string
        required: false
        default: balena-cloud.com
      balena_slugs:
        description: "Comma-delimited string of balenaCloud apps, fleets, or blocks to deploy (skipped if empty)"
        type: string
        required: false
        default: ""
      cargo_targets:
        description: "Comma-delimited string of Rust stable targets to publish (skipped if empty)"
        type: string
        required: false
        default: |
          aarch64-unknown-linux-gnu,
          armv7-unknown-linux-gnueabihf,
          arm-unknown-linux-gnueabihf,
          x86_64-unknown-linux-gnu,
          i686-unknown-linux-gnu
      rust_toolchain:
        description: "Version specifier (e.g. 1.65, stable, nigthly) for the toolchain to use when building Rust sources"
        type: string
        required: false
        default: stable
      rust_binaries:
        description: "Set to true to publish Rust binary release artifacts to GitHub"
        type: boolean
        required: false
        default: false
      pseudo_terminal:
        description: "Set to true to enable terminal emulation for test steps"
        type: boolean
        required: false
        default: false
      disable_versioning:
        description: "Set to true to disable automatic versioning"
        type: boolean
        required: false
        default: false
      runs_on:
        description: "JSON array of runner label strings for default jobs."
        type: string
        required: false
        default: >
          [
            "ubuntu-24.04"
          ]
      docker_runs_on:
        description: "JSON key-value pairs mapping platforms to arrays of runner labels. Unlisted platforms will use `runs_on`."
        type: string
        required: false
        default: "{}"
      cloudformation_runs_on:
        description: "JSON array of runner label strings for cloudformation jobs."
        type: string
        required: false
      cloudflare_website:
        description: "Setting this to your existing CF pages project name will generate and deploy a website. Skipped if empty."
        type: string
        required: false
        default: ""
      docusaurus_website:
        description: "Set to false to disable building a docusaurus website. If false the script `npm run deploy-docs` will be run if it exists."
        type: boolean
        required: false
        default: true
      github_prerelease:
        description: "Finalize releases on merge."
        type: boolean
        required: false
        default: false
      restrict_custom_actions:
        description: "Do not execute custom actions for external contributors. Only remove this restriction if custom actions have been vetted as secure."
        type: boolean
        required: false
        default: true
      custom_test_matrix:
        description: "JSON matrix strategy for the custom test action. Properties 'environment' and 'os' will be applied to the job."
        type: string
        required: false
        default: ""
      custom_publish_matrix:
        description: "JSON matrix strategy for the custom publish action. Properties 'environment' and 'os' will be applied to the job."
        type: string
        required: false
        default: ""
      custom_finalize_matrix:
        description: "JSON matrix strategy for the custom finalize action. Properties 'environment' and 'os' will be applied to the job."
        type: string
        required: false
        default: ""
      custom_runs_on:
        description: "Deprecated. Add the 'os' property in custom_test_matrix, custom_publish_matrix, and custom_finalize_matrix instead."
        type: string
        required: false
      toggle_auto_merge:
        description: "Set to false to disable toggling auto-merge on PRs."
        type: boolean
        required: false
        default: true
      release_notes:
        description: "Create git tags and a PR comment with detailed change log."
        type: boolean
        required: false
        default: false
      max_parallel:
        description: "Set a max parallel value for ALL matrix strategy jobs."
        type: number
        required: false
        default: 20
      generate_sbom:
        description: "Generate a Software Bill of Materials (SBOM) for the release."
        type: boolean
        required: false
        default: true
    outputs:
      cloudflare_deployment_url:
        description: "Cloudflare Deployment URL"
        value: ${{ jobs.website_publish.outputs.cloudflare_deployment_url }}

# https://docs.github.com/en/actions/using-jobs/using-concurrency
# https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs
# - For open pull_request events, the group will be Flowzone-refs/heads/mybranch and cancel-in-progress will be true
# - For merged pull_request events, the group will be Flowzone-refs/heads/master and cancel-in-progress will be false
# - For closed pull_request events, the group will be Flowzone-refs/heads/mybranch and cancel-in-progress will be true
# - For open pull_request_target events, the group will be Flowzone-refs/heads/master and cancel-in-progress will be false
# - For merged pull_request_target events, the group will be Flowzone-refs/heads/master and cancel-in-progress will be false
# - For closed pull_request_target events, the group will be Flowzone-refs/heads/master and cancel-in-progress will be false
# - For tag push events, the group will be Flowzone-v1.2.3 and cancel-in-progress will be false
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  # Expressions in the concurrency context do not have access
  # to the entire github.event context so we cannot make advanced
  # expressions beyond a few top level github event properties.

  # See: https://github.com/orgs/community/discussions/69704#discussioncomment-7803351

  # Cancel jobs in-progress for open PRs, but not merged or closed PRs, by checking for the merge ref.
  # Note that for pull_request_target events (PRs from forks), the github.ref value is
  # usually 'refs/heads/master' so we can't rely on that to determine if it is a merge event or not.
  # As a result pull_request_target events will never cancel in-progress jobs and will be queued instead.
  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}

env:
  NPM_REGISTRY: "https://registry.npmjs.org"
  CARGO_REGISTRY: crates.io

jobs:
  event_types:
    name: Event Types
    runs-on: ubuntu-24.04
    # Wait up to 60 min for workflow approvals on forks.
    # App Installation tokens expire in 1h either way.
    timeout-minutes: 60
    if: |
      (
        (
          github.event_name == 'pull_request' ||
          github.event_name == 'pull_request_target'
        ) && (
          github.event.action == 'opened' ||
          github.event.action == 'synchronize' ||
          github.event.action == 'closed'
        )
      ) || (
        github.event_name == 'push' &&
        startsWith(github.ref, 'refs/tags/')
      )

    strategy:
      fail-fast: true
      matrix:
        include:
          - event_name: ${{ github.event_name }}
            event_action: ${{ github.event.action }}

    permissions: {}

    steps:
      - *rejectExternalPullRequest
      - *rejectInternalPullRequestTarget
      - *rejectMissingSecrets

      - <<: *getGitHubAppToken
        with:
          <<: *getGitHubAppTokenWith
          # pull_requests: write is required to create or update pull request comments
          permissions: >-
            {
              "metadata": "read",
              "issues": "read",
              "pull_requests": "write"
            }

      # Combining pull_request_target workflow trigger with an explicit checkout of an
      # untrusted PR is a dangerous practice that may lead to repository compromise.
      # https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/
      # This action requires approvals via reactions for each workflow run.
      # https://github.com/product-os/review-commit-action
      - name: Wait for approval on pull_request_target events
        if: github.event_name == 'pull_request_target' && github.event.pull_request.merged != true
        uses: product-os/review-commit-action@cddebf4cec8e40ea8f698b6dcce8cd70e38b7320 # v0.1.7
        with:
          poll-interval: "10"
          allow-authors: false
          github-token: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}

      - *logGitHubContext

  versioned_source:
    name: Versioned source
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - event_types
    # skip unmerged closed PRs, allow all other events
    if: |
      github.event.action != 'closed' || github.event.pull_request.merged == true

    <<: *rootWorkingDirectory

    permissions:
      # Required to inspect commits in branches for linear history
      contents: read

    outputs:
      tag: ${{ steps.versionist.outputs.tag || steps.git_describe.outputs.tag }}
      semver: ${{ steps.versionist.outputs.semver || steps.git_describe.outputs.semver }}
      # Note that this is NOT the same sha we use for draft artifact tagging!
      # For that we use github.event.pull_request.head.sha which aligns with the tip of the HEAD branch
      # whereas this will be the merge commit sha for PRs or the tagged commit sha for tags.
      sha: ${{ steps.create_tag.outputs.sha || steps.git_describe.outputs.sha }}
      commit_sha: ${{ steps.create_commit.outputs.sha }}
      author: ${{ steps.create_commit.outputs.author }}
      tag_sha: ${{ steps.create_tag.outputs.sha }}
      # Should be 0 (full) if git submodules are present, otherwise for minimal fetch depth.
      depth: ${{ steps.git_describe.outputs.depth || 0 }}

    env:
      <<: *gitHubCliEnvironment

    steps:
      - <<: *getGitHubAppToken
        with:
          <<: *getGitHubAppTokenWith
          # administration: write is required to bypass branch protection rules
          # contents: write is required to push git commit and tag references
          permissions: >-
            {
              "administration": "write",
              "contents": "write",
              "metadata": "read",
              "pull_requests": "read"
            }

      - *rejectNonLinearHead
      - *rejectNonLinearMerge

      # Checkout the tip of the pull request branch for open PRs.
      # The default behaviour for GitHub Actions is to checkout the merge commit but we
      # want to be able test the changes in isolation, and we already require that branches
      # be rebased before testing merging via branch rules.
      # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request
      - <<: *checkoutPullRequestHeadSha
        if: github.event.pull_request.state == 'open'

      # Checkout the event sha for closed/merged PRs.
      # This is the merge commit sha for PRs and the tagged commit sha for tags.
      - <<: *checkoutEventSha
        if: github.event.pull_request.state != 'open'

      # The current commit sha is needed as the parent sha for the versioned commit
      # and/or as default tag & semver if versioning is disabled.
      - *describeGitState

      - *setupNode

      - name: Install versioning tools
        if: inputs.disable_versioning != true
        run: |
          npm install -g \
            balena-versionist@~0.15.0 \
            versionist@^7.0.3

          npm ls -g

      - name: Generate changelog
        if: inputs.disable_versioning != true
        env:
          GH_TOKEN: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
        run: |
          if [ ! -f .versionbot/CHANGELOG.yml ]
          then
            "$(npm root -g)"/versionist/scripts/generate-changelog.sh .
          fi

      # run balena-versionist
      # print the error if anything fails
      # fail the workflow if the error is anything other than "No such file or directory"
      - name: Run versionist
        if: inputs.disable_versioning != true
        id: versionist
        env:
          GITHUB_TOKEN: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
        run: |
          out="$(balena-versionist 2>&1)"
          error="$(awk '/Error:/{getline; print}' <<< "${out}")"

          case ${error} in
            "") # no error
              ;;
            'No such file or directory'*'/package.json')
              echo "::error file=.versionbot/CHANGELOG.yml,line=1::Versionist expects a package.json if repo.yml does not provide a 'type' for the project"
              ;;
            *)
              echo "::error::${error}"
              exit 1
              ;;
          esac

          git status --porcelain

          versions=()
          [ -f .versionbot/CHANGELOG.yml ] && read -r -a versions < <(yq e '.[0].version' .versionbot/CHANGELOG.yml)
          semver="${versions[0]}"

          echo "semver=${semver}" >> "${GITHUB_OUTPUT}"
          echo "tag=v${semver}" >> "${GITHUB_OUTPUT}"

      # https://github.com/orgs/community/discussions/50055
      # https://www.levibotelho.com/development/commit-a-file-with-the-github-api/
      # https://octokit.github.io/rest.js/v21/#git-create-blob
      # https://octokit.github.io/rest.js/v21/#git-create-tree
      - name: Create blobs and tree objects
        if: inputs.disable_versioning != true
        id: create_tree
        env:
          PARENT_COMMIT_SHA: ${{ steps.git_describe.outputs.sha }}
        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
        with:
          github-token: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
          script: |
            const { execSync } = require('child_process');
            const fs = require('fs').promises;

            // Get modified and untracked files
            const getModifiedFiles = () => {
              const modifiedCmd = 'git diff --name-only';
              const untrackedCmd = 'git ls-files --others --exclude-standard';
              const modified = execSync(modifiedCmd).toString().trim().split('\n');
              const untracked = execSync(untrackedCmd).toString().trim().split('\n');
              return [...new Set([...modified, ...untracked])].filter(f => f != null && !!f.trim());
            };

            // Create tree entries for modified files
            const createTreeEntries = async () => {
              const files = getModifiedFiles();

              const entries = await Promise.all(files.map(async (file) => {
                core.info(`Creating blob for file ${file}...`);
                // Read file content and create blob
                const content = await fs.readFile(file, { encoding: 'utf8' });
                const { data: blob } = await github.rest.git.createBlob({
                  ...context.repo,
                  content: Buffer.from(content).toString("base64"),
                  encoding: 'base64'
                });

                return {
                  path: file,
                  mode: '100644',
                  type: 'blob',
                  sha: blob.sha
                };
              }));
              return entries;
            };

            // Get base tree SHA
            const parentSha = process.env.PARENT_COMMIT_SHA;
            const baseTreeSha = execSync(`git show -s --format=%T "${parentSha}"`).toString().trim();

            // Create new tree
            const treeEntries = await createTreeEntries();
            const { data: tree } = await github.rest.git.createTree({
              ...context.repo,
              tree: treeEntries,
              base_tree: baseTreeSha
            });

            core.setOutput('sha', tree.sha);
            return tree;

      # https://octokit.github.io/rest.js/v21/#git-create-commit
      # https://docs.github.com/en/rest/git/commits#create-a-commit
      - name: Create commit object
        if: inputs.disable_versioning != true
        id: create_commit
        env:
          MESSAGE: ${{ steps.versionist.outputs.tag }}
          TREE_SHA: ${{ steps.create_tree.outputs.sha }}
          PARENT_COMMIT_SHA: ${{ steps.git_describe.outputs.sha }}
        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
        with:
          github-token: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
          result-encoding: json
          script: |
            const { data: commit } = await github.rest.git.createCommit({
              ...context.repo,
              message: process.env.MESSAGE,
              tree: process.env.TREE_SHA,
              parents: [process.env.PARENT_COMMIT_SHA]
            });
            core.setOutput('author', commit.author.name);
            core.setOutput('sha', commit.sha);
            return commit;

      # create a new tag object
      - <<: *createTagObject
        if: inputs.disable_versioning != true
        env:
          GH_TOKEN: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
          TAG: ${{ steps.versionist.outputs.tag }}
          MESSAGE: ${{ steps.versionist.outputs.tag }}
          SHA: ${{ steps.create_commit.outputs.sha }}

      # update the existing branch(head) name reference(pointer) to the new commit object sha
      - <<: *updateGitReference
        if: |
          github.event.pull_request.merged &&
          steps.create_commit.outputs.sha
        env:
          GH_TOKEN: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
          REF: "heads/${{ github.base_ref }}"
          SHA: ${{ steps.create_commit.outputs.sha }}

      # create a new tag name reference(pointer) to the new tag object sha
      - <<: *createGitReference
        if: |
          github.event.pull_request.merged &&
          steps.create_tag.outputs.sha
        env:
          GH_TOKEN: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
          REF: "refs/tags/${{ steps.versionist.outputs.tag }}"
          SHA: ${{ steps.create_tag.outputs.sha }}

  release_notes:
    name: Generate release notes
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - versioned_source
    # On tag push events, we only want to generate release notes if versioning is disabled.
    # On pull_request events, we want to generate release notes if versioning is enabled.
    # Skip pull_request closed events, but allow pull_request merged events.
    # By filtering on the tag output of versioned_source, we can ensure that this job
    # only runs when versioning is enabled, or when a tag is pushed.
    if: |
        needs.versioned_source.outputs.tag != '' &&
        (
          github.event.action != 'closed' ||
          github.event.pull_request.merged == true
        )

    <<: *rootWorkingDirectory

    permissions:
      contents: read

    outputs:
      body: ${{ steps.format_release_notes.outputs.body }}
      comment: ${{ steps.format_release_notes.outputs.comment }}
      note: ${{ steps.short_release_notes.outputs.result }}

    env:
      <<: *gitHubCliEnvironment

    steps:
      - <<: *getGitHubAppToken
        with:
          <<: *getGitHubAppTokenWith
          permissions: >-
            {
              "contents": "read",
              "metadata": "read",
              "pull_requests": "read"
            }

      # Get Renovate release notes from PR body, massage a little and draft a comment.
      - name: Format release notes
        id: format_release_notes
        continue-on-error: true
        env:
          # We need pull_requests: read to get the PR title and body but that permission
          # is not always granted by default to the actions token.
          GH_TOKEN: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
        run: |
          set -x

          pr_title="$(gh pr view ${{ github.event.pull_request.number }} --json title --jq .title)"
          raw_body="$(gh pr view ${{ github.event.pull_request.number }} --json body --jq .body)"

          if [[ -n "$pr_title" ]]; then

              # if Renovate did this, extract its release notes from pull request body and
              # massage until they resemble balena-io-modules/balena-deploy-request output
              renovate_bot="$(gh pr view ${{ github.event.pull_request.number }} --json author --jq \
                  'select((.author.is_bot==true) and (.author.login | contains("renovate"))).author.login')"

              title_pattern="## (R|r)elease (N|n)otes"
              if [[ -n "$renovate_bot" ]] && [[ "$raw_body" =~ '### Release Notes' ]]; then
                  # TODO: remove duplicate <details> sections on the pr_body
                  # https://github.com/renovatebot/renovate/issues/13037
                  pr_body="$(echo "${raw_body}" \
                    | sed -n '/^### Release Notes$/,/^---$/p' \
                    | sed "s|^### Release Notes$||g" \
                    | sed 's/^---$//g')"

                  notable_changes="$(echo "${pr_body}" |
                    # Only get lines starting with `-`, `> -` or `<summary>`
                    grep -E '^> -|^-|^<summary>' |
                    # Replace the contents of the summary tag with a list item
                    sed -E 's|^<summary>(.*)</summary>|-\1|g' |
                    # Remove duplicate lines
                    awk '!(NF && seen[$0]++)' |
                    # Remove first line
                    sed 1d)"

                  # Prepare the release notes
                  release_notes_changes="$(echo "${notable_changes}" | sed -E 's|^> -(.*)|  -\1|g')"
                  release_notes="$(printf '## %s\n\n### Notable changes\n\n%s\n\n%s' "${pr_title}" "${release_notes_changes}" "${pr_body}")"

                  # Prepare the comment body
                  notable_changes="$(echo "${notable_changes}" | sed -E 's|^|* |g')"
                  notable_changes="$(printf 'Notable changes\n* [only keep the important and rephrase, leaving this in place will avoid posting release notes]\n%s' "${notable_changes}")"

                  # https://zulip.com/help/format-your-message-using-markdown
                  # shortnames: https://pygments.org/docs/lexers/
                  release_notes_comment="$(printf '#release-notes %s\n\n%s%s' "${pr_title}" "${notable_changes}" "${pr_body}")"

              # Handle non-renovate cases
              elif [[ "$raw_body" =~ $title_pattern ]]; then
                # Find a section `## Release notes` and use that as the release notes body
                release_notes_body="$(echo "${raw_body}" \
                    | sed -n '/^## Release Notes/I,/^## /p' \
                    | sed '/^## /d' \
                    | sed -e :a -e '/./,$!d;/^\n*$/{$d;N;};/\n$/ba')" # Remove starting/trailing empty lines

                release_notes="$(printf '## %s\n%s' "${pr_title}" "${release_notes_body}")"
              fi

              if [[ -n "$release_notes" ]]; then
                  EOF="$(openssl rand -hex 16)"
                  echo "body<<$EOF" >> $GITHUB_OUTPUT
                  echo "${release_notes}" >> $GITHUB_OUTPUT
                  echo "$EOF" >> $GITHUB_OUTPUT
              fi

              if [[ -n "$release_notes_comment" ]]; then
                  EOF="$(openssl rand -hex 16)"
                  echo "comment<<$EOF" >> $GITHUB_OUTPUT
                  echo "${release_notes_comment}" >> $GITHUB_OUTPUT
                  echo "$EOF" >> $GITHUB_OUTPUT
              fi
          fi

      # https://octokit.github.io/rest.js/v21/#repos-list-tags
      # https://docs.github.com/en/rest/git/refs
      # https://octokit.github.io/rest.js/v21/#repos-compare-commits-with-basehead
      # https://docs.github.com/en/rest/commits/commits#compare-two-commits
      - name: Generate short release note
        id: short_release_notes
        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
        env:
          USER_DEFINED: ${{ steps.format_release_notes.outputs.body }}
          CURRENT_TAG: ${{ needs.versioned_source.outputs.tag }}
        with:
          result-encoding: json
          script: |
            // Get all tags sorted by version in descending order
            const { data: tags } = await github.rest.repos.listTags({
              ...context.repo,
              per_page: 10, // only fetch the last handful of tags
              page: 1
            });

            // Filter out the current tag
            const filteredTags = tags.filter(tag => tag.name !== process.env.CURRENT_TAG);

            console.log('tags:', JSON.stringify(filteredTags, null, 2));
            core.setOutput('tags', filteredTags);

            // Get the previous version tag
            const previousTag = filteredTags.find(tag => tag.name.match(/^v\d+\.\d+\.\d+/));

            if (!previousTag) {
              core.setFailed('No previous version tag found');
            }

            console.log('previousTag:', JSON.stringify(previousTag, null, 2));
            core.setOutput('previousTag', previousTag);

            const base = previousTag.name;
            const head = context.payload.pull_request?.head.sha || context.sha;

            // Get commit history between previous tag and current commit
            const { data: { commits } } = await github.rest.repos.compareCommitsWithBasehead({
              ...context.repo,
              basehead: `${base}...${head}`,
            });

            console.log('commits:', JSON.stringify(commits, null, 2));
            core.setOutput('commits', commits);

            // Format commits as git log --pretty=references
            // e.g. 8011111 (commit message, yyyy-mm-dd)
            const changelog = commits.map(commit => {
              const shortSha = commit.sha.substring(0, 8);
              return `${shortSha} (${commit.commit.message.split('\n')[0]}, ${commit.commit.author.date.split('T')[0]})`;
            }).join('\n');

            core.setOutput('changelog', changelog);

            // Generate release notes
            const userDefined = process.env.USER_DEFINED;
            const releaseNotes = userDefined
              ? `${userDefined}\n\n### List of commits\n\n${changelog}`
              : changelog;

            console.log(releaseNotes);

            // Write to file
            const fs = require('fs');
            fs.writeFileSync(process.env.RUNNER_TEMP + '/release-notes.txt', releaseNotes);

            return releaseNotes;

      # https://github.com/actions/upload-artifact
      - name: Upload release notes file
        uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4.6.0
        with:
          name: release-notes
          path: ${{ runner.temp }}/release-notes.txt
          retention-days: 1

  release_notes_comment:
    name: Prepare deploy message
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - versioned_source
      - release_notes
    if: |
      inputs.release_notes == true &&
      (
        github.event.action != 'closed' ||
        github.event.pull_request.merged == true
      )

    <<: *rootWorkingDirectory

    permissions: {}

    env:
      <<: *gitHubCliEnvironment

    steps:
      - <<: *getGitHubAppToken
        with:
          <<: *getGitHubAppTokenWith
          # contents: write is required to create or update pull request comments
          # pull_requests: write is required to create or update pull request comments
          permissions: >-
            {
              "contents": "write",
              "issues": "read",
              "metadata": "read",
              "pull_requests": "write"
            }

      - uses: peter-evans/find-comment@3eae4d37986fb5a8592848f6a574fdf654e61f9e # v3
        id: find_comment
        if: needs.release_notes.outputs.comment != ''
        with:
          issue-number: ${{ github.event.pull_request.number }}
          comment-author: "flowzone-app[bot]"
          body-includes: "#release-notes"
          token: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}

      - uses: peter-evans/find-comment@3eae4d37986fb5a8592848f6a574fdf654e61f9e # v3
        id: find_edited_comment
        if: needs.release_notes.outputs.comment != ''
        with:
          issue-number: ${{ github.event.pull_request.number }}
          comment-author: "flowzone-app[bot]"
          body-regex: '\* \[only keep the important and rephrase(, leaving this in place will avoid posting release notes)?\]'
          token: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}

      # to prevent clobbering edited comments, run only if no previous draft comment is
      # .. found, or if one exists, it is unedited
      - uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 # v4
        if: |
          needs.release_notes.outputs.comment != '' &&
          (
            (
              steps.find_comment.outputs.comment-id == '' &&
              steps.find_edited_comment.outputs.comment-id == ''
            ) ||
            (
              steps.find_comment.outputs.comment-id != '' &&
              steps.find_edited_comment.outputs.comment-id != ''
            )
          )
        with:
          comment-id: ${{ steps.find_comment.outputs.comment-id }}
          issue-number: ${{ github.event.pull_request.number }}
          body: |
            ${{ needs.release_notes.outputs.comment }}
          edit-mode: replace
          token: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
          reactions: eyes

      - <<: *getTimeStamp
        if: |
          github.event.pull_request.merged &&
          needs.versioned_source.outputs.commit_sha != ''

      # required by https://github.com/balena-io-modules/balena-deploy-request
      - <<: *createTagObject
        if: |
          github.event.pull_request.merged &&
          needs.versioned_source.outputs.commit_sha != ''
        env:
          GH_TOKEN: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
          TAG: production-${{ steps.timestamp.outputs.datetime }}
          MESSAGE: production-${{ steps.timestamp.outputs.datetime }}
          SHA: ${{ needs.versioned_source.outputs.commit_sha }}

      # create a new tag name reference(pointer) to the new tag object sha
      - <<: *createGitReference
        if: |
          github.event.pull_request.merged &&
          steps.create_tag.outputs.sha
        env:
          GH_TOKEN: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
          REF: "refs/tags/production-${{ steps.timestamp.outputs.datetime }}"
          SHA: ${{ steps.create_tag.outputs.sha }}

      # https://github.com/zulip/github-actions-zulip/blob/main/send-message/README.md
      - uses: zulip/github-actions-zulip/send-message@e4c8f27c732ba9bd98ac6be0583096dea82feea5 # v1
        id: zulip_send
        if: |
          github.event.pull_request.merged == true &&
          vars.ZULIP_STREAM != '' &&
          vars.ZULIP_TOPIC != '' &&
          vars.ZULIP_BOT_EMAIL != '' &&
          vars.ZULIP_API_URL != '' &&
          steps.find_edited_comment.outcome == 'success' &&
          steps.find_edited_comment.outputs.comment-id == ''
        continue-on-error: true
        with:
          api-key: ${{ secrets.ZULIP_API_KEY }}
          email: ${{ vars.ZULIP_BOT_EMAIL }}
          organization-url: ${{ vars.ZULIP_API_URL }}
          to: "${{ vars.ZULIP_STREAM }}"
          type: stream
          topic: "${{ vars.ZULIP_TOPIC }}"
          content: "${{ steps.find_comment.outputs.comment-body }}"

      # quick visual signal that we've sent a message
      - uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 # v4
        if: steps.zulip_send.outcome == 'success'
        continue-on-error: true
        with:
          comment-id: ${{ steps.find_comment.outputs.comment-id }}
          issue-number: ${{ github.event.pull_request.number }}
          token: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
          reactions: hooray

  actionlint:
    name: actionlint
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: 5
    # Do not run on PR close or merge events
    if: github.event.action != 'closed'
    # Run this early in the workflow, as soon as we've validated event types
    needs:
      - event_types

    permissions:
      contents: read # Used for checkout

    steps:
      # No need for the Flowzone Installation App token here as we are not cloning
      # submodules so the automatic actions token scoped to the repo is fine.

      # Disable submodules and deep cloning.
      # Do not persist credentials.
      # Use the automatic actions token with contents:read permissions.
      # Use the tip of the pull request branch for pull request (target) events.
      # Use the event sha for other events.
      # https://github.com/actions/checkout
      - *shallowCheckout

      # https://github.com/actions/toolkit/blob/master/docs/problem-matchers.md
      - name: Add problem matcher
        run: |
          curl -fsSL https://raw.githubusercontent.com/rhysd/actionlint/main/.github/actionlint-matcher.json > ${{ runner.temp }}/actionlint-matcher.json
          echo ::add-matcher::${{ runner.temp }}/actionlint-matcher.json

      # https://github.com/rhysd/actionlint/blob/main/docs/usage.md
      - name: Check workflow files
        # https://github.com/rhysd/actionlint/releases
        uses: docker://rhysd/actionlint:1.7.7
        with:
          # Ignore errors on unknown runner custom runner labels
          # Ignore shellcheck info and style messages for now
          args: -color -ignore="custom label for self-hosted runner" -ignore=":info:" -ignore=":style:"

  # https://github.com/synacktiv/octoscan
  # https://github.com/synacktiv/action-octoscan
  octoscan:
    name: octoscan
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: 5
    # Pull request target events will have the wrong ref and sha for SARIF uploads so skip it for now.
    # Do not run on PR close events.
    if: |
      github.event_name != 'pull_request_target' &&
      (
        github.event.action != 'closed' ||
        github.event.pull_request.merged == true
      )
    # Run this early in the workflow, as soon as we've validated event types
    needs:
      - event_types

    permissions:
      contents: read # required for checkout without submodules

    steps:
      - <<: *getGitHubAppToken
        with:
          <<: *getGitHubAppTokenWith
          # security_events: write is required to upload SARIF files
          permissions: >-
            {
              "contents": "read",
              "metadata": "read",
              "security_events": "write"
            }

      # Disable submodules and deep cloning.
      # Do not persist credentials.
      # Use the automatic actions token with contents:read permissions.
      # Use the tip of the pull request branch for pull request (target) events.
      # Use the event sha for other events.
      # https://github.com/actions/checkout
      - *shallowCheckout

      # https://github.com/synacktiv/octoscan
      # https://github.com/synacktiv/action-octoscan
      - id: octoscan
        name: Run octoscan
        uses: synacktiv/action-octoscan@6b1cf2343893dfb9e5f75652388bd2dc83f456b0 # v1.0.0
        with:
          # Filter on all workflow triggers as the default of "external" does not include workflow_call
          # external: https://github.com/synacktiv/octoscan/blob/3f7fd6e563be43432cef874c82a7714f67a8ef92/common/helpers.go#L69
          # allnopr: https://github.com/synacktiv/octoscan/blob/3f7fd6e563be43432cef874c82a7714f67a8ef92/common/helpers.go#L76
          filter_triggers: allnopr
          disable_rules: shellcheck,local-action,runner-label,dangerous-write

      # The codeql-action/upload-sarif action uses internal endpoints and does not work with app installation tokens
      # so here we use the github-script action to upload the SARIF file to GitHub via the REST API
      # https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github
      # https://github.com/github/codeql-action/blob/main/upload-sarif/action.yml
      # https://octokit.github.io/rest.js/v21/#code-scanning-upload-sarif
      # https://github.com/github/codeql-action/issues/2654
      - name: Upload SARIF file to GitHub
        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
        # For now let's just continue on error as this is not a critical path
        continue-on-error: true
        env:
          sarif_file: ${{ steps.octoscan.outputs.sarif_output }}
        with:
          github-token: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
          script: |
            const zlib = require("zlib");
            const fs = require("fs");

            const sarifPayload = fs.readFileSync(process.env.sarif_file, "utf8");
            const zippedSarif = zlib.gzipSync(sarifPayload).toString("base64");

            const { data } = await github.rest.codeScanning.uploadSarif({
              owner: context.repo.owner,
              repo: context.repo.repo,
              commit_sha: context.sha,
              ref: context.ref,
              sarif: zippedSarif,
            });

  # This job should be used as a universal and safe method of checking
  # which project files exist in order to skip other jobs entirely.
  # Eventually it should replace a bunch of the steps in the is_blah-type jobs.
  file_list:
    name: File list
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: 5
    # Run this early in the workflow, as soon as we've validated event types
    needs:
      - event_types

    permissions:
      contents: read # Used to list files in repo via GH API

    env:
      <<: *gitHubCliEnvironment

    # Return file listings for both the root of the project
    # and the provided working directory via inputs.
    # Only a few jobs properly support custom working directories,
    # but it's still used for self-tests in this repo.
    # When a custom working directory is not provided the outputs will contain the same content.
    outputs:
      root: ${{ steps.project-root.outputs.result }}
      workdir: ${{ steps.working-dir.outputs.result || steps.project-root.outputs.result }}

    steps:
      # Use GitHub REST API to safely get contents, limiting to one directory
      # https://octokit.github.io/rest.js/v21/#repos-get-content
      - name: List files in project root
        id: project-root
        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
        with:
          github-token: ${{ github.token }}
          result-encoding: json
          # Use the tip of the pull request branch for pull request (target) events.
          # Use the event sha for other events.
          script: |
            const { data } = await github.rest.repos.getContent({
              owner: context.repo.owner,
              repo: context.repo.repo,
              ref: context.payload.pull_request.head.sha || context.ref
            });

            return data
              .filter(item => item.type === 'file')
              .map(item => item.name);

      # Use GitHub REST API to safely get contents, limiting to one directory
      # https://github.com/actions/github-script
      # https://octokit.github.io/rest.js/v21/#repos-get-content
      - name: List files in working directory
        id: working-dir
        if: inputs.working_directory && inputs.working_directory != '.'
        env:
          WORKING_DIRECTORY: ${{ inputs.working_directory }}
        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
        with:
          github-token: ${{ github.token }}
          result-encoding: json
          # Use the tip of the pull request branch for pull request (target) events.
          # Use the event sha for other events.
          # Remove preceeding ./ from the working directory if it exists.
          script: |
            const { data } = await github.rest.repos.getContent({
              owner: context.repo.owner,
              repo: context.repo.repo,
              ref: context.payload.pull_request.head.sha || context.ref,
              path: process.env.WORKING_DIRECTORY.startsWith('./') ? process.env.WORKING_DIRECTORY.slice(2) : process.env.WORKING_DIRECTORY
            });

            return data
              .filter(item => item.type === 'file')
              .map(item => item.name);

  # Run pre-commit hooks if the config file exists in the project root.
  # This step will fail if the hooks find any differences after running.
  # Pre-commit hooks are useful projects for that don't use npm & husky.
  # See https://pre-commit.com for more information
  # See https://pre-commit.com/hooks.html for more hooks
  # See .pre-commit-config.yaml for example hooks config.
  pre_commit_hooks:
    name: Pre-commit hooks
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - file_list
    # Do not run on PR close or merge events.
    if: |
      contains(needs.file_list.outputs.root, '.pre-commit-config.yaml') &&
      github.event.action != 'closed'

    # No need for the Flowzone Installation App token here as we are not cloning
    # submodules so the automatic actions token scoped to the repo is fine.
    permissions:
      contents: read # Required to checkout source project, without submodules

    steps:
      # Disable submodules and deep cloning.
      # Do not persist credentials.
      # Use the automatic actions token with contents:read permissions.
      # Use the tip of the pull request branch for pull request (target) events.
      # Use the event sha for other events.
      # https://github.com/actions/checkout
      - *shallowCheckout

      # https://github.com/actions/setup-python
      - *setupPython

      # https://github.com/pre-commit/action
      - uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1

  # check if the repository has a package.json file and which engine versions are supported
  is_npm:
    name: Check NodeJS versions
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - file_list
    # Do not run on PR close events.
    if: |
      contains(needs.file_list.outputs.workdir, 'package.json') &&
      (
        github.event.action != 'closed' ||
        github.event.pull_request.merged == true
      )

    <<: *customWorkingDirectory

    # No need for the Flowzone Installation App token here as we are not cloning
    # submodules so the automatic actions token scoped to the repo is fine.
    permissions:
      contents: read # Required to checkout source project, without submodules

    outputs:
      npm: "true"
      has_npm_lockfile: ${{ contains(needs.file_list.outputs.workdir, 'package-lock.json') || contains(needs.file_list.outputs.workdir, 'npm-shrinkwrap.json') }}
      npm_private: ${{ steps.package_json.outputs.private }}
      npm_docs: ${{ steps.package_json.outputs.docs }}
      npm_sbom: ${{ inputs.generate_sbom }} # default true
      npm_access: ${{ steps.package_json.outputs.access }}
      node_versions: ${{ steps.node_versions.outputs.result }} # Default to 20.x if no versions were matched
      max_node_version: ${{ steps.node_versions.outputs.max }}

    env:
      NODE_VERSIONS: "[]"
      PACKAGE_JSON_PATH: "${{ inputs.working_directory }}/package.json"

    steps:
      # Disable submodules and deep cloning.
      # Do not persist credentials.
      # Use the automatic actions token with contents:read permissions.
      # Use the tip of the pull request branch for pull request (target) events.
      # Use the event sha for other events.
      # https://github.com/actions/checkout
      - *shallowCheckout

      - name: Process package.json
        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
        id: package_json
        with:
          result-encoding: json
          script: |
            const fs = require('fs');
            const packageJson = fs.readFileSync(process.env.PACKAGE_JSON_PATH, 'utf8');
            const json = JSON.parse(packageJson);
            console.log(JSON.stringify(json, null, 2));

            if (json.name == 'flowzone') {
              core.setFailed('It looks like we are not in the test directory!');
            }

            core.setOutput('private', json.private);
            if (json.scripts.doc != null) {
              core.setOutput('docs', 'true');
            }

            if (context.repo.private) {
              core.setOutput('access', 'restricted');
            } else {
              core.setOutput('access', 'public');
            }

            return json;

      # check which past and current and future Node.js LTS releases meet the engine requirements
      # if there are no engine requirements then the current LTS will be used

      - <<: *setupNode
        env:
          # renovate: datasource=node-version depName=node packageName=node-18.x
          NODE_VERSION: 18.20.6

      # https://www.npmjs.com/package/check-engine
      - &checkEngine
        name: Check engine
        id: check_engine_18
        run: |
          node_version="$(node --version)"
          if npx -q -y -- check-engine
          then
            echo "node_version=${node_version}" >> "${GITHUB_OUTPUT}"
          fi

      - <<: *setupNode
        env:
          # renovate: datasource=node-version depName=node packageName=node-20.x
          NODE_VERSION: 20.18.2

      - <<: *checkEngine
        id: check_engine_20

      - <<: *setupNode
        env:
          # renovate: datasource=node-version depName=node-22 packageName=node-22.x
          NODE_VERSION: 22.13.1

      - <<: *checkEngine
        id: check_engine_22

      # Default to 20.x if no versions were matched
      # https://github.com/actions/github-script
      - name: Set Node.js versions
        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
        id: node_versions
        env:
          # Tested that this will always return a JSON array.
          # If the engines in package.json are not satisified by any of the above
          # engine checks, the NODE_VERSIONS value will be [] and the script should
          # instead return ["20.x"] so we always test something.
          NODE_VERSIONS: ${{ toJSON(steps.*.outputs.node_version) }}
        with:
          result-encoding: json
          script: |
            const { compareVersions } = require('util');
            const versions = JSON.parse(process.env.NODE_VERSIONS);

            if (versions.length < 1) {
              versions.push('20.x')
            }

            const sorted = [...versions].sort(compareVersions);

            core.setOutput('min', sorted[0]);
            core.setOutput('max', sorted.at(-1));
            return sorted;

  # pre-process any docker-compose and docker-bake files
  is_docker:
    name: Process docker files
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - file_list
    # Do not run on PR close events.
    # Match any of the following file globs:
    #  docker-bake{.override,}.{json,hcl}
    #  docker-compose{.test,}.{yml,yaml}
    #  Dockerfile
    if: |
      (
        inputs.docker_images ||
        contains(needs.file_list.outputs.workdir, 'docker-compose.test.yaml') ||
        contains(needs.file_list.outputs.workdir, 'docker-compose.test.yml')
      ) && (
        github.event.action != 'closed' ||
        github.event.pull_request.merged == true
      )

    <<: *customWorkingDirectory

    # No need for the Flowzone Installation App token here as we are not cloning
    # submodules so the automatic actions token scoped to the repo is fine.
    permissions:
      contents: read # Required to checkout source project, without submodules

    outputs:
      docker_images: ${{ steps.docker_publish.outputs.images }}
      docker_images_crlf: ${{ steps.docker_publish.outputs.images_crlf }}
      docker_compose_tests: ${{ contains(needs.file_list.outputs.workdir, 'docker-compose.test.yaml') || contains(needs.file_list.outputs.workdir, 'docker-compose.test.yml') }}
      docker_bake_json: ${{ steps.docker_bake.outputs.result }}
      docker_test_matrix: ${{ steps.docker_test.outputs.result }}
      docker_publish_matrix: ${{ steps.docker_publish.outputs.result }}

    steps:
      # Disable submodules and deep cloning.
      # Do not persist credentials.
      # Use the automatic actions token with contents:read permissions.
      # Use the tip of the pull request branch for pull request (target) events.
      # Use the event sha for other events.
      # https://github.com/actions/checkout
      - *shallowCheckout

      - <<: *setupBuildx
        with:
          # pin to a known working version because v0.10.x will
          # create a group called "default" that does not contain multiple targets
          version: v0.9.1

      # generate a custom bake json string from the provided bake targets and any discovered bake files
      # https://docs.docker.com/build/customize/bake/file-definition/#json-definition
      # in this custom bake json we also set some default cache values, and inherit the docker-metadata-action
      - name: Pre-process Docker bake files
        id: docker_bake
        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
        env:
          TEMP_BAKE_FILE: ${{ runner.temp }}/docker-bake.json
          BAKE_TARGETS: ${{ inputs.bake_targets }}
          ALL_FILES: ${{ needs.file_list.outputs.workdir }}
          WORKDIR: ${{ inputs.working_directory }}
        with:
          result-encoding: json
          script: |
            const fs = require('fs');
            const path = require('path');
            const { execSync } = require('child_process');

            const tempBakeFile = process.env.TEMP_BAKE_FILE;
            const bakeTargets = process.env.BAKE_TARGETS.trim().replace(/[\s,]+/g,',').split(',');
            const bakeFiles = JSON.parse(process.env.ALL_FILES)
              .filter(f => f.match(/docker-bake(\.override)?\.(json|hcl)/))
              .map(f => path.join(process.env.WORKDIR.trim(), f));

            const bakeConfig = {
              target: Object.fromEntries(bakeTargets.map(t => [t, {}]))
            };
            fs.writeFileSync(tempBakeFile, JSON.stringify(bakeConfig));
            bakeFiles.push(tempBakeFile);

            console.log(JSON.stringify(bakeTargets, null, 2));
            console.log(JSON.stringify(bakeFiles, null, 2));
            console.log(JSON.stringify(bakeConfig, null, 2));

            core.setOutput('targets', bakeTargets);
            core.setOutput('files', bakeFiles);

            const fileArgs = bakeFiles.map(f => `-f ${f}`).join(' ');
            const bakeCmd = `docker buildx bake --print ${bakeTargets.join(' ')} ${fileArgs}`;

            console.log(bakeCmd);

            const bakeOutput = execSync(bakeCmd).toString().trim();
            const bakeJson = JSON.parse(bakeOutput);

            console.log(JSON.stringify(bakeJson, null, 2));

            // Transform the data
            if (bakeJson.target) {
              Object.values(bakeJson.target).forEach(target => {
                target.inherits = target.inherits || [];
                target.inherits.push('docker-metadata-action');
                target.platforms = target.platforms || ['linux/amd64'];
              });
            }

            if (bakeJson.group) {
              delete bakeJson.group.default;
              if (Object.keys(bakeJson.group).length === 0) {
                delete bakeJson.group;
              }
            }

            console.log(JSON.stringify(bakeJson, null, 2));

            return bakeJson;

      # generate a test matrix with this structure
      # {
      #   "include": [
      #     {
      #       "target": "default",
      #       "platform": "linux/amd64",
      #       "runs_on": [
      #         "self-hosted",
      #         "X64"
      #       ],
      #       "platform_slug": "amd64",
      #       "target_slug": "default"
      #     },
      #     {
      #       "target": "multiarch",
      #       "platform": "linux/amd64",
      #       "runs_on": [
      #         "self-hosted",
      #         "X64"
      #       ],
      #       "platform_slug": "amd64",
      #       "target_slug": "multiarch",
      #       "tag_suffix": "-multiarch"
      #     },
      #     {
      #       "target": "multiarch",
      #       "platform": "linux/arm64",
      #       "runs_on": [
      #         "self-hosted",
      #         "ARM64"
      #       ],
      #       "platform_slug": "arm64v8",
      #       "target_slug": "multiarch",
      #       "tag_suffix": "-multiarch"
      #     },
      #     {
      #       "target": "multiarch",
      #       "platform": "linux/arm/v7",
      #       "runs_on": [
      #         "self-hosted",
      #         "ARM64"
      #       ],
      #       "platform_slug": "arm32v7",
      #       "target_slug": "multiarch",
      #       "tag_suffix": "-multiarch"
      #     },
      #     {
      #       "target": "multiarch",
      #       "platform": "linux/arm/v6",
      #       "runs_on": [
      #         "self-hosted",
      #         "ARM64"
      #       ],
      #       "platform_slug": "arm32v6",
      #       "target_slug": "multiarch",
      #       "tag_suffix": "-multiarch"
      #     }
      #   ]
      # }

      - name: Build docker test matrix
        id: docker_test
        if: steps.docker_bake.outputs.result != ''
        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
        env:
          <<: *dockerPlatformSlugMap
          BAKE_JSON: "${{ steps.docker_bake.outputs.result }}"
          RUNS_ON: "${{ inputs.runs_on }}"
          DOCKER_RUNS_ON: "${{ inputs.docker_runs_on }}"
        with:
          result-encoding: json
          script: |
            const bakeJson = JSON.parse(process.env.BAKE_JSON);
            const platformSlugMap = JSON.parse(process.env.PLATFORM_SLUG_MAP);
            const dockerRunsOn = JSON.parse(process.env.DOCKER_RUNS_ON);
            const defaultRunsOn = JSON.parse(process.env.RUNS_ON);

            // Create initial matrix from targets and platforms
            const matrix = {
              include: Object.entries(bakeJson.target).flatMap(([target, value]) =>
                value.platforms.map(platform => ({
                  target,
                  platform,
                  // Set runs_on based on platform or default
                  runs_on: dockerRunsOn[platform] || defaultRunsOn,
                  // Set platform_slug from map or error
                  platform_slug: platformSlugMap[platform] || (() => {
                    throw new Error(`Unsupported platform: ${platform}`);
                  })(),
                  // Set target_slug by replacing non-alphanumeric chars
                  target_slug: target.replace(/[^a-zA-Z0-9]/g, '-')
                }))
              )
            };

            // Add tag prefix/suffix based on docker_invert_tags
            const invertTags = ${{ inputs.docker_invert_tags }};
            matrix.include = matrix.include.map(item => {
              if (item.target !== 'default') {
                if (invertTags) {
                  item.tag_prefix = item.target + '-';
                } else {
                  item.tag_suffix = '-' + item.target;
                }
              }
              return item;
            });

            console.log(JSON.stringify(matrix, null, 2));

            return matrix;

      # generate a publish matrix with this structure
      # {
      #   "include": [
      #     {
      #       "image": "ghcr.io/product-os/flowzone",
      #       "target": "default",
      #       "target_slug": "default",
      #       "platform_slugs": "amd64"
      #     },
      #     {
      #       "image": "ghcr.io/product-os/flowzone",
      #       "target": "multiarch",
      #       "target_slug": "multiarch",
      #       "platform_slugs": "amd64 arm64v8 arm32v7 arm32v6"
      #     }
      #   ]
      # }

      - name: Build docker publish matrix
        id: docker_publish
        if: |
          inputs.docker_images != '' &&
          join(fromJSON(steps.docker_bake.outputs.targets)) != '' &&
          steps.docker_bake.outputs.result != ''
        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
        env:
          <<: *dockerPlatformSlugMap
          BAKE_JSON: ${{ steps.docker_bake.outputs.result }}
          BAKE_TARGETS: ${{ steps.docker_bake.outputs.targets }}
          IMAGES: ${{ inputs.docker_images }}
        with:
          result-encoding: json
          script: |
            const bakeJson = JSON.parse(process.env.BAKE_JSON);
            const platformSlugMap = JSON.parse(process.env.PLATFORM_SLUG_MAP);
            const images = process.env.IMAGES.trim().replace(/[\s,]+/g,',').split(',');
            const imagesCrlf = images.join('\n');
            const targets = JSON.parse(process.env.BAKE_TARGETS);

            console.log(JSON.stringify(images, null, 2));
            core.setOutput('images', images);

            console.log(imagesCrlf);
            core.setOutput('images_crlf', imagesCrlf);

            // Generate combinations of images and targets
            const combinations = images.flatMap(image =>
              targets.map(target => ({
                image,
                target,
                target_slug: target.replace(/[^a-zA-Z0-9]/g, '-')
              }))
            );

            console.log(JSON.stringify(combinations, null, 2));

            // Add platform_slugs to each combination
            const matrix = {
              include: combinations.map(item => {
                const targetPlatforms = bakeJson.target?.[item.target]?.platforms;
                if (!targetPlatforms) {
                  throw new Error(`Unsupported target: ${item.target}`);
                }

                const platformSlugs = targetPlatforms
                  .map(platform => {
                    const slug = platformSlugMap[platform];
                    if (!slug) {
                      throw new Error(`Unsupported platform: ${platform}`);
                    }
                    return slug;
                  })
                  .join(' ');

                return {
                  ...item,
                  platform_slugs: platformSlugs
                };
              })
            };

            console.log(JSON.stringify(matrix, null, 2));

            return matrix;

  is_python:
    name: Is python
    env:
      SUPPORTED_VERSIONS: |
        3.8
        3.9
        3.10
        3.11
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - versioned_source

    <<: *customWorkingDirectory

    permissions: {}

    outputs:
      python_poetry: ${{ steps.python_poetry.outputs.enabled }}
      python_versions: ${{ steps.python_versions.outputs.json }}
      pypi_publish: ${{ steps.python_poetry.outputs.pypi_publish }}
      python_sbom: ${{ inputs.generate_sbom }}

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha

      - name: Identify Poetry project
        id: python_poetry
        run: |
          if test -f "pyproject.toml"
          then
            echo "found pyproject.toml"
            if grep 'build-backend.*poetry' pyproject.toml
            then
              echo "Poetry used"
              echo "enabled=true" >> "${GITHUB_OUTPUT}"
              echo "PYTHON_VERSIONS=[]" >> "${GITHUB_ENV}"
            else
              echo "Poetry not used"
              echo "enabled=false" >> "${GITHUB_OUTPUT}"
            fi

            has_package="$(awk -F "=" '/^packages/ {print $2}' pyproject.toml)"
            if [ -n "${has_package}" ] && [ "${{ github.event.repository.visibility }}" = "public" ]
            then
              echo "pypi_publish=true" >> "${GITHUB_OUTPUT}"
            else
              echo "pypi_publish=false" >> "${GITHUB_OUTPUT}"
            fi

          else
            echo "enabled=false" >> "${GITHUB_OUTPUT}"
            echo "pypi_publish=false" >> "${GITHUB_OUTPUT}"
          fi

      - <<: *setupPython
        if: steps.python_poetry.outputs.enabled == 'true'
        with:
          python-version: ${{ env.SUPPORTED_VERSIONS }}

      - *setupPoetry

      - name: Validate project Python requirements
        if: steps.python_poetry.outputs.enabled == 'true'
        run: |
          versions=()
          while IFS= read -r version; do
            echo "Setting up Python $version"
            error_check=`(poetry env use $version 2>&1 || true)`
            if ! grep -q "Please choose a compatible version" <<< $error_check; then
              versions+=("\"$version\"")
            else
              echo "Python $version does not meet project requirements."
            fi
          done <<< "$(echo -n "${SUPPORTED_VERSIONS}")"
          echo "PYTHON_VERSIONS=[$(IFS=,; echo "${versions[*]}")]" >> "${GITHUB_ENV}"

      # default to the latest version on the runner
      # if none were matched by the checks above
      - name: Output compatible Python versions
        if: steps.python_poetry.outputs.enabled == 'true'
        id: python_versions
        run: |
          echo "json=[\"3.x\"]" >> "${GITHUB_OUTPUT}"
          if [ "${PYTHON_VERSIONS}" != "[]" ]
          then
            echo "json=${PYTHON_VERSIONS}" >> "${GITHUB_OUTPUT}"
          fi

  # check for Cargo.toml in source
  is_cargo:
    name: Is rust
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - versioned_source
    if: inputs.cargo_targets != ''

    <<: *customWorkingDirectory

    permissions: {}

    outputs:
      cargo_targets: ${{ steps.cargo_targets.outputs.result }}
      cargo: ${{ steps.cargo_yml.outputs.enabled }}
      cargo_sbom: ${{ inputs.generate_sbom }}
      cargo_publish: ${{ steps.cargo_publish.outputs.value }}

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha

      - id: cargo_targets
        <<: *jsonArrayBuilder
        env:
          INPUT: ${{ inputs.cargo_targets }}

      - name: Check Cargo.toml
        id: cargo_yml
        run: |
          if test -f "Cargo.toml"
          then
            echo "found Cargo.toml"
            echo "enabled=true" >> "${GITHUB_OUTPUT}"
          else
            echo "enabled=false" >> "${GITHUB_OUTPUT}"
          fi

      - name: Check private
        if: steps.cargo_yml.outputs.enabled == 'true'
        uses: dangdennis/toml-action@ef528766b9af3dc473cb3f768a1646160ffb2645 # v1.3.0
        id: cargo_publish
        with:
          file: "Cargo.toml"
          field: "package.publish"
          working-directory: ${{ inputs.working_directory }}

  # check for balena.yml in source
  is_balena:
    name: Is balena
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - versioned_source
    if: inputs.balena_slugs != ''

    <<: *customWorkingDirectory

    permissions: {}

    outputs:
      balena_slugs: ${{ steps.balena_slugs.outputs.result }}

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha

      - id: balena_slugs
        <<: *jsonArrayBuilder
        env:
          INPUT: ${{ inputs.balena_slugs }}

  # check for custom actions in source
  is_custom:
    name: Is custom
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - versioned_source

    <<: *rootWorkingDirectory

    permissions: {}

    outputs:
      custom_test: ${{ steps.custom.outputs.test }}
      custom_publish: ${{ steps.custom.outputs.publish }}
      custom_finalize: ${{ steps.custom.outputs.finalize }}
      custom_clean: ${{ steps.custom.outputs.clean }}
      custom_always: ${{ steps.custom.outputs.always }}

      custom_test_matrix: ${{ steps.custom_test_matrix.outputs.json || inputs.custom_test_matrix }}
      custom_publish_matrix: ${{ steps.custom_publish_matrix.outputs.json || inputs.custom_publish_matrix }}
      custom_finalize_matrix: ${{ steps.custom_finalize_matrix.outputs.json || inputs.custom_finalize_matrix }}

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha
      - *resetGitHubDirectory

      # FIXME: remove this handling of deprecated comma-separated values
      - id: custom_test_values
        if: contains(inputs.custom_test_matrix, '{') != true
        <<: *jsonArrayBuilder
        env:
          INPUT: ${{ inputs.custom_test_matrix }}

      # FIXME: remove this handling of deprecated comma-separated values
      - &customValuesInput
        name: Create matrix from custom values
        id: custom_test_matrix
        if: steps.custom_test_values.outputs.result != ''
        env:
          MATRIX: >
            {
              "value": ${{ steps.custom_test_values.outputs.result }},
              "os": ${{ inputs.custom_runs_on || format('[{0}]', inputs.runs_on) }}
            }
        run: |
          json=$(jq -e -c . <<<"${MATRIX}") || exit $?
          echo "json=${json}" >> "${GITHUB_OUTPUT}"

      # FIXME: remove this handling of deprecated comma-separated values
      - id: custom_publish_values
        if: contains(inputs.custom_publish_matrix, '{') != true
        <<: *jsonArrayBuilder
        env:
          INPUT: ${{ inputs.custom_publish_matrix }}

      # FIXME: remove this handling of deprecated comma-separated values
      - <<: *customValuesInput
        id: custom_publish_matrix
        if: steps.custom_publish_values.outputs.result != ''
        env:
          MATRIX: >
            {
              "value": ${{ steps.custom_publish_values.outputs.result }},
              "os": ${{ inputs.custom_runs_on || format('[{0}]', inputs.runs_on) }}
            }

      # FIXME: remove this handling of deprecated comma-separated values
      - id: custom_finalize_values
        if: contains(inputs.custom_finalize_matrix, '{') != true
        <<: *jsonArrayBuilder
        env:
          INPUT: ${{ inputs.custom_finalize_matrix }}

      # FIXME: remove this handling of deprecated comma-separated values
      - <<: *customValuesInput
        id: custom_finalize_matrix
        if: steps.custom_finalize_values.outputs.result != ''
        env:
          MATRIX: >
            {
              "value": ${{ steps.custom_finalize_values.outputs.result }},
              "os": ${{ inputs.custom_runs_on || format('[{0}]', inputs.runs_on) }}
            }

      - name: Check for custom actions
        id: custom
        run: |
          if [ -d .github/actions/test ]
          then
            echo "test=true" >> "${GITHUB_OUTPUT}"
          fi
          if [ -d .github/actions/publish ]
          then
            echo "publish=true" >> "${GITHUB_OUTPUT}"
          fi
          if [ -d .github/actions/finalize ]
          then
            echo "finalize=true" >> "${GITHUB_OUTPUT}"
          fi
          if [ -d .github/actions/clean ]
          then
            echo "clean=true" >> "${GITHUB_OUTPUT}"
          fi
          if [ -d .github/actions/always ]
          then
            echo "always=true" >> "${GITHUB_OUTPUT}"
          fi

  is_cloudformation:
    name: Is CloudFormation
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - versioned_source
    if: inputs.cloudformation_templates != ''

    <<: *customWorkingDirectory

    permissions: {}

    outputs:
      cloudformation: ${{ steps.validate_json.outputs.enabled }}
      stacks: ${{ steps.cloudformation_stacks.outputs.matrix }}
      includes: ${{ steps.cloudformation_stacks.outputs.includes }}

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha

      - name: Validate CloudFormation input
        id: validate_json
        run: |
          if echo '${{ inputs.cloudformation_templates }}' | yq e -P - | yq e -o=json - | jq -r .stacks
          then
            if [[ '${{ github.event.pull_request.head.repo.full_name }}' != '${{ github.repository }}' ]]; then
              echo '::warning:: CloudFormation stacks are skipped for external contributions.'
              echo "enabled=false" >> "${GITHUB_OUTPUT}"
              exit 0
            fi
            echo "enabled=true" >> "${GITHUB_OUTPUT}"
          else
            echo '::warning::invalid JSON or no CloudFormation stacks?'
            echo "enabled=false" >> "${GITHUB_OUTPUT}"
          fi

      - name: Generate stacks matrix
        id: cloudformation_stacks
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha || github.event.head_commit.id }}
        run: |
          stacks="$(echo '${{ inputs.cloudformation_templates }}' \
            | yq e -P - | yq e -o=json - \
            | jq -r '.stacks[]')"

          stack_names="$(echo '${{ inputs.cloudformation_templates }}' \
            | yq e -P - | yq e -o=json - \
            | jq -r '.stacks[].name' | jq -Rcn '[inputs'])"

          includes="$(echo '${{ inputs.cloudformation_templates }}' \
            | yq e -P - | yq e -o=json - \
            | jq -r '.stacks[] | with_entries(if .key == "name" then .key = "stack" else . end)' \
            | jq -rsc)"

          template_files="$(echo '${{ inputs.cloudformation_templates }}' \
            | yq e -P - | yq e -o=json - \
            | jq -r '.stacks[].template')"

          # include templates in the matrix only if modified
          for template in ${template_files}; do
              modified_files="$(git diff --submodule=diff "${BASE_SHA}" "${HEAD_SHA}" | sed -n 's#^--- a/\(.*\)$#\1#p')"

              if ! echo "${modified_files}" | grep -Eq "^${template}$|^.github/workflows/"; then
                  unmodified_stacks="$(echo "${stacks}" \
                    | jq -r --arg tmpl "${template}" 'select(.template==$tmpl).name')"

                  for stack in ${unmodified_stacks}; do
                      stack_names="$(echo "${stack_names}" \
                        | jq -rc --arg stack "${stack}" 'map(select(.!=$stack))')"
                  done
              fi
          done

          echo "matrix=${stack_names}" >> "${GITHUB_OUTPUT}"
          echo "includes=${includes}" >> "${GITHUB_OUTPUT}"

  ###################################################
  ## npm
  ###################################################

  npm_test:
    name: Test npm
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - is_npm
      - versioned_source
    if: |
      github.event.pull_request.state == 'open' &&
      needs.is_npm.outputs.npm == 'true'

    <<: *customWorkingDirectory

    permissions: {}

    strategy:
      fail-fast: false
      max-parallel: ${{ fromJSON(inputs.max_parallel) }}
      matrix:
        node_version: ${{ fromJSON(needs.is_npm.outputs.node_versions) }}

    outputs:
      package: ${{ steps.meta.outputs.package }}
      version: ${{ steps.meta.outputs.version }}
      branch_tag: ${{ steps.meta.outputs.branch_tag }}
      sha_tag: ${{ steps.meta.outputs.sha_tag }}
      version_tag: ${{ steps.meta.outputs.version_tag }}

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha
      - *createLocalRefs

      - <<: *setupNode
        if: needs.is_npm.outputs.has_npm_lockfile == 'true'
        with:
          node-version: "${{ matrix.node_version }}"
          registry-url: "${{ env.NPM_REGISTRY }}"
          cache: "npm"

      - <<: *setupNode
        if: needs.is_npm.outputs.has_npm_lockfile != 'true'
        with:
          node-version: "${{ matrix.node_version }}"
          registry-url: "${{ env.NPM_REGISTRY }}"

      - name: Generate metadata
        id: meta
        run: |
          package="$(jq -r '.name' package.json)"
          version="$(jq -r '.version' package.json)"
          branch_tag="$(echo "build-${GITHUB_HEAD_REF}" | sed 's/[^[:alnum:]]/-/g')"
          sha_tag="${branch_tag}-${{ github.event.pull_request.head.sha }}"
          version_tag="${version}-${branch_tag}-${{ github.event.pull_request.head.sha }}"

          echo "package=${package}" >> "${GITHUB_OUTPUT}"
          echo "version=${version}" >> "${GITHUB_OUTPUT}"
          echo "branch_tag=${branch_tag}" >> "${GITHUB_OUTPUT}"
          echo "sha_tag=${sha_tag}" >> "${GITHUB_OUTPUT}"
          echo "version_tag=${version_tag}" >> "${GITHUB_OUTPUT}"

      - name: Install native dependencies (if necessary)
        run: |
          npm run flowzone-preinstall --if-present

      - name: Install dependencies
        # private npm dependencies will fail to install unless NODE_AUTH_TOKEN is set in the environment
        # but to avoid leaking secrets we would also have to disable all scripts, like preinstall and postinstall
        # so only public npm dependencies supported for now
        # env:
        #   # make sure to 'npm config set ignore-scripts true' to avoid leaking secrets
        #   NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: |
          runner_os="$(echo "${RUNNER_OS}" | tr '[:upper:]' '[:lower:]')"
          os_count="$(jq '.os | length' package.json)"
          index="$(jq --arg os "${runner_os}" '.os | index($os) | select( . != null )' package.json)"

          if [[ -n "$index" ]] || [[ "$os_count" -lt 1 ]]; then
              if [ ${{ needs.is_npm.outputs.has_npm_lockfile }} == 'true' ]; then
                npm ci
              else
                npm i
              fi
          else
              echo "${runner_os} is not supported in package.json"
          fi

      - name: Run build
        run: npm run build --if-present

      - name: Run tests
        if: inputs.pseudo_terminal != true
        run: npm test

      - name: Run tests (pseudo-tty)
        if: inputs.pseudo_terminal == true
        shell: script -q -e -c "bash --noprofile --norc -eo pipefail -x {0}" /tmp/test-session
        run: npm test

      - name: Run pack
        if: needs.is_npm.outputs.npm_private != 'true' && needs.is_npm.outputs.max_node_version == matrix.node_version
        run: |
          mkdir ${{ runner.temp }}/npm-pack && npm pack --pack-destination=${{ runner.temp }}/npm-pack

          # FIXME: workaround when `npm pack` for npm 6.x dumps tarball into the current directory because it has no `--pack-destination` flag
          [[ "$(npm --version)" =~ ^6\..* ]] && find . -maxdepth 1 -name '*.tgz' -exec mv {} ${{ runner.temp }}/npm-pack \; || true

      # https://github.com/actions/upload-artifact
      - name: Upload artifact
        if: needs.is_npm.outputs.npm_private != 'true' && needs.is_npm.outputs.max_node_version == matrix.node_version
        uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4.6.0
        with:
          name: npm-${{ github.event.pull_request.head.sha }}
          path: ${{ runner.temp }}/npm-pack/*.tgz
          retention-days: 90

      - name: Generate docs (if present)
        if: needs.is_npm.outputs.npm_docs == 'true'
        shell: bash
        run: npm run doc

      - name: Compress docs
        if: needs.is_npm.outputs.npm_docs == 'true' && needs.is_npm.outputs.max_node_version == matrix.node_version
        run: tar --auto-compress -cvf ${{ runner.temp }}/docs.tar.zst ./docs

      # https://github.com/actions/upload-artifact
      - name: Upload artifact
        if: needs.is_npm.outputs.npm_docs == 'true' && needs.is_npm.outputs.max_node_version == matrix.node_version
        uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4.6.0
        with:
          name: docs-${{ github.event.pull_request.head.sha }}
          path: ${{ runner.temp }}/docs.tar.zst
          retention-days: 90

  npm_sbom:
    name: Generate SBOM for NPM
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    continue-on-error: true
    needs:
      - is_npm
      - npm_test
      - versioned_source
    if: ${{ needs.is_npm.outputs.npm == 'true' && needs.is_npm.outputs.npm_sbom == 'true' }}

    <<: *customWorkingDirectory

    permissions: {}

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha
      - *createLocalRefs

      - <<: *setupNode
        with:
          node-version: ${{ fromJSON(needs.is_npm.outputs.node_versions)[0] }}

      - run: npm install

      - name: Generate SBOM
        run: |
          npx @cyclonedx/cyclonedx-npm --output-file=${{ runner.temp }}/npm-sbom.xml

      - <<: *publishSBOMArtifacts
        with:
          name: gh-release-sbom-npm
          path: ${{ runner.temp }}/npm-sbom.xml
          retention-days: 90

      - <<: *publishSBOMToDependencyTrack
        env:
          SERVER_HOSTNAME: ${{ vars.DTRACK_API }}
          API_KEY: ${{ secrets.DTRACK_TOKEN }}
          PROJECT_NAME: ${{ github.event.repository.name }}
          BOM_FILE: ${{ runner.temp }}/npm-sbom.xml
          PROJECT_VERSION: ${{ needs.npm_test.outputs.version_tag }}

  npm_publish:
    name: Publish npm
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - is_npm
      - npm_test
      - custom_test
      - docker_test
      - cargo_test
      - python_test
    # allow some dependencies to be skipped
    if: |
      !failure() && !cancelled() &&
      needs.npm_test.result == 'success' &&
      needs.is_npm.outputs.npm_private != 'true'

    <<: *rootWorkingDirectory

    permissions: {}

    steps:
      # https://github.com/actions/download-artifact
      - name: Download npm artifact
        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
        with:
          path: ${{ runner.temp }}
          name: npm-${{ github.event.pull_request.head.sha }}

      - <<: *setupNode
        with:
          # use npm v9 or later as the access flag behaviour has changed
          # https://docs.npmjs.com/cli/v9/commands/npm-publish?access
          node-version: "${{ needs.is_npm.outputs.max_node_version }}"
          registry-url: "${{ env.NPM_REGISTRY }}"

      # unpack the tarball provided by the tests so we can apply the draft version to package.json
      # before publishing
      - name: Publish draft release
        env:
          # make sure to 'npm config set ignore-scripts true' to avoid leaking secrets
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: |
          npm config set ignore-scripts true

          pack="$(ls ${{ runner.temp }}/*.tgz | sort -t- -n -k3 | tail -n1)"
          tar xvf "${pack}"
          (cd package
            npm --loglevel=verbose --logs-max=0 --no-git-tag-version version ${{ needs.npm_test.outputs.version_tag }}-${{ github.run_attempt }} --allow-same-version
          )
          tar czvf "${pack}" package

          # shellcheck disable=SC2170
          if [ ${{ github.run_attempt }} -gt 1 ]; then
            npm --loglevel=verbose --logs-max=0 unpublish ${{ needs.npm_test.outputs.package }}@${{ needs.npm_test.outputs.version_tag }}-$((${{ github.run_attempt }} - 1)) || true
          fi
          npm --loglevel=verbose --logs-max=0 publish --tag=${{ needs.npm_test.outputs.branch_tag }} "${pack}" --access="${{ needs.is_npm.outputs.npm_access }}"

  npm_finalize:
    name: Finalize npm
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - is_npm
    if: |
      (github.event.pull_request.merged == true || github.event_name == 'push') &&
      needs.is_npm.outputs.npm == 'true' &&
      needs.is_npm.outputs.npm_private != 'true'

    <<: *rootWorkingDirectory

    permissions: {}

    steps:
      - *getGitHubAppToken

      # https://github.com/dawidd6/action-download-artifact
      # TODO: what if this is a tag event and PR artifacts do not exist?
      - name: Download npm artifact from last run
        uses: dawidd6/action-download-artifact@09f2f74827fd3a8607589e5ad7f9398816f540fe # v3.1.4
        with:
          github_token: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
          commit: ${{ github.event.pull_request.head.sha || github.event.head_commit.id }}
          path: ${{ runner.temp }}
          workflow_conclusion: success
          # Optionally match version suffix in the format -v22.13.1 or -22.x as we used to
          # include a version suffix on draft artifacts.
          name: npm-${{ github.event.pull_request.head.sha }}(-v[0-9]+\.[0-9]+\.[0-9]+|-[0-9][0-9]\.x)?
          name_is_regexp: true

      - <<: *setupNode
        with:
          # use npm v9 or later as the access flag behaviour has changed
          # https://docs.npmjs.com/cli/v9/commands/npm-publish?access
          node-version: "${{ needs.is_npm.outputs.max_node_version }}"
          registry-url: "${{ env.NPM_REGISTRY }}"

      - name: Publish final release
        env:
          # make sure to 'npm config set ignore-scripts true' to avoid leaking secrets
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
        run: |
          npm config set ignore-scripts true
          pack="$(ls ${{ runner.temp }}/*/*.tgz | sort -t- -n -k3 | tail -n1)"
          npm --loglevel=verbose --logs-max=0 publish --tag "latest" "${pack}" --access="${{ needs.is_npm.outputs.npm_access }}"

  npm_docs_finalize:
    name: Finalize npm docs
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - is_npm
    if: |
      (github.event.pull_request.merged == true || github.event_name == 'push') &&
      needs.is_npm.outputs.npm_docs == 'true'

    <<: *rootWorkingDirectory

    permissions: {}

    steps:
      - <<: *getGitHubAppToken
        with:
          <<: *getGitHubAppTokenWith
          # need permissions to push to docs branch and publish to github pages
          permissions: >-
            {
              "pages": "write",
              "contents": "write",
              "metadata": "read"
            }

      # https://github.com/dawidd6/action-download-artifact
      # TODO: what if this is a tag event and PR artifacts do not exist?
      - name: Download npm docs artifact from last run
        uses: dawidd6/action-download-artifact@09f2f74827fd3a8607589e5ad7f9398816f540fe # v3.1.4
        with:
          github_token: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
          commit: ${{ github.event.pull_request.head.sha || github.event.head_commit.id }}
          path: ${{ runner.temp }}
          workflow_conclusion: success
          # Optionally match version suffix in the format -v22.13.1 or -22.x as we used to
          # include a version suffix on draft artifacts.
          name: docs-${{ github.event.pull_request.head.sha }}(-v[0-9]+\.[0-9]+\.[0-9]+|-[0-9][0-9]\.x)?
          name_is_regexp: true

      - name: Extract docs artifact
        run: |
          docs="$(ls ${{ runner.temp }}/*/*.tar.zst | sort -t- -n -k3 | tail -n1)"
          tar -xvf "${docs}"

      - name: Publish generated docs to GitHub Pages
        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4.0.0
        with:
          github_token: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
          publish_dir: docs
          publish_branch: docs

  ###################################################
  ## docker
  ###################################################

  docker_test:
    name: Test docker
    runs-on: ${{ matrix.runs_on }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - is_docker
      - versioned_source
    if: |
      github.event.pull_request.state == 'open' &&
      needs.is_docker.outputs.docker_bake_json != ''

    <<: *customWorkingDirectory

    strategy:
      fail-fast: false
      max-parallel: ${{ fromJSON(inputs.max_parallel) }}
      matrix: ${{ fromJSON(needs.is_docker.outputs.docker_test_matrix) }}

    env:
      DOCKER_BUILDKIT: "1"

    permissions:
      packages: read # pull private base images from ghcr.io

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha
      - *createLocalRefs
      - *sanitizeDockerStrings

      - <<: *setupBuildx

      - id: native_platforms
        <<: *jsonArrayBuilder
        env:
          INPUT: ${{ steps.setup_buildx.outputs.platforms }}

      # only register qemu binfmt if the target platform is not supported by the host natively
      - <<: *setupQemuBinfmt
        if: contains(steps.native_platforms.outputs.result, matrix.platform) != true

      # allow access to private base images for private repositories only
      # to avoid leaking secrets
      - <<:
          - *loginWithGitHubContainerRegistry
          - *ifPrivateRepository
      - <<:
          - *loginWithDockerHub
          - *ifPrivateRepository

      - name: Export common env vars
        run: |
          echo "DOCKER_BAKE_FILE=${{ runner.temp }}/docker-bake.json" >> "${GITHUB_ENV}"
          echo "DOCKER_TAR=${{ runner.temp }}/docker.tar" >> "${GITHUB_ENV}"

          echo "COMPOSE_PROJECT_NAME=${{ github.run_id }}" >> "${GITHUB_ENV}"
          echo "COMPOSE_FILE=${{ runner.temp }}/docker-compose.yml" >> "${GITHUB_ENV}"
          echo "COMPOSE_ENV_FILE=${{ runner.temp }}/.env" >> "${GITHUB_ENV}"

      # these secrets are being used in untrusted user code so only allow for internal PRs
      - name: Add COMPOSE_VARS to compose env file
        <<: *ifInternalPullRequest
        env:
          COMPOSE_VARS: ${{ secrets.COMPOSE_VARS }}
        # do not use shell tracing to avoid leaking secrets
        shell: bash
        run: |
          if [ -n "${COMPOSE_VARS}" ]
          then
            echo "${COMPOSE_VARS}" | base64 --decode > "${COMPOSE_ENV_FILE}"

            while read -r line
            do
              secret="$(echo "${line}" | awk -F'=' '{print $2}')"
              echo "::add-mask::${secret}"
            done < "${COMPOSE_ENV_FILE}"
          fi

      - name: Write docker bake file
        run: |
          echo '${{ needs.is_docker.outputs.docker_bake_json }}' > "${DOCKER_BAKE_FILE}"
          jq . "${DOCKER_BAKE_FILE}"

      - name: Write docker compose file
        if: needs.is_docker.outputs.docker_compose_tests == 'true'
        run: |
          files="
            docker-compose.yml
            docker-compose.yaml
            docker-compose.test.yml
            docker-compose.test.yaml
          "

          args=""
          for file in ${files}
          do
            test -f "${file}" || continue
            args="${args} -f ${file}"

            if [ ! -f .env ]
            then
              yq '.services.*.env_file |= map(with(select(. == ".env") ; . = "${{ env.COMPOSE_ENV_FILE }}"))' -i "${file}"
            fi
          done

          touch ${COMPOSE_ENV_FILE}
          docker compose --env-file="${COMPOSE_ENV_FILE}" --project-directory="$(pwd)" ${args} config > "${COMPOSE_FILE}"

          yq '(.services.* | select(.build != null)).platform |= "${{ matrix.platform }}"' -i "${COMPOSE_FILE}"
          yq . "${COMPOSE_FILE}"

      - *dockerTestMetadata
      - *dockerCacheFromMetadata

      # https://github.com/docker/bake-action
      - name: Docker bake
        id: docker_bake
        uses: docker/bake-action@7bff531c65a5cda33e52e43950a795b91d450f63 # v6.3.0
        with:
          # Use path context as v6 defaults to git context
          # https://github.com/docker/bake-action/releases/tag/v6.0.0
          # https://github.com/docker/bake-action?tab=readme-ov-file#git-context
          # https://github.com/docker/bake-action?tab=readme-ov-file#path-context
          source: .
          workdir: ${{ inputs.working_directory }}
          files: |
            ${{ env.DOCKER_BAKE_FILE }}
            ${{ steps.test_meta.outputs.bake-file }}
          targets: ${{ matrix.target }}
          set: |
            *.platform=${{ matrix.platform }}
            *.cache-to=type=gha,mode=max,scope=${{ matrix.target }}-${{ matrix.platform }}
            *.cache-from=type=gha,scope=${{ matrix.target }}-${{ matrix.platform }}
            *.cache-from=${{fromJSON(steps.cache_meta.outputs.json || '{}').tags[0] || ''}}
            *.cache-from=${{fromJSON(steps.cache_meta.outputs.json || '{}').tags[1] || ''}}
            *.cache-from=${{fromJSON(steps.cache_meta.outputs.json || '{}').tags[2] || ''}}
            *.cache-from=${{fromJSON(steps.cache_meta.outputs.json || '{}').tags[3] || ''}}
            *.cache-from=${{fromJSON(steps.cache_meta.outputs.json || '{}').tags[4] || ''}}
            *.cache-from=${{fromJSON(steps.cache_meta.outputs.json || '{}').tags[5] || ''}}
            *.cache-from=${{fromJSON(steps.cache_meta.outputs.json || '{}').tags[6] || ''}}
            *.cache-from=${{fromJSON(steps.cache_meta.outputs.json || '{}').tags[7] || ''}}
          load: true
          provenance: false

      # save image to file before running compose tests to avoid tainting the published image
      - name: Save image to file
        if: needs.is_docker.outputs.docker_publish_matrix != ''
        run: |
          docker save ${{ join(fromJSON(steps.test_meta.outputs.json).tags,' ') }} -o ${DOCKER_TAR}
          zstd -v ${DOCKER_TAR}

      # https://github.com/actions/runner-images/discussions/7191#discussioncomment-8351370
      # https://github.com/reactivecircus/android-emulator-runner?tab=readme-ov-file#running-hardware-accelerated-emulators-on-linux-runners
      # https://github.com/ankidroid/Anki-Android/commit/3a5ecaa9837691817022d11b0dbe383b8e82d9fe
      # https://github.blog/changelog/2023-02-23-hardware-accelerated-android-virtualization-on-actions-windows-and-linux-larger-hosted-runners/
      - name: Enable KVM group perms
        if: contains(fromJSON('["ubuntu-22.04","ubuntu-24.04","ubuntu-latest"]'), matrix.runs_on[0])
        continue-on-error: true
        run: |
          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
          sudo udevadm control --reload-rules
          sudo udevadm trigger -v --name-match=kvm

      # run docker compose tests and print the logs from all services
      - name: Run docker compose tests
        if: needs.is_docker.outputs.docker_compose_tests == 'true'
        run: |
          docker compose run sut || { docker compose logs ; exit 1 ; }
          docker compose logs

      # https://github.com/actions/upload-artifact
      - name: Upload artifacts
        if: needs.is_docker.outputs.docker_publish_matrix != ''
        uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4.6.0
        with:
          # this docker-{sha}-{target}-{platform} naming scheme is used by docker_publish to find the correct artifact
          name: docker-${{ matrix.target_slug }}-${{ matrix.platform_slug }}
          path: ${{ env.DOCKER_TAR }}.zst
          retention-days: 1

  docker_publish:
    name: Publish docker
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - versioned_source
      - is_docker
      - npm_test
      - custom_test
      - docker_test
      - cargo_test
      - python_test
    # allow some dependencies to be skipped
    if: |
      !failure() && !cancelled() &&
      needs.docker_test.result == 'success' &&
      needs.is_docker.outputs.docker_publish_matrix != ''

    <<: *rootWorkingDirectory

    services:
      registry:
        image: registry:2.8.3
        ports:
          - 5000:5000

    strategy:
      fail-fast: false
      max-parallel: ${{ fromJSON(inputs.max_parallel) }}
      matrix: ${{ fromJSON(needs.is_docker.outputs.docker_publish_matrix) }}

    env:
      LOCAL_TAG: localhost:5000/sut:latest

    # The calling workflow must set these permissions to use these optional features.
    # permissions:
    #   id-token: write # AWS GitHub OIDC provider
    #   packages: write # push manifests to ghcr.io

    steps:
      - *sanitizeDockerStrings
      - *dockerDraftMetadata
      - *setupBuildx
      - *setupCrane
      - *setupSkopeo
      - *setupAwsCli

      - name: Warn if tests skipped
        if: needs.is_docker.outputs.docker_compose_tests != 'true'
        run: echo "::warning::Publishing Docker images without docker compose tests!"

      # https://github.com/actions/download-artifact
      - name: Download required artifacts
        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
        with:
          path: ${{ runner.temp }}
          pattern: docker-${{ matrix.target_slug }}-*

      - name: Decompress artifacts
        env:
          PATH_PREFIX: ${{ runner.temp }}/docker-${{ matrix.target_slug }}
        run: |
          # shellcheck disable=SC2043
          for platform in ${{ matrix.platform_slugs }}
          do
            zstd -vd "${PATH_PREFIX}-${platform}/docker.tar.zst"
          done

      - name: Create local manifest
        env:
          PATH_PREFIX: ${{ runner.temp }}/docker-${{ matrix.target_slug }}
        run: |
          # shellcheck disable=SC2043
          for platform in ${{ matrix.platform_slugs }}
          do
            tar="${PATH_PREFIX}-${platform}/docker.tar"
            platform_tag="${LOCAL_TAG}-${platform}"

            skopeo copy --all "docker-archive:${tar}" "docker://${platform_tag}" --dest-tls-verify=false

            docker buildx imagetools create -t ${LOCAL_TAG} --append "${platform_tag}" || \
              docker buildx imagetools create -t ${LOCAL_TAG} "${platform_tag}"
            docker buildx imagetools inspect --raw "${LOCAL_TAG}" > "${{ runner.temp }}/manifest.json"
          done

      - *loginWithGitHubContainerRegistry
      - *loginWithDockerHub
      - *configureAWSCredentials
      - *getAWSCallerIdentity
      - *loginWithECRPublic
      - *loginWithECRPrivate

      # https://github.com/akhilerm/tag-push-action
      - name: Publish manifest to remote(s)
        uses: akhilerm/tag-push-action@f35ff2cb99d407368b5c727adbcc14a2ed81d509 # v2.2.0
        with:
          src: ${{ env.LOCAL_TAG }}
          dst: |
            ${{ steps.draft_meta.outputs.tags }}

      - &dockerPublishPlatformTags
        name: Publish tags for each platform
        if: inputs.docker_publish_platform_tags == true
        env:
          <<: *dockerPlatformSlugMap
          REMOTE_TAGS: ${{ steps.draft_meta.outputs.tags }}
        run: |
          for remote_tag in ${REMOTE_TAGS}
          do
            for b64 in $(jq -r '.manifests[].platform | @base64' <<< "$(docker buildx imagetools inspect --raw "${remote_tag}")")
            do
              json="$(echo "${b64}" | base64 --decode)"
              os="$(echo "${json}" | jq -r '.os')"
              arch="$(echo "${json}" | jq -r '.architecture')"
              variant="$(echo "${json}" | jq -r '.variant // ""')"

              if [ -z "${variant}" ]
              then
                platform="${os}/${arch}"
              else
                platform="${os}/${arch}/${variant}"
              fi

              platform_slug="$(jq -cr --arg platform "${platform}" '.[$platform] // ""' <<< "${PLATFORM_SLUG_MAP}")"

              if [ -z "{platform_slug}" ]
              then
                echo "::error::Unsupported platform: ${PLATFORM}"
              fi

              crane copy "${remote_tag}" "${remote_tag}-${platform_slug}" --platform "${platform}"
            done
          done

  docker_finalize:
    name: Finalize docker
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - is_docker
      - versioned_source
    if: |
      (github.event.pull_request.merged == true || github.event_name == 'push') &&
      needs.is_docker.outputs.docker_publish_matrix != ''

    <<: *rootWorkingDirectory

    strategy:
      fail-fast: false
      max-parallel: ${{ fromJSON(inputs.max_parallel) }}
      matrix: ${{ fromJSON(needs.is_docker.outputs.docker_publish_matrix) }}

    # The calling workflow must set these permissions to use these optional features.
    # permissions:
    #   id-token: write # AWS GitHub OIDC provider
    #   packages: write # push manifests to ghcr.io

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha
      - *sanitizeDockerStrings
      - *dockerFinalMetadata
      - *setupCrane
      - *setupAwsCli
      - *loginWithGitHubContainerRegistry
      - *loginWithDockerHub
      - *configureAWSCredentials
      - *getAWSCallerIdentity
      - *loginWithECRPublic
      - *loginWithECRPrivate

      # https://github.com/akhilerm/tag-push-action
      - name: Publish final tags
        uses: akhilerm/tag-push-action@f35ff2cb99d407368b5c727adbcc14a2ed81d509 # v2.2.0
        with:
          src: ${{ matrix.image }}:${{ steps.strings.outputs.prefix }}build-${{ github.event.pull_request.head.sha || github.event.head_commit.id }}${{ steps.strings.outputs.suffix }}
          dst: |
            ${{ steps.final_meta.outputs.tags }}

      - <<: *dockerPublishPlatformTags
        env:
          <<: *dockerPlatformSlugMap
          REMOTE_TAGS: ${{ steps.final_meta.outputs.tags }}

      # attempt to update the dockerhub description, but do not abort on failure
      - name: Update DockerHub Description
        if: contains(steps.strings.outputs.image,'docker.io') && github.base_ref == github.event.repository.default_branch
        continue-on-error: true
        uses: peter-evans/dockerhub-description@e98e4d1628a5f3be2be7c231e50981aee98723ae # v4.0.0
        with:
          username: ${{ secrets.DOCKERHUB_USER || secrets.DOCKER_REGISTRY_USER }}
          password: ${{ secrets.DOCKERHUB_TOKEN || secrets.DOCKER_REGISTRY_PASS }}
          repository: ${{ steps.strings.outputs.repo }}
          readme-filepath: ./README.md

  ###################################################
  ## balena
  ###################################################

  balena_publish:
    name: Publish balena
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - is_balena
      - npm_test
      - custom_test
      - docker_test
      - cargo_test
      - python_test
      - versioned_source
      - release_notes
    # allow some dependencies to be skipped
    if: |
      !failure() && !cancelled() &&
      needs.is_balena.result == 'success' &&
      (github.event.action != 'closed' || github.event.pull_request.merged == true)

    strategy:
      fail-fast: false
      max-parallel: ${{ fromJSON(inputs.max_parallel) }}
      matrix:
        slug: ${{ fromJSON(needs.is_balena.outputs.balena_slugs) }}

    permissions:
      packages: read # pull private base images from ghcr.io

    <<: *customWorkingDirectory

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha
      - uses: balena-io/deploy-to-balena-action@3cb4217ab3347a885b4fcdc44d5f3a4153145633 # v2.0.92
        id: balena_deploy
        with:
          balena_token: ${{ secrets.BALENA_API_KEY || secrets.BALENA_API_KEY_PUSH }}
          environment: ${{ inputs.balena_environment }}
          fleet: ${{ matrix.slug }}
          source: ${{ inputs.working_directory }}
          note: ${{ needs.release_notes.outputs.note }}
          # Feb 2023: as per GitHub support: "You cannot authenticate with a GitHub App token on the GitHub Package Registry"
          # Nov 2024: Still cannot use GitHub App Tokens to authenticate with the GitHub Package Registry (login works, push/pull fails)
          registry_secrets: |
            {
              "ghcr.io": {
                "username": "${{ github.actor }}",
                "password": "${{ secrets.GITHUB_TOKEN }}"
              },
              "docker.io": {
                "username": "${{ secrets.DOCKERHUB_USER }}",
                "password": "${{ secrets.DOCKERHUB_TOKEN }}"
              }
            }

  ###################################################
  ## Python
  ###################################################

  python_test:
    name: Test python poetry
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - is_python
      - versioned_source
    if: |
      github.event.pull_request.state == 'open' &&
      needs.is_python.outputs.python_poetry == 'true'

    <<: *customWorkingDirectory

    permissions: {}

    strategy:
      fail-fast: false
      max-parallel: ${{ fromJSON(inputs.max_parallel) }}
      matrix:
        python-version: ${{ fromJSON(needs.is_python.outputs.python_versions) }}

    outputs:
      package: ${{ steps.meta.outputs.package }}
      version: ${{ steps.meta.outputs.version }}
      branch_tag: ${{ steps.meta.outputs.branch_tag }}
      sha_tag: ${{ steps.meta.outputs.sha_tag }}
      version_tag: ${{ steps.meta.outputs.version_tag }}

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha
      - *createLocalRefs

      - <<: *setupPython
        with:
          python-version: ${{ matrix.python-version }}

      - *setupPoetry

      - name: Run poetry install
        run: |
          poetry install

      - name: Add linters and pytest to poetry
        run: |
          dep_list=`poetry show`
          if (grep -wq ^flake8 <<< "$dep_list") && \
             (grep -wq ^pydocstyle <<< "$dep_list") && \
             (grep -wq ^pytest <<< "$dep_list")
          then
            echo "Dev dependencies already installed"
          else
            poetry add --group dev flake8@latest pydocstyle@latest pytest@latest
          fi

      - name: Generate metadata
        id: meta
        run: |
          package=$(grep '^name =' pyproject.toml | sed 's/name = "\(.*\)"/\1/')
          version=$(grep '^version =' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
          branch_tag="$(echo "build-${GITHUB_HEAD_REF}" | sed 's/[^[:alnum:]]/-/g')"
          sha_tag="${branch_tag}-${{ github.event.pull_request.head.sha }}"
          version_tag="${version}-${branch_tag}-${{ github.event.pull_request.head.sha }}"

          echo "package=${package}" >> "${GITHUB_OUTPUT}"
          echo "version=${version}" >> "${GITHUB_OUTPUT}"
          echo "branch_tag=${branch_tag}" >> "${GITHUB_OUTPUT}"
          echo "sha_tag=${sha_tag}" >> "${GITHUB_OUTPUT}"
          echo "version_tag=${version_tag}" >> "${GITHUB_OUTPUT}"

      - name: Lint with flake8
        run: |
          poetry run flake8 --max-line-length=120 --benchmark

      - name: Lint with pydocstyle
        run: |
          poetry run pydocstyle

      - name: Test with pytest
        if: inputs.pseudo_terminal != true
        run: |
          poetry run pytest tests/

      - name: Test with pytest (pseudo-tty)
        if: inputs.pseudo_terminal == true
        shell: script -q -e -c "bash --noprofile --norc -eo pipefail -x {0}" /tmp/test-session
        run: |
          poetry run pytest tests/

  python_sbom:
    name: Generate SBOM for python
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    continue-on-error: true
    needs:
      - is_python
      - python_test
      - versioned_source
    if: needs.is_python.outputs.python_poetry == 'true' && needs.is_python.outputs.python_sbom == 'true'

    <<: *customWorkingDirectory

    permissions: {}

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha
      - *createLocalRefs

      - *setupPython

      - *setupPoetry

      - name: Run poetry install
        run: poetry install

      - name: Install CycloneDX for Python
        run: |
          pip3 install 'cyclonedx-bom>=1.4.0,<4'

      - name: Generate SBOM
        run: cyclonedx-py -r -i ./poetry.lock --format xml -o ${{ runner.temp }}/python-sbom.xml

      - <<: *publishSBOMArtifacts
        with:
          name: gh-release-sbom-python
          path: ${{ runner.temp }}/python-sbom.xml
          retention-days: 90

      - <<: *publishSBOMToDependencyTrack
        env:
          SERVER_HOSTNAME: ${{ vars.DTRACK_API }}
          API_KEY: ${{ secrets.DTRACK_TOKEN }}
          PROJECT_NAME: ${{ github.event.repository.name }}
          BOM_FILE: ${{ runner.temp }}/python-sbom.xml
          PROJECT_VERSION: ${{ needs.python_test.outputs.version_tag }}

  python_publish:
    name: Publish to test PyPI
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - is_python
      - npm_test
      - custom_test
      - docker_test
      - cargo_test
      - python_test
      - versioned_source
    # allow some dependencies to be skipped
    if: |
      !failure() && !cancelled() &&
      needs.python_test.result == 'success' &&
      needs.is_python.outputs.python_poetry == 'true' &&
      needs.is_python.outputs.pypi_publish == 'true'

    <<: *customWorkingDirectory

    permissions: {}

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha
      - *createLocalRefs

      - *setupPython
      - *setupPoetry

      - *generatePythonMetadata

      - name: Run poetry install
        run: |
          poetry install

      - name: Publish draft release
        env:
          PYPI_TOKEN: ${{ secrets.PYPI_TEST_TOKEN }}
        run: |
          poetry version ${{ steps.python_meta.outputs.version_tag }}
          poetry config repositories.test-pypi https://test.pypi.org/legacy/
          poetry config pypi-token.test-pypi $PYPI_TOKEN
          poetry publish --build -r test-pypi

  python_finalize:
    name: Finalize python
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - is_python
      - versioned_source
    if: |
      (github.event.pull_request.merged == true || github.event_name == 'push') &&
      needs.is_python.outputs.python_poetry == 'true' &&
      needs.is_python.outputs.pypi_publish == 'true'

    <<: *customWorkingDirectory

    permissions: {}

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha

      - *setupPython
      - *setupPoetry

      - name: Publish release
        env:
          PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
        run: |
          poetry config pypi-token.pypi $PYPI_TOKEN
          poetry publish --build

  ###################################################
  # Website
  ###################################################

  website_publish:
    name: Publish website
    runs-on: ${{fromJSON(inputs.runs_on)}}
    outputs:
      cloudflare_deployment_url: ${{ steps.output_cf_url.outputs.cloudflare_deployment_url }}
    env:
      CF_BRANCH: ${{ github.event.pull_request.head.ref || github.event.repository.default_branch }}
    needs:
      - file_list
      - npm_test
      - custom_test
      - docker_test
      - cargo_test
      - python_test
      - versioned_source
    # allow some dependencies to be skipped
    # skip unmerged closed PRs, allow all other events
    if: |
      !failure() && !cancelled() && needs.versioned_source.result == 'success' &&
      inputs.cloudflare_website != '' &&
      (github.event.action != 'closed' || github.event.pull_request.merged == true)

    permissions: {}

    steps:
      - <<: *getGitHubAppToken
        with:
          <<: *getGitHubAppTokenWith
          # pull_requests: write is required to create or update pull request comments
          permissions: >-
            {
              "metadata": "read",
              "contents": "read",
              "issues": "read",
              "pull_requests": "write"
            }
      - *checkoutVersionedSha
      - *createLocalRefs

      - <<: *setupNode
        # FIXME: does this need to be pinned to 18? Remove the property and use the global default otherwise.
        with:
          node-version: 18

      - name: Docusaurus Builder
        if: |
          contains(needs.file_list.outputs.workdir, 'README.md') &&
          inputs.docusaurus_website != false
        uses: product-os/docusaurus-builder@699d83eb85945ac55f5699579987159d3754f268 # v2.1.36
        with:
          repo: ${{ github.event.repository.name }}
          org: ${{ github.repository_owner }}
          default_branch: ${{ github.event.repository.default_branch }}
          url: https://${{ inputs.cloudflare_website }}.pages.dev/

      - name: Custom Website Builder
        if: |
          inputs.docusaurus_website == false
        run: npm run deploy-docs --if-present

      - name: Update deploy branch for merged PRs
        if: github.event.pull_request.state != 'open'
        run: |
          echo "CF_BRANCH=${{ github.event.repository.default_branch }}" >> "${GITHUB_ENV}"

      - name: Deploy to Cloudflare Pages
        id: deploy_cf_pages
        uses: cloudflare/wrangler-action@7a5f8bbdfeedcde38e6777a50fe685f89259d4ca # v3.13.1
        with:
          apiToken: ${{ secrets.CF_API_TOKEN }}
          accountId: ${{ secrets.CF_ACCOUNT_ID }}
          wranglerVersion: "3.5.1" # latest - https://www.npmjs.com/package/wrangler
          command: pages deploy --branch ${{ env.CF_BRANCH }} --project-name=${{ inputs.cloudflare_website }} build/

      - name: Set Cloudflare Pages deployment-url to output
        id: output_cf_url
        if: steps.deploy_cf_pages.outputs.deployment-url != ''
        env:
          DEPLOYMENT_URL: ${{ steps.deploy_cf_pages.outputs.deployment-url }}
        run: |
          echo "cloudflare_deployment_url=${DEPLOYMENT_URL}" >> "$GITHUB_OUTPUT"

      - name: Find Cloudflare Pages link comment
        uses: peter-evans/find-comment@3eae4d37986fb5a8592848f6a574fdf654e61f9e # v3.1.0
        id: find_cf_comment
        with:
          issue-number: ${{ github.event.pull_request.number }}
          body-includes: Website deployed to CF Pages, 👀 preview link
          token: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}

      - name: Create or update Cloudflare Pages link comment if deployment link present
        uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 # v4.0.0
        if: steps.deploy_cf_pages.outputs.deployment-url != ''
        with:
          comment-id: ${{ steps.find_cf_comment.outputs.comment-id }}
          issue-number: ${{ github.event.pull_request.number }}
          edit-mode: replace
          token: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
          body: |
            Website deployed to CF Pages, 👀 preview link ${{ steps.deploy_cf_pages.outputs.deployment-url }}

  ###################################################
  # GitHub
  ###################################################

  github_clean:
    name: Clean GitHub release
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - event_types
    if: |
      github.event.action == 'closed' &&
      github.event.pull_request.merged == false

    <<: *rootWorkingDirectory

    permissions: {}

    steps:
      - <<: *getGitHubAppToken
        with:
          <<: *getGitHubAppTokenWith
          # contents:write permissions for managing releases
          permissions: >-
            {
              "contents": "write",
              "metadata": "read"
            }

      - *deleteDraftGitHubRelease

  github_publish:
    name: Publish Github release
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - versioned_source
      - release_notes
      - npm_publish
      - python_publish
      - cargo_publish
      - custom_publish
      - npm_sbom
      - python_sbom
      - cargo_sbom
    # allow some dependencies to be skipped
    if: |
      !failure() && !cancelled() &&
      github.event.pull_request.state == 'open' &&
      needs.versioned_source.outputs.tag != ''

    <<: *rootWorkingDirectory

    permissions: {}

    steps:
      - <<: *getGitHubAppToken
        with:
          <<: *getGitHubAppTokenWith
          # contents:write permissions for managing releases
          permissions: >-
            {
              "contents": "write",
              "metadata": "read"
            }

      - *deleteDraftGitHubRelease
      - *checkoutVersionedSha

      # https://github.com/actions/download-artifact
      - name: Download release artifacts
        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
        with:
          path: ${{ runner.temp }}/artifacts
          pattern: gh-release-*
          merge-multiple: true

      # https://github.com/actions/download-artifact
      - name: Download release notes
        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
        with:
          path: ${{ runner.temp }}
          name: release-notes

      # https://github.com/softprops/action-gh-release
      - name: Publish draft release
        uses: softprops/action-gh-release@c95fe1489396fe8a9eb87c0abf8aa5b2ef267fda # v2.2.1
        with:
          token: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
          name: ${{ github.event.pull_request.head.ref }}
          tag_name: ${{ github.event.pull_request.head.ref }}
          draft: true
          prerelease: true
          files: ${{ runner.temp }}/artifacts/*
          fail_on_unmatched_files: false
          body: ${{ needs.release_notes.outputs.note }}
          body_path: ${{ runner.temp }}/release-notes.txt

  github_finalize:
    name: Finalize GitHub release
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - versioned_source
      - release_notes
    if: |
      (
        (
          github.event.pull_request.merged == true &&
          inputs.disable_versioning == false
        ) || (
          github.event_name == 'push' &&
          inputs.disable_versioning == true
        )
      )

    <<: *rootWorkingDirectory

    permissions: {}

    steps:
      - <<: *getGitHubAppToken
        with:
          <<: *getGitHubAppTokenWith
          # contents:write permissions for managing releases
          permissions: >-
            {
              "contents": "write",
              "metadata": "read"
            }

      - *checkoutVersionedSha

      # https://github.com/actions/download-artifact
      - name: Download release notes
        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
        with:
          path: ${{ runner.temp }}
          name: release-notes

      # https://docs.github.com/en/rest/releases
      - name: Finalize GitHub release (if any)
        env:
          <<: *gitHubCliEnvironment
          GH_TOKEN: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
        run: |
          set -ea

          if gh release view "${GITHUB_HEAD_REF}"; then
            gh release edit "${GITHUB_HEAD_REF}" \
              --notes-file '${{ runner.temp }}/release-notes.txt' \
              --title '${{ needs.versioned_source.outputs.tag }}' \
              --tag '${{ needs.versioned_source.outputs.tag }}' \
              --prerelease='${{ inputs.github_prerelease }}' \
              --draft=false

            if [[ ${{ inputs.github_prerelease }} =~ false ]]; then
                release_id="$(gh api "/repos/${{ github.repository }}/releases/tags/${{ needs.versioned_source.outputs.tag }}" \
                  -H 'Accept: application/vnd.github+json' | jq -r .id)"
                gh api --method PATCH "/repos/${{ github.repository }}/releases/${release_id}" \
                  -H 'Accept: application/vnd.github+json' \
                  -F make_latest=true
            fi
          else
            echo "No release found for the current PR"
          fi

  ###################################################
  # rust
  ###################################################

  cargo_test:
    name: Test rust
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - is_cargo
      - versioned_source
    if: |
      github.event.pull_request.state == 'open' &&
      needs.is_cargo.outputs.cargo == 'true'

    <<: *customWorkingDirectory

    permissions: {}

    strategy:
      fail-fast: false
      max-parallel: ${{ fromJSON(inputs.max_parallel) }}
      matrix:
        target: ${{ fromJSON(needs.is_cargo.outputs.cargo_targets) }}

    outputs:
      package: ${{ steps.meta.outputs.package }}
      version: ${{ steps.meta.outputs.version }}
      branch_tag: ${{ steps.meta.outputs.branch_tag }}
      sha_tag: ${{ steps.meta.outputs.sha_tag }}
      version_tag: ${{ steps.meta.outputs.version_tag }}

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha
      - *createLocalRefs

      - name: Set up toolchain ${{ matrix.target }}
        uses: dtolnay/rust-toolchain@master
        with:
          toolchain: ${{ inputs.rust_toolchain }}
          targets: ${{ matrix.target }}
          components: rustfmt

      - name: Check formatting
        run: cargo fmt --check

      - name: Install cross
        run: cargo install cross --locked

      - name: Lint with clippy
        run: cross -v clippy --all-targets --all-features --target ${{ matrix.target }} -- -D warnings

      - name: Run tests for toolchain ${{ matrix.target }}
        run: cross -v test --locked --target ${{ matrix.target }}

      - name: Generate metadata
        id: meta
        run: |
          package="$(grep '^name = \"' Cargo.toml | awk -F[\"\"] '{print $2}')"
          version="${{ needs.versioned_source.outputs.semver }}"
          branch_tag="$(echo "${GITHUB_HEAD_REF}" | sed 's/[^[:alnum:]]/-/g')"
          sha_tag="${branch_tag}-${{ github.event.pull_request.head.sha }}"
          version_tag="${version}-${branch_tag}-${{ github.event.pull_request.head.sha }}"

          {
            echo "package=${package}" ;
            echo "version=${version}" ;
            echo "branch_tag=${branch_tag}" ;
            echo "sha_tag=${sha_tag}" ;
            echo "version_tag=${version_tag}" ;
          } >> "${GITHUB_OUTPUT}"

  cargo_sbom:
    name: Generate SBOM for cargo
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    continue-on-error: true
    needs:
      - is_cargo
      - cargo_test
      - versioned_source
    if: needs.is_cargo.outputs.cargo == 'true' && needs.is_cargo.outputs.cargo_sbom == 'true'

    <<: *customWorkingDirectory

    permissions: {}

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha
      - *createLocalRefs

      - name: Set up toolchain
        uses: dtolnay/rust-toolchain@master
        with:
          toolchain: stable

      - name: Install CycloneDX for Cargo
        run: cargo install cargo-cyclonedx

      - name: Generate SBOM
        run: |
          cargo cyclonedx --override-filename bom
          mv bom.xml ${{ runner.temp }}/cargo-sbom.xml

      - <<: *publishSBOMArtifacts
        with:
          name: gh-release-sbom-cargo
          path: ${{ runner.temp }}/cargo-sbom.xml
          retention-days: 90

      - <<: *publishSBOMToDependencyTrack
        env:
          SERVER_HOSTNAME: ${{ vars.DTRACK_API }}
          API_KEY: ${{ secrets.DTRACK_TOKEN }}
          PROJECT_NAME: ${{ github.event.repository.name }}
          BOM_FILE: ${{ runner.temp }}/cargo-sbom.xml
          PROJECT_VERSION: ${{ needs.cargo_test.outputs.version_tag }}

  cargo_publish:
    name: Publish rust
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - is_cargo
      - npm_test
      - custom_test
      - docker_test
      - cargo_test
      - python_test
      - versioned_source
    # allow some dependencies to be skipped
    if: |
      !failure() && !cancelled() &&
      needs.cargo_test.result == 'success' &&
      inputs.rust_binaries == true

    <<: *customWorkingDirectory

    permissions: {}

    strategy:
      fail-fast: false
      max-parallel: ${{ fromJSON(inputs.max_parallel) }}
      matrix:
        target: ${{ fromJSON(needs.is_cargo.outputs.cargo_targets) }}

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha
      - *createLocalRefs

      - name: Set up toolchain ${{ matrix.target }}
        uses: dtolnay/rust-toolchain@master
        with:
          toolchain: ${{ inputs.rust_toolchain }}
          targets: ${{ matrix.target }}

      - name: Install cross
        run: cargo install cross --locked

      - name: Build release for toolchain ${{ matrix.target }}
        run: cross -v build --locked --release --target ${{ matrix.target }}

      - name: Install LLVM
        run: sudo apt-get install -y llvm

      - name: LLVM strip
        run: llvm-strip target/${{ matrix.target }}/release/${{ needs.cargo_test.outputs.package }}

      - name: Compress
        run: |
          tar --auto-compress -cvf ${{ needs.cargo_test.outputs.package }}-${{ matrix.target }}.tar.gz -C target/${{ matrix.target }}/release ${{ needs.cargo_test.outputs.package }}

      - name: Upload artifact
        uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4.6.0
        with:
          name: gh-release-${{ matrix.target }}
          path: ${{ needs.cargo_test.outputs.package }}-${{ matrix.target }}.tar.gz
          retention-days: 1

  cargo_finalize:
    name: Finalize rust
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - is_cargo
      - versioned_source
    if: |
      (github.event.pull_request.merged == true || github.event_name == 'push') &&
      needs.is_cargo.outputs.cargo == 'true'

    <<: *customWorkingDirectory

    permissions: {}

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha

      - name: Set up toolchain
        uses: dtolnay/rust-toolchain@stable

      - name: Publish crate to ${{ env.CARGO_REGISTRY }}
        if: needs.is_cargo.outputs.cargo_publish != 'false'
        env:
          CARGO_REGISTRY_DEFAULT: ${{ env.CARGO_REGISTRY }}
          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
        run: |
          if [ -n "$CARGO_REGISTRY_TOKEN" ]; then
            cargo publish
          fi

  ###################################################
  ## custom
  ###################################################

  custom_test:
    name: Test custom
    runs-on: ${{ matrix.os || fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - is_custom
      - versioned_source
    if: |
      github.event.pull_request.state == 'open' &&
      needs.is_custom.outputs.custom_test == 'true'

    # The permissions for custom actions are set by the calling workflow
    # and should not be overridden by Flowzone.

    strategy:
      fail-fast: false
      max-parallel: ${{ fromJSON(inputs.max_parallel) }}
      matrix: ${{ fromJSON(needs.is_custom.outputs.custom_test_matrix) }}

    environment: ${{ matrix.environment }}

    steps:
      - *rejectExternalCustomActions
      - <<: *getGitHubAppToken
        with:
          <<: *getGitHubAppTokenWith
          # use permissions from the token_scope input
          permissions: ${{ inputs.token_scope }}

      - *checkoutVersionedSha
      - *resetGitHubDirectory
      - *createLocalRefs

      - name: Set the matrix value env var
        shell: bash
        run: |
          {
            echo "matrix_value=${{ matrix.value }}" ;
            echo "os_value=$(echo '${{ toJSON(matrix.os) }}' | jq -c .)" ;
            echo "environment=${{ matrix.environment }}" ;
          } >> "${GITHUB_ENV}"

      - uses: ./.github/actions/test
        with:
          json: ${{ toJSON(inputs) }}
          secrets: ${{ toJSON(secrets) }}
          variables: ${{ toJSON(vars) }}

  custom_publish:
    name: Publish custom
    runs-on: ${{ matrix.os || fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - is_custom
      - npm_test
      - custom_test
      - docker_test
      - cargo_test
      - python_test
      - versioned_source
    # allow some dependencies to be skipped
    if: |
      !failure() && !cancelled() &&
      github.event.pull_request.state == 'open' &&
      needs.is_custom.outputs.custom_publish == 'true'

    # The permissions for custom actions are set by the calling workflow
    # and should not be overridden by Flowzone.

    strategy:
      fail-fast: false
      max-parallel: ${{ fromJSON(inputs.max_parallel) }}
      matrix: ${{ fromJSON(needs.is_custom.outputs.custom_publish_matrix) }}

    environment: ${{ matrix.environment }}

    steps:
      - *rejectExternalCustomActions

      - <<: *getGitHubAppToken
        with:
          <<: *getGitHubAppTokenWith
          # use permissions from the token_scope input
          permissions: ${{ inputs.token_scope }}

      - *checkoutVersionedSha
      - *resetGitHubDirectory
      - *createLocalRefs

      - name: Set the matrix value env var
        shell: bash
        run: |
          {
            echo "matrix_value=${{ matrix.value }}" ;
            echo "os_value=$(echo '${{ toJSON(matrix.os) }}' | jq -c .)" ;
            echo "environment=${{ matrix.environment }}" ;
          } >> "${GITHUB_ENV}"

      - uses: ./.github/actions/publish
        with:
          json: ${{ toJSON(inputs) }}
          secrets: ${{ toJSON(secrets) }}
          variables: ${{ toJSON(vars) }}

  custom_finalize:
    name: Finalize custom
    runs-on: ${{ matrix.os || fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - is_custom
      - versioned_source
    if: |
      (github.event.pull_request.merged == true || github.event_name == 'push') &&
      needs.is_custom.outputs.custom_finalize == 'true'

    # The permissions for custom actions are set by the calling workflow
    # and should not be overridden by Flowzone.

    strategy:
      fail-fast: false
      max-parallel: ${{ fromJSON(inputs.max_parallel) }}
      matrix: ${{ fromJSON(needs.is_custom.outputs.custom_finalize_matrix) }}

    environment: ${{ matrix.environment }}

    steps:
      - *rejectExternalCustomActions

      - <<: *getGitHubAppToken
        with:
          <<: *getGitHubAppTokenWith
          # use permissions from the token_scope input
          permissions: ${{ inputs.token_scope }}

      - *checkoutVersionedSha
      - *resetGitHubDirectory

      - name: Set the matrix value env var
        shell: bash
        run: |
          {
            echo "matrix_value=${{ matrix.value }}" ;
            echo "os_value=$(echo '${{ toJSON(matrix.os) }}' | jq -c .)" ;
            echo "environment=${{ matrix.environment }}" ;
          } >> "${GITHUB_ENV}"

      - uses: ./.github/actions/finalize
        with:
          json: ${{ toJSON(inputs) }}
          secrets: ${{ toJSON(secrets) }}
          variables: ${{ toJSON(vars) }}

  custom_clean:
    name: Clean custom
    runs-on: ${{ matrix.os || fromJSON(inputs.runs_on) }}
    strategy:
      fail-fast: true
      max-parallel: ${{ fromJSON(inputs.max_parallel) }}
      matrix:
        os: ${{ fromJSON(inputs.custom_runs_on || format('[{0}]', inputs.runs_on)) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - is_custom
      - versioned_source
    if: |
      github.event.action == 'closed' &&
      github.event.pull_request.merged == false &&
      needs.is_custom.outputs.custom_clean == 'true'

    # The permissions for custom actions are set by the calling workflow
    # and should not be overridden by Flowzone.

    steps:
      - *rejectExternalCustomActions

      - <<: *getGitHubAppToken
        with:
          <<: *getGitHubAppTokenWith
          # use permissions from the token_scope input
          permissions: ${{ inputs.token_scope }}

      - *checkoutVersionedSha
      - *resetGitHubDirectory

      - uses: ./.github/actions/clean
        with:
          json: ${{ toJSON(inputs) }}
          secrets: ${{ toJSON(secrets) }}
          variables: ${{ toJSON(vars) }}

  custom_always:
    name: Always custom
    runs-on: ${{ matrix.os || fromJSON(inputs.runs_on) }}
    strategy:
      fail-fast: true
      max-parallel: ${{ fromJSON(inputs.max_parallel) }}
      matrix:
        os: ${{ fromJSON(inputs.custom_runs_on || format('[{0}]', inputs.runs_on)) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - custom_test
      - custom_publish
      - custom_finalize
      - custom_clean
      - is_custom
      - versioned_source
    if: |
      always() &&
      needs.is_custom.outputs.custom_always == 'true'

    # The permissions for custom actions are set by the calling workflow
    # and should not be overridden by Flowzone.

    steps:
      - *rejectExternalCustomActions

      - <<: *getGitHubAppToken
        with:
          <<: *getGitHubAppTokenWith
          # use permissions from the token_scope input
          permissions: ${{ inputs.token_scope }}

      - *checkoutVersionedSha
      - *resetGitHubDirectory

      - uses: ./.github/actions/always
        with:
          json: ${{ toJSON(inputs) }}
          secrets: ${{ toJSON(secrets) }}
          variables: ${{ toJSON(vars) }}

  ###################################################
  # AWS/CloudFormation
  ###################################################

  cloudformation_test:
    name: Test CloudFormation
    runs-on: ${{ fromJSON(inputs.cloudformation_runs_on || inputs.runs_on) }}
    strategy:
      fail-fast: true
      max-parallel: ${{ fromJSON(inputs.max_parallel) }}
      matrix:
        stack: ${{ fromJSON(needs.is_cloudformation.outputs.stacks) }}
        include: ${{ fromJSON(needs.is_cloudformation.outputs.includes) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - is_cloudformation
      - versioned_source
    if: |
      github.event.pull_request.state == 'open' &&
      needs.is_cloudformation.outputs.cloudformation == 'true' &&
      needs.is_cloudformation.outputs.stacks != '' &&
      needs.is_cloudformation.outputs.stacks != '[]'

    <<: *customWorkingDirectory

    env:
      AWS_RETRY_MODE: adaptive
      AWS_MAX_ATTEMPTS: 10
      AWS_REGION: ${{ matrix.region || inputs.aws_region }}
      AWS_DEFAULT_REGION: ${{ matrix.region || inputs.aws_region }}
      ATTEMPTS: 5
      TIMEOUT: 3

    # sets the GH environment context for secrets and variables
    environment: ${{ matrix.environment }}

    # The calling workflow must set these permissions to use these optional features.
    # permissions:
    #   id-token: write # AWS GitHub OIDC provider

    steps:
      - *setupAwsCli
      - *getGitHubAppToken
      - *checkoutVersionedSha
      - *randomDelay # Why do people always forget that you need to add a little jitter?
      - *configureAWSCredentials
      - *getAWSCallerIdentity
      - *convenienceFunctions

      - name: Create templates bucket
        id: make_bucket
        run: |
          # If at first you don't succeed, back off exponentially.
          source '${{ steps.functions.outputs.with_backoff }}'

          bucket="$(with_backoff aws s3api list-buckets | jq -r '.Buckets[] | select(.Name | (startswith("cfn-") and endswith("-${{ matrix.region || inputs.aws_region }}"))).Name' | head -n 1)"
          if [[ -z "$bucket" ]]; then
              result="$(with_backoff aws s3 mb "s3://cfn-$(uuidgen)-${{ matrix.region || inputs.aws_region }}" \
                --region '${{ matrix.region || inputs.aws_region }}')"

              bucket="${result#*:}"
              bucket="${bucket//[[:space:]]/}"
          fi
          echo "s3_bucket=${bucket}" >> "${GITHUB_OUTPUT}"

      - *waitForCloudFormation

      - name: Generate shared outputs
        id: shared
        env:
          SECRETS_CONTEXT: ${{ toJson(secrets) }}
          VARS_CONTEXT: ${{ toJson(vars) }}
        run: |
          set -a

          trap 'rm -f .env' EXIT

          # shellcheck disable=SC2140
          to_envs() { jq -r "to_entries[] | \"\(.key)="\'"\(.value)"\'"\""; }

          printf "matrix: params='%s' tags='%s' caps='%s'" \
            '${{ toJSON(matrix.params) }}' \
            '${{ toJSON(matrix.tags) }}' \
            '${{ toJSON(matrix.capabilities) }}'

          stacks="$(echo '${{ inputs.cloudformation_templates }}' | yq e -P - | yq e -o=json -)"
          stack="$(echo "${stacks}" | jq -r '.stacks[] | select(.name=="${{ matrix.stack }}")')"
          template_file="$(echo "${stack}" | jq -rc .template)"
          tags="$(echo "${stack}" | jq -rc .tags[] | paste -sd' ' -) github_pull_request=${{ github.event.pull_request.number }} github_sha=${{ github.event.pull_request.head.sha || github.event.head_commit.id }}"
          params="$(echo "${stack}" | jq -c .params[] | paste -sd' ' - || echo '')"
          kvparams="$(echo "${stack}" | jq -rc .params | jq -r 'map(split("=") as [$ParameterKey, $ParameterValue] | {$ParameterKey, $ParameterValue})[] | "ParameterKey=" + .ParameterKey + ",ParameterValue=" + .ParameterValue' | paste -sd' ' - || echo '')"
          caps="$(echo "${stack}" | jq -rc .capabilities[] | paste -sd' ' -)"
          ignore_lint="$(echo "${stack}" | jq -rc .ignore_lint)"

          echo "${SECRETS_CONTEXT}" | to_envs > .env
          echo "${VARS_CONTEXT}" | to_envs >> .env
          source .env && rm -f .env

          {
            echo "stack_name=${{ matrix.stack }}" ;
            echo "template_file=${template_file}" ;
            echo "tags=${tags}" ;
            echo "ignore_lint=${ignore_lint}" ;
          } >> "${GITHUB_OUTPUT}"

          if [[ -n "$params" ]]; then
            EOF="$(openssl rand -hex 16)"
            params="$(echo "${params}" | envsubst)"
            {
              echo "params<<$EOF" ;
              # shellcheck disable=SC2086
              echo --parameter-overrides ${params} ;
              echo "$EOF" ;
            } >> "${GITHUB_OUTPUT}"
          fi

          if [[ -n "$kvparams" ]]; then
            EOF="$(openssl rand -hex 16)"
            kvparams="$(echo "${kvparams}" | envsubst)"
            {
              echo "kvparams<<$EOF" ;
              # shellcheck disable=SC2086
              echo --parameters ${kvparams} ;
              echo "$EOF" ;
            } >> "${GITHUB_OUTPUT}"
          fi

          echo "caps=${caps}" >> "${GITHUB_OUTPUT}"

      - <<: *setupPython
        with:
          cache: "pip" # caching pip dependencies
          python-version: 3.11

      - name: Install cfn-lint
        run: |
          python -m pip install --upgrade pip
          python -m pip install cfn-lint==0.83.7

      - name: Lint template
        run: |
          ignore="${DEFAULT_IGNORE} ${IGNORE}"
          if [[ -z "$IGNORE" ]] || [[ "$IGNORE" =~ null ]]; then
              ignore="${DEFAULT_IGNORE}"
          fi
          cfn-lint -i ${ignore} -t '${{ steps.shared.outputs.template_file }}'
        env:
          DEFAULT_IGNORE: W2001 W3002 W4002 W6001 W8003 E3026 E2520 W3045
          IGNORE: ${{ steps.shared.outputs.ignore_lint }}

      - name: Validate template
        run: |
          source '${{ steps.functions.outputs.with_backoff }}'

          tmpvalid="$(openssl rand -hex 16)"

          trap 'aws s3 rm s3://${{ steps.make_bucket.outputs.s3_bucket }}/${tmpvalid}' EXIT

          with_backoff aws s3 cp '${{ steps.shared.outputs.template_file }}' \
            "s3://${{ steps.make_bucket.outputs.s3_bucket }}/${tmpvalid}"

          with_backoff aws cloudformation validate-template \
            --template-url "https://s3.amazonaws.com/${{ steps.make_bucket.outputs.s3_bucket }}/${tmpvalid}"

      - name: Prepare (Python) Lambda dependencies
        run: |
          template_base_directory="$(dirname '${{ steps.shared.outputs.template_file }}')"

          python_lambdas="$(cat <'${{ steps.shared.outputs.template_file }}' \
            | yq e -oj \
            | jq -r '.Resources[]
            | select((.Type=="AWS::Lambda::Function")
            and (.Properties.Runtime | select (.!=null) | startswith("python"))).Properties.Code')"

          for python_lambda in ${python_lambdas:-}; do
              if [[ -d "$template_base_directory/$python_lambda" ]]; then
                  pushd "${template_base_directory}/${python_lambda}"
                  if [[ -s requirements.txt ]]; then
                      pip install -r requirements.txt -t .
                  fi
                  popd
              fi
          done

      - name: Package template
        run: |
          source '${{ steps.functions.outputs.with_backoff }}'

          mkdir -p "package/$(dirname '${{ steps.shared.outputs.template_file }}')"

          with_backoff aws cloudformation package \
            --template-file '${{ steps.shared.outputs.template_file }}' \
            --s3-bucket '${{ steps.make_bucket.outputs.s3_bucket }}' \
            --output-template-file 'package/${{ steps.shared.outputs.template_file }}'

      - name: Estimate costs
        # seems buggy: estimate-template-cost doesn't know about LaunchTemplate(s)
        # (e.g.) An error occurred (ValidationError) when calling the EstimateTemplateCost operation: LaunchConfigurationName missing. It is a mandatory property of AutoScaling Group
        continue-on-error: true
        run: |
          aws cloudformation estimate-template-cost \
            --template-body 'file://package/${{ steps.shared.outputs.template_file }}' \
            ${{ steps.shared.outputs.kvparams || '' }}

      - name: Delete existing change set
        continue-on-error: true
        run: |
          source '${{ steps.functions.outputs.with_backoff }}'

          change_set_ids="$(with_backoff aws cloudformation list-change-sets \
            --stack-name '${{ matrix.stack }}' | jq -r '.Summaries[].ChangeSetId')"

          for id in ${change_set_ids}; do
              pr_tag="$(with_backoff aws cloudformation describe-change-set \
                --change-set-name "${id}" \
                --query Tags | jq -r '.[] | select(.Key=="github_pull_request").Value')"

              if [[ -n "$pr_tag" ]] && [[ "$pr_tag" == '${{ github.event.pull_request.number }}' ]]; then
                  with_backoff aws cloudformation delete-change-set --change-set-name "${id}"
              fi
          done

      - name: Generate change set
        id: change_set
        run: |
          source '${{ steps.functions.outputs.with_backoff }}'

          result="$(with_backoff aws cloudformation deploy \
            --stack-name '${{ steps.shared.outputs.stack_name }}' \
            --template-file 'package/${{ steps.shared.outputs.template_file }}' \
            --s3-bucket '${{ steps.make_bucket.outputs.s3_bucket }}' \
            --capabilities ${{ steps.shared.outputs.caps }} \
            --tags ${{ steps.shared.outputs.tags }} \
            --no-fail-on-empty-changeset \
            --no-execute-changeset \
            ${{ steps.shared.outputs.params || '' }})"

          if ! [[ "$result" =~ 'No changes to deploy' ]]; then
              cmd="${result#*:}"
              cmd="${cmd//$'\n'/}"
              echo "command=${cmd}" >> "${GITHUB_OUTPUT}"
          else
              echo '::notice::no changes'
          fi

      - name: Describe change set(s)
        if: steps.change_set.outputs.command != ''
        run: |
          result="$(${{ steps.change_set.outputs.command }})"
          if [[ -n "$result" ]]; then
              replace="$(echo "${result}" | jq -r '.Changes[].ResourceChange | select(.Replacement=="True")' | jq -rs '. | length')"
              destroy="$(echo "${result}" | jq -r '.Changes[].ResourceChange | select(.Action=="Remove")' | jq -rs '. | length')"
              if [[ $replace -gt 0 ]] || [[ $destroy -gt 0 ]]; then
                  echo '::warning::change set may destroy and/or replace existing resources'
              else
                  echo '::notice::change set may add or update resources'
              fi
              echo "${result}" | jq -r
          fi

  cloudformation_finalize:
    name: Finalize CloudFormation
    runs-on: ${{ fromJSON(inputs.cloudformation_runs_on || inputs.runs_on) }}
    strategy:
      fail-fast: false
      max-parallel: ${{ fromJSON(inputs.max_parallel) }}
      matrix:
        stack: ${{ fromJSON(needs.is_cloudformation.outputs.stacks) }}
        include: ${{ fromJSON(needs.is_cloudformation.outputs.includes) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - is_cloudformation
    if: |
      (github.event.pull_request.merged == true || github.event_name == 'push') &&
      needs.is_cloudformation.outputs.cloudformation == 'true' &&
      needs.is_cloudformation.outputs.stacks != '' &&
      needs.is_cloudformation.outputs.stacks != '[]'

    env:
      # https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-retries.html#cli-usage-retries-modes-adaptive
      AWS_RETRY_MODE: adaptive
      AWS_MAX_ATTEMPTS: 10
      AWS_REGION: ${{ matrix.region || inputs.aws_region }}
      AWS_DEFAULT_REGION: ${{ matrix.region || inputs.aws_region }}
      ATTEMPTS: 5
      TIMEOUT: 3

    environment: ${{ matrix.environment }}

    # The calling workflow must set these permissions to use these optional features.
    # permissions:
    #   id-token: write # AWS GitHub OIDC provider

    steps:
      - *setupAwsCli
      - *randomDelay
      - *configureAWSCredentials
      - *getAWSCallerIdentity
      - *waitForCloudFormation
      - *convenienceFunctions

      - name: Execute change set
        run: |
          source '${{ steps.functions.outputs.with_backoff }}'

          change_set_ids="$(with_backoff aws cloudformation list-change-sets \
            --stack-name '${{ matrix.stack }}' \
            | jq -r '.Summaries[] | select(.ExecutionStatus=="AVAILABLE").ChangeSetId')"

          for id in ${change_set_ids}; do
              pr_tag="$(with_backoff aws cloudformation describe-change-set \
                --change-set-name "${id}" \
                --query Tags | jq -r '.[] | select(.Key=="github_pull_request").Value')"

              if [[ -n "$pr_tag" ]] && [[ "$pr_tag" == '${{ github.event.pull_request.number }}' ]]; then
                  with_backoff aws cloudformation execute-change-set --change-set-name "${id}"
              fi
          done

      - *waitForCloudFormation

  all_tests:
    name: All tests
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    permissions: {}
    needs:
      - npm_test
      - docker_test
      - python_test
      - cargo_test
      - custom_test
      - cloudformation_test
      - actionlint
      - octoscan
    if: |
      always() &&
      github.event.pull_request.state == 'open'
    steps:
      - *rejectFailedJobs
      - *rejectCancelledJobs

  all_jobs:
    name: All jobs
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    permissions: {}
    needs:
      - event_types
      - versioned_source
      - is_npm
      - is_docker
      - is_python
      - is_cargo
      - is_balena
      - is_custom
      - all_tests
      - npm_sbom
      - python_sbom
      - cargo_sbom
      - npm_publish
      - docker_publish
      - balena_publish
      - python_publish
      - website_publish
      - github_publish
      - cargo_publish
      - custom_publish
      - custom_always
    # Run on event triggers for open PRs
    # OR when the PR is closed but not merged
    # See https://github.com/product-os/flowzone/issues/1143
    if: |
      always() &&
      (
        github.event.pull_request.state == 'open' ||
        (
          github.event.pull_request.state == 'closed' && github.event.pull_request.merged != true
        )
      )

    steps:
      # Avoid showing this job as skipped if a PR is reopened
      # See https://github.com/product-os/flowzone/issues/1143
      - name: Reject on closed pull requests
        if: github.event.pull_request.state == 'closed' && github.event.pull_request.merged != true
        run: |
          echo "::warning::Marking this job as failed so if the PR is reopened it does not satisfy merge requirements"
          exit 1
      - *rejectFailedJobs
      - *rejectCancelledJobs

  auto-merge:
    name: Auto-merge
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - all_jobs
    if: |
      !failure() && !cancelled() &&
      needs.all_jobs.result == 'success' &&
      github.event.pull_request.state == 'open' &&
      inputs.toggle_auto_merge == true &&
      github.event.pull_request.user.type != 'Bot'

    permissions: {}

    steps:
      - <<: *getGitHubAppToken
        with:
          <<: *getGitHubAppTokenWith
          # contents: write is required to enable automerge on a pull request
          permissions: >-
            {
              "contents": "write",
              "metadata": "read",
              "pull_requests": "read"
            }

      # Get the current state of the PR so we can check if it is in draft state
      - name: Get the PR state
        id: get-pr
        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
        with:
          result-encoding: json
          github-token: "${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}"
          script: |
            const { data } = await github.rest.pulls.get({
              owner: context.repo.owner,
              repo: context.repo.repo,
              pull_number: context.payload.pull_request.number
            });
            return data;

      # This prevents merging PRs that do not have any required
      # checks, in theory. In practice the rules may not contain
      # required status checks but the presence of any branch rule is good enough.
      # The fine-grained token must have the following permission set:
      # - "Metadata" repository permissions (read)
      # https://octokit.github.io/rest.js/v21/#repos-get-branch-rules
      # https://docs.github.com/en/rest/repos/rules#get-rules-for-a-branch
      - name: Check if branch has rules
        if: ${{ fromJSON(steps.get-pr.outputs.result).draft == false }}
        id: get-branch-rules
        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7
        with:
          result-encoding: json
          github-token: "${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}"
          script: |
            const { data } = await github.rest.repos.getBranchRules({
              owner: context.repo.owner,
              repo: context.repo.repo,
              branch: context.payload.pull_request.base.ref
            });
            return data;

      # Only toggle auto-merge if:
      # - there are one or more required status checks on the branch via rulesets
      # - and the PR is not in draft state
      - name: Toggle auto-merge
        if: ${{ fromJSON(steps.get-pr.outputs.result).draft == false && steps.get-branch-rules.outputs.result != '[]' }}
        env:
          <<: *gitHubCliEnvironment
          # DO NOT use the automatic github token (GITHUB_TOKEN) as it will not trigger merge events!
          GH_TOKEN: "${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}"
        # As long as we avoid the --admin flag, we should never bypass branch protections
        # See: https://cli.github.com/manual/gh_pr_merge
        run: |
          gh pr merge ${{ github.event.pull_request.number }} --merge --auto || true