Merge upstream changes

.changeset/README.md

@@ -0,0 +1,5 @@
+# Changesets
+
+This directory contains [**Changesets**](https://github.com/changesets/changesets) which are markdown files that describe package changes for the next release.
+
+For guidance on when and how to add changesets, checkout the [Maintainer's Guide](../.github/maintainers_guide.md#changesets).

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "restricted",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.github/CODEOWNERS

@@ -0,0 +1,12 @@
+# Salesforce Open Source project configuration
+# Learn more: https://github.com/salesforce/oss-template
+#ECCN:Open Source
+#GUSINFO:Open Source,Open Source Workflow
+
+# @slackapi/slack-github-action
+# are code reviewers for all changes in this repo.
+* @slackapi/slack-github-action
+
+# @slackapi/developer-education
+# are code reviewers for changes in the `/docs` directory.
+/docs/ @slackapi/developer-education

.github/dependabot.yml

@@ -1,11 +1,15 @@
 version: 2
 updates:
-  - package-ecosystem: 'npm'
-    directory: '/'
+  - package-ecosystem: "npm"
+    directory: "/"
     schedule:
-      interval: 'monthly'
-
-  - package-ecosystem: 'github-actions'
-    directory: '/'
+      interval: "monthly"
+    ignore:
+      - dependency-name: "@types/node"
+        versions:
+          - "25.x"
+          - "26.x"
+  - package-ecosystem: "github-actions"
+    directory: "/"
     schedule:
-      interval: 'monthly'
+      interval: "monthly"

.github/maintainers_guide.md

@@ -18,31 +18,88 @@ Information on setting up and configuring mocked events can be found in [`.githu
 
 ### Testing
 
-When testing locally, ensure at least linting and unit tests pass by running `npm test`.
-Additionally, sending a PR is highly recommended with every change as there are several GitHub
-Actions jobs that execute what are effectively integration tests for this GitHub Action.
-
-#### Checks on PRs
-
-Actions that run the integration tests on PRs from a fork will require approval before running.
-These checks use stored secrets so the changes should be reviewed before approving the workflow to
-avoid accidently leaking tokens!
-
-### Releasing
-
-* Check the status of this project's GitHub Milestone to be released for issues that should be shipped with the release.
-  -  If all issues have been closed, continue with the release.
-  -  If issues are still open, discuss with the team about whether the open issues should be moved to a future release or if the release should be held off until the issues are resolved.
-  -  Take a look at all issues under the Milestone to make sure that the type of issues included aligns with the Milestone name based on [semantic versioning](https://semver.org/). If the issues do not align with the naming of the Milestone (ex: if the issues are all bug fixes, but the Milestone is labeled as a minor release), then you can tweak the Milestone name to reflect the correct versioning.
-* Update the version in `package.json`.
-* Update all references to versions in the README and in the workflow files under `example-workflows/` to refer to the latest release.
-* Run all tests using `npm test` to make sure the tests pass.
-* Commit the changes on your `main` branch.
-* Create a git tag for the new version. Should be in the format `v1.4.0`. `git tag v1.4.0`.
-* Push changes up to GitHub `git push origin main --tags`.
-* Create a GitHub Release based on the tag you just pushed up - this will trigger the publishing
-  GitHub workflow.
-* Once released, make sure to close the relevant GitHub Milestone for the version you released.
+Expected behaviors are confirmed with both unit tests and integration tests. Our unit tests run fast without secrets, while integration tests use webhooks and tokens for sending data to Slack across various techniques.
+
+#### Unit tests
+
+Run the following scripts to confirm tests pass before opening a PR:
+
+```sh
+$ npm test       # Unit tests
+$ npm run lint   # Lint and format
+$ npm run check  # Typecheck
+```
+
+The `test.yml` workflow runs these scripts for pull requests and changes to the `main` branch.
+
+#### Integration tests
+
+The `integration.yml` workflow uses this action in interactions with Slack using secrets saved to the `staging` environment.
+
+A PR from a forked branch will fail this workflow until a maintainer reviews the code and [dispatches](https://github.com/slackapi/slack-github-action/actions/workflows/integration.yml) a test run that points to the most recent commit using the following format:
+
+```
+pull/<NUMBER>/head
+```
+
+### Documentation
+
+This repo contains two types of docs files:
+
+- markdown files
+- sidebar.json
+
+The private repo containing the docs.slack.dev site pulls these in at build time.
+
+Maintainers need to use the `run workflow` button associated with the `deploy` workflow in that private repo to update the docs with changes from here.
+
+#### Markdown Files
+
+The markdown files here are secretly mdx files in disguise.
+
+If you'd like to add images to pages, add the image files to the same folder the md file is in.
+
+We appreciate markdown edits from anyone!!!
+
+#### Sidebar
+
+`_sidebar.json` sets the slack github action docs sidebar
+
+sidebar values take the form of "slack-github-action/path-within-docs/"
+
+or, in other words - full path but remove "docs":
+path: slack-github-action/docs/sending-variables.md
+value: slack-github-action/sending-variables
+
+for info on syntax see https://docusaurus.io/docs/sidebar
+
+this file is copied into slackapi.github.io/slack-github-action/sidebar.js it is then called in slackapi.github.io/sidebars.js
+
+### Changesets
+
+This project uses [Changesets](https://github.com/changesets/changesets) to track changes and automate releases.
+
+Each changeset describes a change to the package and its [semver](https://semver.org/) impact, and a new changeset should be added when updating the package with some change that affects consumers:
+
+```sh
+npm run changeset
+```
+
+Updates to documentation, tests, or CI might not require new entries.
+
+When a PR containing changesets is merged to `main`, a different PR is opened or updated using [changesets/action](https://github.com/changesets/action) which consumes the pending changesets, bumps the package version, and updates the `CHANGELOG` in preparation to release.
+
+### Releases
+
+New versions are published when the release PR created from changesets is merged and the publish workflow is approved. Follow these steps to build confidence:
+
+1. **Check GitHub Milestones**: Before merging the release PR please check the relevant [Milestones](https://github.com/slackapi/slack-github-action/milestones). If issues or pull requests are still open either decide to postpone the release or save those changes for a future update.
+
+2. **Review the release PR**: Verify that the version bump matches expectations, `CHANGELOG` entries are clear, and CI checks pass.
+
+3. **Merge and approve**: Merge the release PR, then approve the publish workflow to release the action. Update the [release](https://github.com/slackapi/slack-github-action/releases) to share to the [marketplace](https://github.com/marketplace/actions/the-slack-github-action).
+
+4. **Update Milestones**: Close the relevant [Milestones](https://github.com/slackapi/slack-github-action/milestones) and rename these to match the released version. Open a new Milestone for the next version.
 
 ## Workflow
 
@@ -60,6 +117,8 @@ As a maintainer, the development you do will be almost entirely off of your fork
 
 `main` is where active development occurs.
 
+`release/vX.Y.Z` has the packaged distribution of a particular version based from the changes on `main`. This is created using a workflow when new releases are published.
+
 When developing, branches should be created off of your fork and not directly off of this repository. If working on a long-running feature and in collaboration with others, a corresponding branch of the same name is permitted. This makes collaboration on a single branch possible, as contributors working on the same feature cannot push commits to others' open Pull Requests.
 
 After a major version increment, there also may be maintenance branches created specifically for supporting older major versions.
@@ -68,18 +127,17 @@ After a major version increment, there also may be maintenance branches created
 
 Labels are used to run issues through an organized workflow. Here are the basic definitions:
 
-*  `bug`: A confirmed bug report. A bug is considered confirmed when reproduction steps have been
-   documented and the issue has been reproduced.
-*  `enhancement`: A feature request for something this package might not already do.
-*  `docs`: An issue that is purely about documentation work.
-*  `tests`: An issue that is purely about testing work.
-*  `needs feedback`: An issue that may have claimed to be a bug but was not reproducible, or was otherwise missing some information.
-*  `discussion`: An issue that is purely meant to hold a discussion. Typically the maintainers are looking for feedback in this issues.
-*  `question`: An issue that is like a support request because the user's usage was not correct.
-*  `semver:major|minor|patch`: Metadata about how resolving this issue would affect the version number.
-*  `security`: An issue that has special consideration for security reasons.
-*  `good first contribution`: An issue that has a well-defined relatively-small scope, with clear expectations. It helps when the testing approach is also known.
-*  `duplicate`: An issue that is functionally the same as another issue. Apply this only if you've linked the other issue by number.
+- `bug`: A confirmed bug report. A bug is considered confirmed when reproduction steps have been documented and the issue has been reproduced.
+- `enhancement`: A feature request for something this package might not already do.
+- `docs`: An issue that is purely about documentation work.
+- `tests`: An issue that is purely about testing work.
+- `needs feedback`: An issue that may have claimed to be a bug but was not reproducible, or was otherwise missing some information.
+- `discussion`: An issue that is purely meant to hold a discussion. Typically the maintainers are looking for feedback in this issues.
+- `question`: An issue that is like a support request because the user's usage was not correct.
+- `semver:major|minor|patch`: Metadata about how resolving this issue would affect the version number.
+- `security`: An issue that has special consideration for security reasons.
+- `good first contribution`: An issue that has a well-defined relatively-small scope, with clear expectations. It helps when the testing approach is also known.
+- `duplicate`: An issue that is functionally the same as another issue. Apply this only if you've linked the other issue by number.
 
 **Triage** is the process of taking new issues that aren't yet "seen" and marking them with a basic
 level of information with labels. An issue should have **one** of the following labels applied:

.github/pull_request_template.md

@@ -2,7 +2,7 @@
 
 Describe the goal of this PR. Mention any related Issue numbers.
 
-### Requirements (place an `x` in each `[ ]`)
+### Requirements <!-- Place an `x` in each `[ ]` -->
 
-* [ ] I've read and understood the [Contributing Guidelines](https://github.com/slackapi/slack-github-action/blob/main/.github/contributing.md) and have done my best effort to follow them.
-* [ ] I've read and agree to the [Code of Conduct](https://slackhq.github.io/code-of-conduct).
+- [ ] I've read and understood the [Contributing Guidelines](https://github.com/slackapi/slack-github-action/blob/main/.github/contributing.md) and have done my best effort to follow them.
+- [ ] I've read and agree to the [Code of Conduct](https://slackhq.github.io/code-of-conduct).

.github/resources/.env.example

@@ -4,4 +4,5 @@
 export SLACK_BOT_TOKEN=xoxb-01010101-example
 export SLACK_CHANNEL_ID=C0123456789
 export SLACK_INCOMING_WEBHOOK=https://hooks.slack.com/services/T0123456789/B0123456789/abcdefghijklmnopqrstuvwxyz
+export SLACK_SERVICE_TOKEN=xoxp-01010101-example
 export SLACK_WEBHOOK_TRIGGER=https://hooks.slack.com/triggers/T0123456789/00000000000/abcdefghijklmnopqrstuvwxyz

.github/resources/.slack/config.json

@@ -1,5 +1,7 @@
 {
-  "experiments": ["bolt"],
+  "manifest": {
+    "source": "local"
+  },
   "project_id": "c4805b41-d1ce-4ea0-b297-ed2f8c64c267"
 }
 

.github/resources/slack.json → .github/resources/.slack/hooks.json

@@ -1,7 +1,7 @@
 {
   "runtime": "actions",
   "hooks": {
-    "deploy": "open https://api.slack.com/apps || true",
+    "deploy": "echo https://api.slack.com/apps",
     "get-manifest": "cat ./.slack/manifest.json #"
   },
   "config": {

.github/resources/README.md

@@ -6,7 +6,7 @@ experiments with the [Slack CLI][cli].
 
 ## Overview
 
-This app showcases all three techniques of sending data into Slack and follows
+This app showcases all four techniques of interacting with Slack and follows
 patterns found in the integration tests.
 
 - **Technique 1** Slack Workflow Builder: Use a Slack webhook trigger to start a
@@ -15,13 +15,18 @@ patterns found in the integration tests.
   data provided through the GitHub workflow.
 - **Technique 3** Incoming webhook: Post a message to a Slack channel using an
   incoming webhook.
+- **Technique 4** Slack CLI Command: Install and run Slack CLI commands such as
+  `deploy` or `manifest` using a service token.
 
 Configurations for the Slack app and workflow, and the GitHub Actions workflow
 are found in the following files:
 
 - Slack app setup: [`.github/resources/.slack/manifest.json`][slacktion]
 - GitHub Actions steps: [`.github/workflows/develop.yml`][develop]
 
+> **Note:** During CLI integration tests, `.github/resources/.slack` is moved to
+> `.slack` at the project root so the Slack CLI can discover the app manifest.
+
 Either the techniques or app setup and workflow steps can be adjusted during
 testing and development. For experimenting with new changes, we recommend using
 the [steps for development](#experimenting-for-development) while the
@@ -76,6 +81,8 @@ tested. Required values include:
   https://hooks.slack.com/services/T0123456789/B0123456789/abcdefghijklmnopqrstuvwxyz
 - `SLACK_WEBHOOK_TRIGGER`:
   https://hooks.slack.com/triggers/T0123456789/00000000000/abcdefghijklmnopqrstuvwxyz
+- `SLACK_SERVICE_TOKEN`: xoxp-service-token-example (secret — for CLI commands)
+- `SLACK_APP_ID`: A0123456789 (variable — used with `--app` flag in CLI deploy)
 
 ### Experimenting for development
 
@@ -98,6 +105,7 @@ export SLACK_BOT_TOKEN=xoxb-01010101-example
 export SLACK_CHANNEL_ID=C0123456789
 export SLACK_INCOMING_WEBHOOK=https://hooks.slack.com/services/T0123456789/B0123456789/abcdefghijklmnopqrstuvwxyz
 export SLACK_WEBHOOK_TRIGGER=https://hooks.slack.com/triggers/T0123456789/00000000000/abcdefghijklmnopqrstuvwxyz
+export SLACK_SERVICE_TOKEN=xoxp-service-token-example
 ```
 
 Environment variables and credentials should be set in the created `.env` file
@@ -134,8 +142,8 @@ of the `.github/resources/.actions/event.json` file.
 
 Reference: https://docs.github.com/en/webhooks/webhook-events-and-payloads
 
-[cli]: https://api.slack.com/automation/cli/commands
+[cli]: https://docs.slack.dev/tools/slack-cli/
 [develop]: ../workflows/develop.yml
-[manifest]: https://api.slack.com/concepts/manifests
+[manifest]: https://docs.slack.dev/app-manifests/
 [secrets]: https://github.com/slackapi/slack-github-action/settings/secrets/actions
 [slacktion]: ./.slack/manifest.json

.github/workflows/dependencies.yml

@@ -0,0 +1,29 @@
+name: Merge updates to dependencies
+on:
+  pull_request:
+jobs:
+  dependabot:
+    name: "@dependabot"
+    if: github.event.pull_request.user.login == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Collect metadata
+        id: metadata
+        uses: dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98 # v3.1.0
+        with:
+          github-token: "${{ secrets.GITHUB_TOKEN }}"
+      - name: Approve
+        if: steps.metadata.outputs.update-type == 'version-update:semver-patch' || steps.metadata.outputs.update-type == 'version-update:semver-minor'
+        run: gh pr review --approve "$PR_URL"
+        env:
+          PR_URL: ${{github.event.pull_request.html_url}}
+          GH_TOKEN: ${{secrets.GITHUB_TOKEN}}
+      - name: Automerge
+        if: steps.metadata.outputs.update-type == 'version-update:semver-patch' || steps.metadata.outputs.update-type == 'version-update:semver-minor'
+        run: gh pr merge --auto --squash "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/develop.yml

@@ -8,13 +8,15 @@ on:
 jobs:
   run:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - name: Checkout action
-        uses: actions/checkout@v4
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           persist-credentials: false
       - name: Setup the Node runtime for this project
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           cache: npm
           cache-dependency-path: package-lock.json