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
    continue-on-error: true
    id: gh_app_token
    with: &getGitHubAppTokenWith
      app_id: ${{ inputs.app_id }}
      installation_retrieval_mode: id
      installation_retrieval_payload: ${{ inputs.installation_id }}
      private_key: ${{ secrets.GH_APP_PRIVATE_KEY }}
      # permissions: ${{ inputs.token_scope }}
      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@e3dd6a429d7300a6a4c196c26e071d42e0343502 # v4.0.2
    # 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}"

  - &deployToBalenaAction
    uses: balena-io/deploy-to-balena-action@e313ae39c21b7fd8502175a635b7417a6feaef7d # v2.0.81
    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 }}
      registry_secrets: |
        {
          "ghcr.io": {
            "username": "${{ github.actor }}",
            "password": "${{ secrets.GITHUB_TOKEN }}"
          },
          "docker.io": {
            "username": "${{ secrets.DOCKERHUB_USER }}",
            "password": "${{ secrets.DOCKERHUB_TOKEN }}"
          }
        }

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

  # https://docs.github.com/en/rest/git/tags?apiVersion=2022-11-28#create-a-tag-object
  - &createTagObject
    name: Create tag object
    if: inputs.disable_versioning != true
    id: create_tag
    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 }}
    run: |
      response="$(gh api -X POST repos/$GH_REPO/git/tags \
        -F "tag=${TAG}" \
        -F "message=${MESSAGE}" \
        -F "object=${SHA}" \
        -F "type=commit")"

      echo "$response" | jq .
      echo "sha=$(echo $response | jq -r .sha)" >> "${GITHUB_OUTPUT}"
      echo "json=$(echo $response | jq -c .)" >> "${GITHUB_OUTPUT}"

  # https://docs.github.com/en/rest/git/refs?apiVersion=2022-11-28#update-a-reference
  - &updateGitReference
    name: Update git reference
    if: github.event.pull_request.merged == true && steps.create_commit.outputs.sha != ''
    env:
      GH_TOKEN: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
      REF: "refs/heads/${{ github.base_ref }}"
      SHA: ${{ steps.create_commit.outputs.sha }}
    run: |
      gh api \
        -X PATCH \
        -H "Accept: application/vnd.github+json" \
        -H "X-GitHub-Api-Version: 2022-11-28" \
        "/repos/${{ github.repository }}/git/${REF}" \
        -f sha="${SHA}" \
        -F force=true \
        --include

  # https://docs.github.com/en/rest/git/refs?apiVersion=2022-11-28#create-a-reference
  - &createGitReference
    name: Create git reference
    if: github.event.pull_request.merged == true && 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 }}
    run: |
      gh api \
        -X POST \
        -H "Accept: application/vnd.github+json" \
        -H "X-GitHub-Api-Version: 2022-11-28" \
        /repos/$GH_REPO/git/refs \
        -f ref="${REF}" \
        -f sha="${SHA}" \
        --include

  - &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

  - &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=100" >> "${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 }}

  # Enabling fetch-tags via actions/checkout does not work when fetch-depth > 0
  # https://github.com/actions/checkout/issues/1781
  - &fetchTags
    name: Fetch tags
    if: needs.versioned_source.outputs.depth != 0 && needs.versioned_source.outputs.depth != ''
    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 -q --tags

  - &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:
      registry: ghcr.io
      username: ${{ github.actor }}
      # FIXME: as per GitHub support:
      # "You cannot authenticate with a GitHub App token on the GitHub Package Registry"
      # so this will fail for external PRs as the automatic actions token will be read-only
      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 }}"
    # default to automatic actions token
    GH_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

  - &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 array
    id: to_json_array
    shell: bash
    run: |
      set -x

      # Remove spaces and newlines from the input
      INPUT="$(echo "${INPUT}" | tr -d '[:space:]')"

      # Convert to JSON array using jq to split the string by the given delimiter
      # Add a step to check if the array is empty, default to [""] if so
      JSON_ARRAY="$(jq --raw-input --compact-output --null-input --arg delim "$DELIMITER" --arg input "$INPUT" '
        if $input == "" then
          [""] # Default to a single empty string element if input is empty
        else
          $input | split($delim) # Split the input by the delimiter
        end
      ')"

      echo "build=${JSON_ARRAY}" >> "${GITHUB_OUTPUT}"
      echo "json=${JSON_ARRAY}" >> "${GITHUB_OUTPUT}"

  - &newlineListBuilder
    name: Build newline-separated list from JSON array
    id: to_newline_list
    run: |
      build="$(echo "${{ join(fromJSON(env.INPUT),' ') }}" | tr " " "\n")"
      DELIMITER="$(echo $RANDOM | md5sum | head -c 32)"
      echo "build<<${DELIMITER}" >> "${GITHUB_OUTPUT}"
      echo "${build}" >> "${GITHUB_OUTPUT}"
      echo "${DELIMITER}" >> "${GITHUB_OUTPUT}"

  - &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
    id: strings
    env:
      TARGET: ${{ matrix.target }}
      IMAGE: ${{ matrix.image }}
    run: |
      target_slug="$(echo "${TARGET}" | sed 's/[^[:alnum:]]/-/g')"

      if [ -n "${TARGET}" ] && [ -z "${target_slug}" ]
      then
        echo "::error::Unsupported platform: ${TARGET}"
      fi

      if [ "${TARGET}" != "default" ]
      then
        if [ "${{ inputs.docker_invert_tags }}" = "true" ]
        then
          prefix_slug="${target_slug}-"
        else
          suffix_slug="-${target_slug}"
        fi
      fi

      case ${IMAGE} in
      '')
        image_slug=
        ;;
      *.*/*)
        # convert tl.d/org/repo(:tag)? to tl.d/org/repo
        image_slug="${IMAGE%%:*}"
        ;;
      *)
        # convert org/repo(:tag)? to docker.io/org/repo
        image_slug="docker.io/${IMAGE%%:*}"
        ;;
      esac

      # convert tl.d/org/repo to org/repo
      repo_slug="${image_slug#*/}"

      echo "image=${image_slug}" >> "${GITHUB_OUTPUT}"
      echo "target=${target_slug}" >> "${GITHUB_OUTPUT}"
      echo "prefix=${prefix_slug}" >> "${GITHUB_OUTPUT}"
      echo "suffix=${suffix_slug}" >> "${GITHUB_OUTPUT}"
      echo "repo=${repo_slug}" >> "${GITHUB_OUTPUT}"

  - &dockerTestMetadata # https://github.com/docker/metadata-action
    name: Generate docker metadata
    id: test_meta
    uses: docker/metadata-action@8e5442c4ef9f78752691e2d8f8d19755c6f78e81 # v5.5.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: join(fromJSON(needs.is_docker.outputs.docker_images)) != ''
    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

  - &setupBuildx # https://github.com/docker/setup-buildx-action
    name: Setup buildx
    id: setup_buildx
    uses: docker/setup-buildx-action@c47758b77c9736f4b2ef4073d4d51994fabfe349 # v3.7.1
    with:
      driver-opts: network=host
      install: true

  - &setupQemuBinfmt # https://github.com/docker/setup-qemu-action
    name: Setup QEMU
    id: qemu_binfmt
    uses: docker/setup-qemu-action@49b3bc8e6bdd4a60e6116a5414239cba5943d3cf # v3.2.0
    env:
      LOG_LEVEL: debug
      # renovate: datasource=docker depName=binfmt packageName=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@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
    with:
      node-version: 20.x

  - &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@e78f54a89cb052fff327414dd9ff010b5d2b4dbd # v3.0.1
    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@506c5b26faaa69e050009260f5f0c6755e7dd963 # v0.0.8
    with:
      version: "2.15.43"

  - &sortNodeVersions
    name: Sort node versions
    id: node_versions
    env:
      VERSIONS: ${{ needs.is_npm.outputs.node_versions }}
    run: |
      echo "min=$(echo "${VERSIONS}" | jq -r '.[]' | sort --version-sort | head -n1)" >> "${GITHUB_OUTPUT}"
      echo "max=$(echo "${VERSIONS}" | jq -r '.[]' | sort --version-sort --reverse | head -n1)" >> "${GITHUB_OUTPUT}"

  - &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@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.4.3

  - &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
        # https://github.com/organizations/product-os/settings/apps/flowzone-app
        # https://github.com/organizations/product-os/settings/variables/actions/APP_ID
        default: "${{ vars.APP_ID || '291899' }}"
      # not needed if installed on this current org/repo
      installation_id:
        description: "GitHub App installation id"
        type: string
        required: false
        # https://github.com/organizations/product-os/settings/installations
        # https://github.com/organizations/product-os/settings/variables/actions/INSTALLATION_ID
        default: "${{ vars.INSTALLATION_ID || '34040165' }}"
      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-22.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
