client-report-workflow.yaml

name: Report GitHub Actions Workflow

# This workflow is meant to be called from other repositories' workflows to report info about the workflow to
# Sherlock.
#
# The caller repository must have Workload Identity Federation configured to allow impersonation of the
# "gha-iap-accessor@dsp-devops-super-prod.iam.gserviceaccount.com" service account; steps 1 and 2 of the documentation:
# https://docs.google.com/document/d/1bnhDmWQHAMat_Saoa_z28FHwXmGWw6kywjdbKf208h4/edit
#
# With that configured, here's an example of how you can call this workflow (all fields optional and many more available):
# ```yaml
# jobs:
#
#   report-workflow:
#     uses: broadinstitute/sherlock/.github/workflows/client-report-workflow.yaml@main
#     with:
#       relates-to-chart-releases: leonardo-dev
#       notify-slack-channels-upon-workflow-completion: "#workbench-resilience-dev"
#       notify-slack-custom-icon: ":terra:"
#     permissions:
#       id-token: write
# ```
#
# The Slack notifications will link to the job and will reference chart releases or environments that the workflow is
# specified as relating to.

on:
  workflow_call:
    inputs:

      # Slack notifications
      #   Setting these inputs tells Sherlock to send Slack notifications (from @Beehive) when the workflow
      #   eventually completes. You can specify these at any point in your workflow (doesn't have to be at
      #   the end); Sherlock will automatically wait for completion before sending notifications.

      notify-slack-channels-upon-workflow-completion:
        required: false
        type: string
        description: |
          Slack channels that Beehive should notify when this workflow completes, regardless of outcome.
          
          Multiple slack channels can be provided by separating them with whitespace and/or commas.

      notify-slack-channels-upon-workflow-success:
        required: false
        type: string
        description: |
          Slack channels that Beehive should notify when this workflow succeeds.
          
          Multiple slack channels can be provided by separating them with whitespace and/or commas.

      notify-slack-channels-upon-workflow-failure:
        required: false
        type: string
        description: |
          Slack channels that Beehive should notify when this workflow fails.
          
          Multiple slack channels can be provided by separating them with whitespace and/or commas.

      notify-slack-channels-upon-workflow-retry:
        required: false
        type: string
        description: |
          Slack channels that Beehive should notify when this workflow completes on a retry, regardless
          of outcome.
          
          Channels provided here will be deduplicated with any channels specified for completion,
          success, or failure (when necessary).
          
          Multiple slack channels can be provided by separating them with whitespace and/or commas.

      notify-slack-custom-icon:
        required: false
        type: string
        description: |
          A custom icon to use for any of the above Slack notifications. Can be given either as a
          public image URL or as a Slack emoji in colon-shortcode format (e.g. ":smiley:").
          
          If not provided, Beehive's icon will be used.

      #
      # Workflow relations
      #   These inputs tell Sherlock that this workflow was related to particular resources.
      #   This is what will make this workflow show up in the workflow lists visible in
      #   Beehive when you look at an environment, chart instance, etc.
      #
      relates-to-app-versions:
        required: false
        type: string
        description: |
          App versions related to or affected by the calling workflow.
          The app versions must have already been reported to Sherlock (or ignore-bad-selectors should be true).
          
          App versions should be specified by an app version selector. Some different examples:
            - <id-integer> (`456`)
            - <chart-selector>/<version-string> (`leonardo/v1.2.3`)
          Multiple app versions can be reported by separating them with whitespace and/or commas.
      relates-to-chart-versions:
        required: false
        type: string
        description: |
          Chart versions related to or affected by the calling workflow.
          The chart versions must have already been reported to Sherlock (or ignore-bad-selectors should be true).
          
          Chart versions should be specified by a chart version selector. Some different examples:
            - <id-integer> (`456`)
            - <chart-selector>/<version-string> (`leonardo/v1.2.3`)
          Multiple chart versions can be reported by separating them with whitespace and/or commas.
      relates-to-chart-releases:
        required: false
        type: string
        description: |
          Chart releases (chart instances) related to or affected by the calling workflow.
          The chart releases must already exist in Sherlock (or ignore-bad-selectors should be true).
          
          Relating to a chart release will automatically also be recorded as relating to the chart
          release's Kubernetes cluster and/or environment, where applicable. Don't directly specify
          them too unless you also want the workflow to be related to everything else inside them.
          
          Chart releases should be specified by a chart release selector. Some different examples:
            - <id-integer> (`456`)
            - <name-string> (`leonardo-dev`)
            - <environment-selector>/<chart-selector> (`dev/leonardo`)
            - <cluster-selector>/<namespace-string>/<chart-selector> (`terra-dev/terra-dev/leonardo`)
          Multiple chart releases can be reported by separating them with whitespace and/or commas.
      relates-to-environments:
        required: false
        type: string
        description: |
          Environments related to or affected by the calling workflow.
          The environments must already exist in Sherlock (or ignore-bad-selectors should be true).
          
          Relating to an environment will automatically also be recorded as relating to all the chart
          releases it contains.
          
          Environments should be specified by an environment selector. Some different examples:
            - <id-integer> (`456`)
            - <name-string> (`dev`)
            - resource-prefix/<unique-resource-prefix-string> (`resource-prefix/z123`)
          Multiple environments can be reported by separating them with whitespace and/or commas.
      relates-to-clusters:
        required: false
        type: string
        description: |
          Kubernetes clusters related to or affected by the calling workflow.
          The clusters must already exist in Sherlock (or ignore-bad-selectors should be true).
          
          Relating to a cluster will automatically also be recorded as relating to all the chart
          releases it contains.
          
          Clusters should be specified by a cluster selector. Some different examples:
            - <id-integer> (`456`)
            - <name-string> (`terra-dev`)
          Multiple clusters can be reported by separating them with whitespace and/or commas.
      relates-to-charts:
        required: false
        type: string
        description: |
          Helm Charts related to or affected by the calling workflow.
          The charts must already exist in Sherlock (or ignore-bad-selectors should be true).
          
          Charts should be specified by a chart selector. Some different examples:
            - <id-integer> (`456`)
            - <name-string> (`leonardo`)
          Multiple charts can be reported by separating them with whitespace and/or commas.
      relates-to-changesets:
        required: false
        type: string
        description: |
          Changesets (chart release version change) related to or used by the calling workflow.
          The changesets must already exist in Sherlock (or ignore-bad-selectors should be true).
          
          Relating to a changeset will automatically also be recorded as relating to the chart release it
          affects, which will in turn also be recorded as relating to that chart release's environment
          and/or cluster.
          
          Additionally, relating to a changeset can also automatically create relations with any new app
          or chart versions introduced by that changeset. This behavior is controlled by the
          relate-to-changeset-new-versions field.
          
          Changesets must be specified by their integer ID (`456`), there aren't other selectors available.
          Multiple changesets can be reported by separating them with whitespace and/or commas.
      relate-to-changeset-new-versions:
        required: false
        type: string
        description: |
          This field controls whether a changeset relation should also automatically create relations with
          any new app or chart versions introduced by the changeset.
          
          This field has three possible values: "always", "when-static", and "never". "when-static" is the
          default.
          - "always" means that those version relations should always be created
          - "when-static" means that those version relations should only be created when the changeset's
            target chart release is in a static environment, like dev or prod
          - "never" means that those version relations should never be created
        default: when-static
      ignore-bad-selectors:
        required: false
        type: boolean
        description: |
          This field controls whether errors handling the selector fields should be returned as actual errors
          or just ignored. This is useful when you don't know whether the input will actually exist in Sherlock
          and you'd rather this step still succeed if it doesn't.

