📖 Documentation: Include examples preparing slack message with conditional logic

[fragkakis]

Every couple of years I have trouble resolving the same issue: Slack messages with blocks that appear conditionally. I think it would help a lot of people if the documentation contained such examples. For example, a section that appears only if the test results failed. Or a section that appears only if the workflow was invoked manually.

[mwbrooks]

@fragkakis Thanks for sharing this pain points. 🙇🏻 These type of suggestions are often gems that can save developers a lot of time, but the maintainers would never think about documenting! 💎

@zimeg What are your thoughts on adding documentation around conditional content?

[zimeg]

@fragkakis Seconding the thanks for this suggestion! 🙏 ✨

@mwbrooks I think it's a great idea, though it's somewhat specific to GitHub Actions workflows and syntax. That isn't a reason against it - we might consider adding another section for common cases:

• Sending variables
• Sending techniques
• Common patterns
• Additional configurations

We're hoping to add significant detail about YAML and JSON parsings, and where templated variables are gathered from to the "Sending variables" pages at the moment.

Sending techniques might remain focused on using the techniques with examples specific to each technique, and additional configurations can keep focus on various action options too.

But I think "Common patterns" would be excellent for examples like this, gathering relevant details from certain events, and parsing responses with jq otherwise 📚

Let's add this to the 2.x milestone with hopes to soon add to and improve examples like this!

[zimeg]

Also tagging the excellent @lukegalbraithrussell for awareness and possible thoughts, but TBH writing these docs seems exciting for me if time is crunched elsewhere 😉

[zimeg]

@fragkakis For now, the following docs reference how this can be done at the step level:

- name: Oops something went wrong
  if: ${{ failure() }}
  uses: slackapi/slack-github-action@v2.1.0
  with:
    method: chat.postMessage
    token: ${{ secrets.SLACK_BOT_TOKEN }}
    payload: |
      channel: ${{ secrets.SLACK_CHANNEL_ID }}
      text: "ohno <!channel>!"

[fragkakis]

Let me give you a more concrete (and recent) example, which I came up with through trial and error. It already contains conditional logic (using the condition() && 'label' || 'other label' pattern, which is perhaps the number 1 conditional pattern that should be documented.

The thing I would like documented (and I haven't come up with a nice way to do) is how to make the content after the divider appear conditionally (ie when the workflow has been manually triggered).

- name: Post results to Slack
  uses: slackapi/slack-github-action@v2.1.0
  if: ${{ !cancelled() }}
  with:
    method: chat.postMessage
    token: ${{ secrets.SLACK_BOT_TOKEN }}
    payload: |
      {
        "channel": "#bots-ci",
        "text": "Dataset Test Results - ${{ job.status == 'success' && 'Success ✅' || 'Failure ❌' }} - Run by ${{ github.actor }}",
        "blocks": [
          {
            "type": "header",
            "text": {
              "type": "plain_text",
              "text": ":medical_symbol: Dataset Test Results - ${{ job.status == 'success' && 'Success ✅' || 'Failure ❌' }}",
              "emoji": true
            }
          },
          {
            "type": "section",
            "fields": [
              {
                "type": "mrkdwn",
                "text": "*Run (test results):*\n<${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}|View Details>"
              },
              {
                "type": "mrkdwn",
                "text": "*Duration:*\n${{ steps.process-results.outputs.elapsed_time }}"
              }
            ]
          },
          {
            "type": "section",
            "fields": [
              {
                "type": "mrkdwn",
                "text": "*Branch:*\n${{ github.event_name == 'pull_request' && github.head_ref || github.ref_name }}"
              },
              {
                "type": "mrkdwn",
                "text": "*Success Rate:*\n ${{steps.process-results.outputs.success_percentage}}% (${{steps.process-results.outputs.failed}} failed / ${{steps.process-results.outputs.passed}} passed) "
              }
            ]
          },
          {
            "type": "divider"
          },
          {
            "type": "section",
            "fields": [
              {
                "type": "mrkdwn",
                "text": "*Configuration:*\nLLM Model: `${{ inputs.LLM_MODEL }}` \nTest Dataset Size: `${{ inputs.TEST_DATASET_SIZE }}`"
              }
            ]
          }
        ]
      }

[fragkakis]

💡 Not sure if that's the case, but this kind of "templating" work for the slack message may be easier through a previous step using github-script, which would prepare the string with the message, and then we could consume it. Just dropping the idea.