# The following concurrency group cancels in-progress jobs or runs on pull_request events only;
# if github.head_ref is undefined, the concurrency group will fallback to the run ID,
# which is guaranteed to be both unique and defined for the run.
concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
  # 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-latest
    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:
      # Required to create comments on pull requests.
      pull-requests: write

    steps:
      - *rejectExternalPullRequest
      - *rejectInternalPullRequestTarget
      
      # 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
        timeout-minutes: 90
        uses: product-os/review-commit-action@cddebf4cec8e40ea8f698b6dcce8cd70e38b7320 # v0.1.7
        with:
          poll-interval: '10'
          allow-authors: false

      - *rejectMissingSecrets
      - *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

    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.bot }}
      tag_sha: ${{ steps.create_tag.outputs.sha }}
      # depth: ${{ steps.git_describe.outputs.depth || 0 }}
      # Force full fetch depth for now in order to retrieve tags (this takes longer).
      # https://github.com/actions/checkout/issues/1781
      depth: 0

    env:
      <<: *gitHubCliEnvironment

    steps:
      - <<: *getGitHubAppToken
        with:
          <<: *getGitHubAppTokenWith
          # admin permission is currently required to bypass branch protection rules
          permissions: >-
            {
              "administration": "write",
              "contents": "write",
              "metadata": "read",
              "pull_requests": "read"
            }

      # 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'

      # fail on merge commits (ones with more than one parent)
      - name: Reject merge commits
        if: github.event.pull_request.state == 'open'
        run: |
          if [ "$(git cat-file -p ${{ github.event.pull_request.head.sha || github.event.head_commit.id }} | grep -c '^parent ')" -gt 1 ]
          then
            echo "::error::Latest commit appears to be a merge, which is currently unsupported. Try a rebase instead."
            exit 1
          fi

      # 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/
      - name: Create blobs and tree objects
        if: inputs.disable_versioning != true
        id: create_tree
        shell: bash
        env:
          GH_TOKEN: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
          PARENT_COMMIT_SHA: ${{ steps.git_describe.outputs.sha }}
        run: |
          # Temporary array to hold our new tree objects
          declare -a tree_array

          # Use git status to check for new and modified files
          modified_files="$(git diff --name-only ; git ls-files --others --exclude-standard)"

          # Extract changes
          for file in $modified_files; do

            echo "Creating blob of file $file..."
            base64 -w0 "$file" > content.base64
            response="$(gh api -X POST "/repos/$GH_REPO/git/blobs" \
              -F 'content=@content.base64' \
              -F 'encoding=base64')"
            rm content.base64

            echo "$response" | jq .
            blob_sha="$(echo "$response" | jq -r .sha)"

            # Add blob to our tree
            tree_array+=("{\"path\":\"$file\",\"mode\":\"100644\",\"type\":\"blob\",\"sha\":\"$blob_sha\"}")
          done

          # Get the SHA of the tree the parent commit points to
          base_tree_sha="$(git show -s --format=%T "$PARENT_COMMIT_SHA")"

          # Create JSON array for tree creation
          tree_json="$(printf ",%s" "${tree_array[@]}")"
          tree_json="${tree_json:1}"
          tree_json="[$tree_json]"
          tree_json="{\"tree\": $tree_json, \"base_tree\": \"$base_tree_sha\"}"

          echo "Creating tree..."
          echo "$tree_json" | jq .

          response="$(echo "$tree_json" | gh api -X POST "/repos/$GH_REPO/git/trees" --input -)"

          echo "$response" | jq .
          echo "sha=$(echo "$response" | jq -r .sha)" >> "${GITHUB_OUTPUT}"
          echo "json=$(echo "$response" | jq -c .)" >> "${GITHUB_OUTPUT}"

      # https://docs.github.com/en/rest/git/commits?apiVersion=2022-11-28#create-a-commit
      - name: Create commit object
        if: inputs.disable_versioning != true
        id: create_commit
        env:
          GH_TOKEN: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
          MESSAGE: ${{ steps.versionist.outputs.tag }}
          PARENT_COMMIT_SHA: ${{ steps.git_describe.outputs.sha }}
        run: |
          response="$(gh api -X POST "/repos/$GH_REPO/git/commits" \
            -F "message=$MESSAGE" \
            -F "tree=${{ steps.create_tree.outputs.sha }}" \
            -F "parents[]=$PARENT_COMMIT_SHA")"

          echo "$response" | jq .
          {
            echo "sha=$(echo "$response" | jq -r .sha)" >> "${GITHUB_OUTPUT}" ;
            echo "json=$(echo "$response" | jq -c .)" >> "${GITHUB_OUTPUT}" ;
            echo "bot=$(echo "$response" | jq -r .author.name | sed 's/\[bot\]//g')" ;
          } >> "${GITHUB_OUTPUT}"

      # create a new tag object
      - <<: *createTagObject
        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
        env:
          GH_TOKEN: ${{ steps.gh_app_token.outputs.token || secrets.FLOWZONE_TOKEN }}
          REF: "refs/heads/${{ github.base_ref }}"
          SHA: ${{ steps.create_commit.outputs.sha }}

      # create a new tag name reference(pointer) to the new tag object sha
      - <<: *createGitReference
        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
    if: |
      (
        github.event.action != 'closed' ||
        github.event.pull_request.merged == true
      )

    <<: *rootWorkingDirectory

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

    env:
      <<: *gitHubCliEnvironment

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

      # 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:
          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]\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

      - *checkoutVersionedSha
      - *fetchTags
      - *createLocalRefs

      - name: Generate short release note
        id: short_release_notes
        # Look back should always be 2
        # First is the current versioned tag
        # Second is the previous versioned tag
        env:
          look_back: 2
          user_defined: ${{ steps.format_release_notes.outputs.body }}
        run: |
          set -ea
          # prevent git from existing with 141
          set +o pipefail

          previous_tag="$(git --no-pager tag --list --sort=-version:refname "v*.*.*" --merged | head -n${look_back} | tail -n1)"

          changelog="$(git log ${previous_tag}..${{ github.event.pull_request.head.sha || github.event.head_commit.id }} --pretty=reference)"
          release_notes="${changelog}"
          if [[ -n "${user_defined}" ]]; then
            release_notes="$(printf '%s\n\n### List of commits\n\n%s' "${user_defined}" "${changelog}")"
          fi

          EOF="$(openssl rand -hex 16)"
          echo "note<<$EOF" >> "${GITHUB_OUTPUT}"
          echo "${release_notes}" >> "${GITHUB_OUTPUT}"
          echo "$EOF" >> "${GITHUB_OUTPUT}"

          echo "${release_notes}" > "${{ runner.temp }}/release-notes.txt"

      # https://github.com/actions/upload-artifact
      - name: Upload release notes file
        uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.4.3
        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: |
      (
        github.event.action != 'closed' ||
        github.event.pull_request.merged == true
      ) &&
      inputs.release_notes == true

    <<: *rootWorkingDirectory

    env:
      <<: *gitHubCliEnvironment

    steps:
      - <<: *getGitHubAppToken
        with:
          <<: *getGitHubAppTokenWith
          permissions: >-
            {
              "contents": "write",
              "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\]'
          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 == true &&
          needs.versioned_source.outputs.commit_sha != ''

      # required by https://github.com/balena-io-modules/balena-deploy-request
      - <<: *createTagObject
        if: |
          github.event.pull_request.merged == true &&
          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 == true &&
          steps.create_tag.outputs.sha != ''
        env:
          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

  lint_workflows:
    name: Lint workflows
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - versioned_source

    <<: *customWorkingDirectory

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha

      # 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.4
        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:"

  # check if the repository has a package.json file and which engine versions are supported
  is_npm:
    name: Is npm
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - versioned_source

    <<: *customWorkingDirectory

    outputs:
      npm: ${{ steps.npm.outputs.enabled }}
      has_npm_lockfile: ${{ steps.npm_lock.outputs.has_npm_lockfile }}
      npm_private: ${{ steps.npm.outputs.private }} # can be null or unset
      npm_docs: ${{ steps.npm.outputs.docs }} # can be null or unset
      npm_sbom: ${{ inputs.generate_sbom }} # default true
      node_versions: ${{ steps.node_versions.outputs.json }}
      npm_access: ${{ steps.access.outputs.access }}

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha

      - name: Check for package.json
        id: npm
        run: |
          if test -f "package.json"
          then
            echo "found package.json"
            echo "enabled=true" >> "${GITHUB_OUTPUT}"
            echo "private=$(jq -r '.private' package.json)" >> "${GITHUB_OUTPUT}"
            echo "docs=$(jq -r '.scripts | has("doc")' package.json)" >> "${GITHUB_OUTPUT}"
            echo "NODE_VERSIONS=[]" >> "${GITHUB_ENV}"
          else
            echo "enabled=false" >> "${GITHUB_OUTPUT}"
          fi

      - name: Check for package locks
        id: npm_lock
        run: |
          has_npm_lockfile="$([ -e package-lock.json ] || [ -e npm-shrinkwrap.json ] && echo true || echo false)"
          echo "has_npm_lockfile=${has_npm_lockfile}" >> "${GITHUB_OUTPUT}"

      - name: Set access
        id: access
        run: |
          access="public"
          if [ "${{ github.event.repository.private }}" = "true" ]
          then
            access="restricted"
          fi
          echo "access=${access}" >> "${GITHUB_OUTPUT}"

      # 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
        if: steps.npm.outputs.enabled == 'true'
        with:
          node-version: 18.x

      - name: Check engine
        if: steps.npm.outputs.enabled == 'true'
        run: |
          if npx -q -y -- check-engine
          then
            echo "NODE_VERSIONS=$(echo "${NODE_VERSIONS}" | jq -c '. + ["18.x"]')" >> "${GITHUB_ENV}"
          fi

      - <<: *setupNode
        if: steps.npm.outputs.enabled == 'true'
        with:
          node-version: 20.x

      - name: Check engine
        if: steps.npm.outputs.enabled == 'true'
        run: |
          if npx -q -y -- check-engine
          then
            echo "NODE_VERSIONS=$(echo "${NODE_VERSIONS}" | jq -c '. + ["20.x"]')" >> "${GITHUB_ENV}"
          fi

      - <<: *setupNode
        if: steps.npm.outputs.enabled == 'true'
        with:
          node-version: 22.x

      - name: Check engine
        if: steps.npm.outputs.enabled == 'true'
        run: |
          if npx -q -y -- check-engine
          then
            echo "NODE_VERSIONS=$(echo "${NODE_VERSIONS}" | jq -c '. + ["22.x"]')" >> "${GITHUB_ENV}"
          fi

      # default to the current LTS version if none were matched
      # by the engine checks above
      - name: Set Node.js versions
        if: steps.npm.outputs.enabled == 'true'
        id: node_versions
        run: |
          echo "json=[\"20.x\"]" >> "${GITHUB_OUTPUT}"
          if [ "${NODE_VERSIONS}" != "[]" ]
          then
            echo "json=${NODE_VERSIONS}" >> "${GITHUB_OUTPUT}"
          fi

  # pre-process any docker-compose and docker-bake files
  is_docker:
    name: Is docker
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - versioned_source

    <<: *customWorkingDirectory

    outputs:
      docker_images: ${{ steps.docker_images_json.outputs.build }}
      docker_images_crlf: ${{ steps.docker_images_crlf.outputs.build }}
      docker_compose_tests: ${{ steps.docker_compose_tests.outputs.found }}
      bake_targets: ${{ steps.bake_targets_json.outputs.build }}
      docker_bake_json: ${{ steps.docker_bake.outputs.json }}
      docker_test_matrix: ${{ steps.docker_test.outputs.build }}
      docker_publish_matrix: ${{ steps.docker_publish.outputs.build }}

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha

      - id: docker_images_json
        <<: *jsonArrayBuilder
        env:
          INPUT: ${{ inputs.docker_images }}
          DELIMITER: ","

      - id: docker_images_crlf
        <<: *newlineListBuilder
        env:
          INPUT: ${{ steps.docker_images_json.outputs.build }}

      - id: bake_targets_json
        <<: *jsonArrayBuilder
        env:
          INPUT: ${{ inputs.bake_targets }}
          DELIMITER: ","

      - name: Check for docker compose test files
        id: docker_compose_tests
        run: |
          if [ -n "$(ls docker-compose.test.{yml,yaml} 2>/dev/null)" ]
          then
            echo "found=true" >> "${GITHUB_OUTPUT}"
          else
            echo "found=false" >> "${GITHUB_OUTPUT}"
          fi

      - <<: *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
        if: |
          join(fromJSON(steps.docker_images_json.outputs.build)) != '' ||
          steps.docker_compose_tests.outputs.found == 'true'
        env:
          BAKE_FILE: /tmp/docker-bake.json
        run: |
          if [ -n "$(ls docker-bake{.override,}.{json,hcl} 2>/dev/null)" ]
          then
            files="$(echo "$(ls -1 docker-bake{.override,}.{json,hcl} 2>/dev/null)" | sed 's/ / -f /')"
          else
            echo '${{ steps.bake_targets_json.outputs.build }}' | jq -s '{target: (map({(.[]):{}}))}' > ${BAKE_FILE}
            files="${BAKE_FILE}"
          fi

          # log merged files and targets
          docker buildx bake --print ${{ join(fromJSON(steps.bake_targets_json.outputs.build),' ') }} -f ${files}

          json="$(docker buildx bake --print ${{ join(fromJSON(steps.bake_targets_json.outputs.build),' ') }} -f ${files} \
            | jq -cr '
              .target |= map_values(."inherits" += ["docker-metadata-action"]) |
              .target |= map_values(."platforms" //= ["linux/amd64"]) |
              del(.group."default") |
              if .group == {} then del(.group) else . end
            ')"

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

      # generate a test matrix with this structure
      # {
      #   "include": [
      #     {
      #       "target": "default",
      #       "platform": "linux/amd64",
      #       "runs_on": ["ubuntu-22.04"],
      #       "platform_slug": "amd64",
      #       "target_slug": "default"
      #     },
      #     {
      #       "target": "multiarch",
      #       "platform": "linux/amd64",
      #       "runs_on": ["ubuntu-22.04"],
      #       "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", "X64"],
      #       "platform_slug": "arm32v6",
      #       "target_slug": "multiarch",
      #       "tag_suffix": "-multiarch"
      #     }
      #   ]
      # }
      - name: Build docker test matrix
        id: docker_test
        if: steps.docker_bake.outputs.json != ''
        env:
          <<: *dockerPlatformSlugMap
          BAKE_JSON: "${{ steps.docker_bake.outputs.json }}"
          RUNS_ON: "${{ inputs.runs_on }}"
          DOCKER_RUNS_ON: "${{ inputs.docker_runs_on }}"
        run: |
          matrix="$(jq -cr '.target | to_entries |
            {include: map(.value.platforms[] as $p |
            {target: .key, platform: $p}
          )}' <<< "${BAKE_JSON}")"

          matrix="$(jq -cr --argjson in "$DOCKER_RUNS_ON" --argjson default "$RUNS_ON" '.include |=
            map(.platform as $p |
            .runs_on = if ($in | has($p)) then $in[$p] else $default end)' <<< "${matrix}")"

          matrix="$(jq -cr --argjson in "$PLATFORM_SLUG_MAP" '.include |=
            map(.platform as $p |
            .platform_slug = if ($in | has($p)) then $in[$p] else error("Unsupported platform: \($p)") end)' <<< "${matrix}")"

          matrix="$(jq -cr '.include[] |= . + {"target_slug": (.target | gsub("[^[:alnum:]]"; "-"))}' <<< "${matrix}")"

          if [ "${{ inputs.docker_invert_tags }}" = "true" ]
          then
            matrix="$(jq -cr '.include[] |= (if .target != "default" then .tag_prefix = .target + "-" else . end)'  <<< "${matrix}")"
          else
            matrix="$(jq -cr '.include[] |= (if .target != "default" then .tag_suffix = "-" + .target else . end)'  <<< "${matrix}")"
          fi

          echo "build=${matrix}">> "${GITHUB_OUTPUT}"

      # 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
        env:
          <<: *dockerPlatformSlugMap
          BAKE_JSON: "${{ steps.docker_bake.outputs.json }}"
        if: |
          join(fromJSON(steps.docker_images_json.outputs.build)) != '' && join(fromJSON(steps.bake_targets_json.outputs.build)) != ''
        run: |
          matrix="$(jq -ncr \
            --argjson images '${{ steps.docker_images_json.outputs.build }}' \
            --argjson targets '${{ steps.bake_targets_json.outputs.build }}' \
            '{include: [([$images, $targets] | combinations | {image: .[0], target: .[1]})]}')"

          matrix="$(jq -cr '.include[] |= . + {"target_slug": (.target | gsub("[^[:alnum:]]"; "-"))}' <<< "${matrix}")"

          matrix="$(jq -cr --argjson in "$BAKE_JSON" --argjson slugs "$PLATFORM_SLUG_MAP" '.include |=
            map(.target as $t |
            .platform_slugs = if ($in.target | has($t)) then ($in.target[$t].platforms | map($slugs[.]) | join(" "))
            else error("Unsupported target: \($t)") end)' <<< "${matrix}")"

          echo "build=${matrix}">> "${GITHUB_OUTPUT}"

  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

    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

    outputs:
      cargo_targets: ${{ steps.cargo_targets.outputs.build }}
      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 }}
          DELIMITER: ","

      - 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

    outputs:
      balena_slugs: ${{ steps.balena_slugs.outputs.build }}
      balena_yml: ${{ steps.balena_yml.outputs.enabled }}

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha

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

      - name: Check for balena.yml
        id: balena_yml
        run: |
          if test -f balena.yml
          then
            echo "found balena.yml"
            echo "enabled=true" >> "${GITHUB_OUTPUT}"
          else
            echo "enabled=false" >> "${GITHUB_OUTPUT}"
          fi

  # 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

    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 }}
          DELIMITER: ","

      # 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.json != ''
        env:
          MATRIX: >
            {
              "value": ${{ steps.custom_test_values.outputs.json }},
              "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 }}
          DELIMITER: ","

      # FIXME: remove this handling of deprecated comma-separated values
      - <<: *customValuesInput
        id: custom_publish_matrix
        if: steps.custom_publish_values.outputs.json != ''
        env:
          MATRIX: >
            {
              "value": ${{ steps.custom_publish_values.outputs.json }},
              "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 }}
          DELIMITER: ","

      # FIXME: remove this handling of deprecated comma-separated values
      - <<: *customValuesInput
        id: custom_finalize_matrix
        if: steps.custom_finalize_values.outputs.json != ''
        env:
          MATRIX: >
            {
              "value": ${{ steps.custom_finalize_values.outputs.json }},
              "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_website:
    name: Is website
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - versioned_source
    if: inputs.cloudflare_website != ''

    <<: *customWorkingDirectory

    outputs:
      has_readme: ${{ steps.has_readme.outputs.enabled }}

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha

      # Check if we have at least a README to build a website from
      - name: Check for README for building a website
        id: has_readme
        run: |
          if test -e "README.md"
          then
            echo "found README.md"
            echo "enabled=true" >> "${GITHUB_OUTPUT}"
          else
            echo "enabled=false" >> "${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

    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

    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
      - *sortNodeVersions

      - <<: *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' && steps.node_versions.outputs.max == 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

      - name: Upload artifact
        if: needs.is_npm.outputs.npm_private != 'true' && steps.node_versions.outputs.max == matrix.node_version
        uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.4.3
        with:
          name: npm-${{ github.event.pull_request.head.sha }}-${{ matrix.node_version }}
          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' && steps.node_versions.outputs.max == matrix.node_version
        run: tar --auto-compress -cvf ${{ runner.temp }}/docs.tar.zst ./docs

      - name: Upload artifact
        if: needs.is_npm.outputs.npm_docs == 'true' && steps.node_versions.outputs.max == matrix.node_version
        uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.4.3
        with:
          name: docs-${{ github.event.pull_request.head.sha }}-${{ matrix.node_version }}
          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
    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

    steps:
      - *sortNodeVersions

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

      - <<: *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: "18"
          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

    steps:
      - *getGitHubAppToken
      - *sortNodeVersions

      # 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
          name: npm-${{ github.event.pull_request.head.sha }}-${{ steps.node_versions.outputs.max }}

      - <<: *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: "18"
          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

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

      - *sortNodeVersions

      # 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
          name: docs-${{ github.event.pull_request.head.sha }}-${{ steps.node_versions.outputs.max }}

      - 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"

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

      - <<: *setupBuildx

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

      # only register qemu binfmt if the target platform is not supported by the host natively
      - <<: *setupQemuBinfmt
        if: contains(steps.native_platforms.outputs.build, 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@2e3d19baedb14545e5d41222653874f25d5b4dfb # v5.10.0
        with:
          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: join(fromJSON(needs.is_docker.outputs.docker_images)) != ''
        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(matrix.runs_on,'ubuntu-latest') || contains(matrix.runs_on,'ubuntu-22.04')
        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: join(fromJSON(needs.is_docker.outputs.docker_images)) != ''
        uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.4.3
        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' &&
      join(fromJSON(needs.is_docker.outputs.docker_images)) != ''

    <<: *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

    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') &&
      join(fromJSON(needs.is_docker.outputs.docker_images)) != ''

    <<: *rootWorkingDirectory

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

    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.pull_request.state == 'open'

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

    <<: *customWorkingDirectory

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha
      - *deployToBalenaAction

  balena_finalize:
    name: Finalize balena
    runs-on: ${{ fromJSON(inputs.runs_on) }}
    timeout-minutes: ${{ fromJSON(inputs.jobs_timeout_minutes) }}
    needs:
      - is_balena
      - versioned_source
      - release_notes
    if: |
      github.event.pull_request.merged == true || github.event_name == 'push'

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

    <<: *customWorkingDirectory

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha
      - *deployToBalenaAction

  ###################################################
  ## 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

    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

    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

    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
    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:
      - is_website
      - 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() &&
      (github.event.action != 'closed' || github.event.pull_request.merged == true) &&
      needs.is_website.result == 'success'

    steps:
      - *getGitHubAppToken
      - *checkoutVersionedSha
      - *createLocalRefs

      - <<: *setupNode
        with:
          node-version: 18

      - name: Docusaurus Builder
        if: |
          needs.is_website.outputs.has_readme == 'true' &&
          inputs.docusaurus_website != false
        uses: product-os/docusaurus-builder@b0ffeb2b2dd2b0f733747aac14103a95b51ac2c5 # v2.1.22
        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@e998fe3d9a589b7a05d3ca40c0c74cb7435e2ceb # v3.12.0
        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

      - 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
          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
    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'

    <<: *rootWorkingDirectory

    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@e7a8f85e1c67a31e6ed99a94b41bd0b71bbee6b8 # v2.0.9
        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

    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

    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

    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

    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@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # v4.4.3
        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

    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'

    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'

    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'

    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'

    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'

    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 }}

    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 }}

    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) }}
    needs:
      - npm_test
      - docker_test
      - python_test
      - cargo_test
      - custom_test
      - cloudformation_test
      - lint_workflows
    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) }}
    needs:
      - event_types
      - versioned_source
      - is_npm
      - is_docker
      - is_python
      - is_cargo
      - is_balena
      - is_custom
      - is_website
      - 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:
      pull-requests: read

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

      # Check if the PR is currently in draft state.
      # We aren't using the existing github context values here as those
      # are not updated on re-runs, or mid-execution.
      - name: Check if PR is draft
        id: is_draft_pr
        env:
          <<: *gitHubCliEnvironment
        run: |
          result="$(gh pr view ${{ github.event.pull_request.number }} --json isDraft | jq '.isDraft == true')"
          echo "result=${result}" >> "${GITHUB_OUTPUT}"

      # 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.
      # https://docs.github.com/en/rest/repos/rules?apiVersion=2022-11-28#get-rules-for-a-branch
      # The fine-grained token must have the following permission set:
      # - "Metadata" repository permissions (read)
      - name: Check if branch has rules
        if: steps.is_draft_pr.outputs.result == 'false'
        id: branch_has_rules
        env:
          <<: *gitHubCliEnvironment
        run: |
          result="$(gh api -H "Accept: application/vnd.github+json" \
            "/repos/${{ github.repository }}/rules/branches/${{ github.base_ref }}" | jq 'length != 0')"
          echo "result=${result}" >> "${GITHUB_OUTPUT}"

      # 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: steps.is_draft_pr.outputs.result == 'false' && steps.branch_has_rules.outputs.result == 'true'
        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