feat!: wrap payloads to send to a "method" with "token" or "webhook"

[zimeg]

Summary

This PR introduces a handful of changes across this action in preparation for @v2! - #312 ✨

A few more changes might be needed, but I'm hoping this is in an alright place to test things! Most details are in the README but some testing notes are below 🙏 📚

One notable change from the proposal is the parsing of YAML values 😳 I stumbled across the js-yaml package during development and am finding that it parses super well and makes it a bit easier to author workflows - it all seems like YAML but it's parsed as a string that's converted to JSON via YAML! I think it's neat, but open to all discussion on this!

Planning to soon find ways to test this beyond local builds, but the steps for reviews can hopefully be helpful for testing things 🧪

Running experimental changes in a development or testing workspace

Check out the documentation in .github/resources 🙏 ✨

Running experimental changes of this branch in real workflows can be done with this-

- name: Checkout the Slack GitHub Action
  uses: actions/checkout@v4
  with:
    repository: slackapi/slack-github-action
    ref: v2-development
    path: ./slack-send
    token: ${{ secrets.GITHUB_TOKEN }}

- name: Setup Node
  uses: actions/setup-node@v4
  with:
    node-version: 20
    cache: "npm"
    cache-dependency-path: ./slack-send/package-lock.json

- name: Install dependencies
  run: npm install
  working-directory: ./slack-send

- name: Post a token message into channel
  uses: ./slack-send
  with:
    method: chat.postMessage
    token: ${{ secrets.SLACK_BOT_TOKEN }}
    payload: |
      channel: ${{ secrets.SLACK_CHANNEL_ID }}
      text: "Action happens at <https://github.com/${{ github.repository }}>"

📆 If these changes are seeming alright, I'm hoping to keep this PR open for a few more weeks for possible issues to appear in testing. Please do share issues you find!

Preview

Here, the payload uses a method and token with YAML values:

- name: Post a message to a channel using a token
  uses: slackapi/slack-github-action@v2
  with:
    method: chat.postMessage
    token: ${{ secrets.SLACK_BOT_TOKEN }}
    payload: |
      text: "Actions happen at <https://github.com/${{ github.repository }}>"
      channel: ${{ secrets.SLACK_CHANNEL_ID }}

This example POSTs the payload-file-path to the webhook URL:

- name: Start a Slack workflow using a webhook URL
  uses: slackapi/slack-github-action@v2
  with:
    webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
    payload-file-path: ./build-artifacts.json

Reviewers

From the kind reviewer, testing of all kinds is super appreciated! Using these changes with various token and method combinations, or testing edge cases with the payloads and inputs with webhook are all things that have changed, as well as some of the documentation that goes with this 📚

With this branch checked out, notes on testing and changing commands can be found as resources:

🔗 https://github.com/slackapi/slack-github-action/tree/v2-development/.github/resources

Notes

• The updated unit tests cover most happy paths and integration tests make sure messages can be sent with each technique, but I do plan to cover a few more lines in the following commits 🔬
• This change brings more files than before, but I found this made some sense during development. Open to all thoughts on this though!
  • Also open to breaking this PR up into multiple if that's easier to review. It's nice to couple some of these changes, but I believe the testing setup is separate from actual changes to the action 😅

⚠️ CI is failing with so much change!The pull_request_targed used in main.yml is running the workflow on main with the changes of this PR. That fails due to build setups...

Hoping that the red "x" isn't so off-putting, but I believe the pull_request workflow is the most important for our tests 🔬

I'm thinking we could do some magic with what workflows exist on main while also using the pull_request_target if we're wanting to get green checks 🤔

Todo

• Stub IRL callings of the @slack/web-api WebClient
  • Integration tests cover actual usage, but options aren't tested directly on the instantiated client 😬
• Add the build step back if it's now breaking - it does seem needed to avoid the npm install in testing...
• Confirm that thread_ts are being returned!
• Attempt to check lints in CI without additional action steps.
• Revert the inclusion of pull_request in CI - a final step!

Requirements

• I've read and understood the Contributing Guidelines and have done my best effort to follow them.
• I've read and agree to the Code of Conduct.

[zimeg]

📝 Sharing a few quick responses to great feedback, but will continue with iteration to the README after this!

[zimeg]

Per the great suggestion of @filmaj 🙏

[zimeg]

Thanks for calling this out! I agree that the actions of this app deserve a bit more explanation. The writer might've been holding too much context at first...

I've added a few details in the overview with a recommendation to develop and experiment with act, while using CI testing for more real apps 🧪 📚

[zimeg]

@filmaj Apologies for causing this confusion! I wrote a few notes that encourage using develop when testing changes while leaving notes on test to the following CI sections of the maintainer's guide 🙏