env:
  SHERLOCK_PROD_URL: "https://sherlock.dsp-devops-prod.broadinstitute.org"

jobs:
  report-workflow-relations:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
    steps:
      - name: "Parse Inputs"
        id: parse
        uses: actions/github-script@v7
        env:
          SLACK_CHANNELS_UPON_COMPLETION: ${{ inputs.notify-slack-channels-upon-workflow-completion }}
          SLACK_CHANNELS_UPON_SUCCESS: ${{ inputs.notify-slack-channels-upon-workflow-success }}
          SLACK_CHANNELS_UPON_FAILURE: ${{ inputs.notify-slack-channels-upon-workflow-failure }}
          SLACK_CHANNELS_UPON_RETRY: ${{ inputs.notify-slack-channels-upon-workflow-retry }}
          APP_VERSIONS: ${{ inputs.relates-to-app-versions }}
          CHART_VERSIONS: ${{ inputs.relates-to-chart-versions }}
          CHART_RELEASES: ${{ inputs.relates-to-chart-releases }}
          ENVIRONMENTS: ${{ inputs.relates-to-environments }}
          CLUSTERS: ${{ inputs.relates-to-clusters }}
          CHARTS: ${{ inputs.relates-to-charts }}
          CHANGESETS: ${{ inputs.relates-to-changesets }}
        with:
          # Bash action steps are usually easier to work with, but here it's easier to assemble this JSON object
          # in JS rather than doing lots of string work with Bash.
          script: |
            core.setOutput("body", JSON.stringify({
              // Split on commas/whitespace and filter to non-empty values
              notifySlackChannelsUponSuccess: [
                ...process.env.SLACK_CHANNELS_UPON_COMPLETION.split(/[\s,]+/),
                ...process.env.SLACK_CHANNELS_UPON_SUCCESS.split(/[\s,]+/)
              ].filter(Boolean),
              notifySlackChannelsUponFailure: [
                ...process.env.SLACK_CHANNELS_UPON_COMPLETION.split(/[\s,]+/),
                ...process.env.SLACK_CHANNELS_UPON_FAILURE.split(/[\s,]+/)
              ].filter(Boolean),
              notifySlackChannelsUponRetry: [
                // We don't need to worry about _UPON_COMPLETION here because it's already in the other two
                ...process.env.SLACK_CHANNELS_UPON_RETRY.split(/[\s,]+/)
              ].filter(Boolean),
              appVersions: process.env.APP_VERSIONS.split(/[\s,]+/).filter(Boolean),
              chartVersions: process.env.CHART_VERSIONS.split(/[\s,]+/).filter(Boolean),
              chartReleases: process.env.CHART_RELEASES.split(/[\s,]+/).filter(Boolean),
              environments: process.env.ENVIRONMENTS.split(/[\s,]+/).filter(Boolean),
              clusters: process.env.CLUSTERS.split(/[\s,]+/).filter(Boolean),
              charts: process.env.CHARTS.split(/[\s,]+/).filter(Boolean),
              changesets: process.env.CHANGESETS.split(/[\s,]+/).filter(Boolean),

              notifySlackCustomIcon: "${{ inputs.notify-slack-custom-icon }}",
              relateToChangesetNewVersions: "${{ inputs.relate-to-changeset-new-versions }}",
              ignoreBadSelectors: ${{ inputs.ignore-bad-selectors }},

              platform: "github-actions",
              githubActionsAttemptNumber: ${{ github.run_attempt }},
              githubActionsOwner: "${{ github.repository }}".split("/")[0],
              githubActionsRepo: "${{ github.repository }}".split("/")[1],
              githubActionsRunID: ${{ github.run_id }},
              // Path is prefixed by "<owner>/<repo>/" and suffixed by "@<ref>" so strip those
              githubActionsWorkflowPath: "${{ github.workflow_ref }}".slice("${{ github.repository }}".length+1).split("@")[0]
            }))

      - name: "Write Request Body"
        shell: bash
        run: |
          echo '${{ steps.parse.outputs.body }}' | jq > "$RUNNER_TEMP/body.json"

      - name: "Log Request Body"
        shell: bash
        run: |
          cat "$RUNNER_TEMP/body.json"

      - name: "Authenticate to GCP"
        id: iap_auth
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: "projects/1038484894585/locations/global/workloadIdentityPools/github-wi-pool/providers/github-wi-provider"
          service_account: "gha-iap-accessor@dsp-devops-super-prod.iam.gserviceaccount.com"
          token_format: "id_token"
          id_token_audience: "257801540345-1gqi6qi66bjbssbv01horu9243el2r8b.apps.googleusercontent.com"
          id_token_include_email: true
          create_credentials_file: false
          export_environment_variables: false

      - name: "Generate GHA OIDC Token"
        id: gha_auth
        uses: actions/github-script@v7
        with:
          script: core.setOutput("id_token", await core.getIDToken())

      - name: "Send to Sherlock"
        shell: bash
        run: |
          set -ex
          curl --fail-with-body -X 'PUT' \
            "$SHERLOCK_PROD_URL/api/ci-runs/v3" \
            -H 'Content-Type: application/json' \
            -H 'Authorization: Bearer ${{ steps.iap_auth.outputs.id_token }}' \
            -H 'X-GHA-OIDC-JWT: ${{ steps.gha_auth.outputs.id_token }}' \
            -d "@$RUNNER_TEMP/body.json" | jq