142 lines
5.0 KiB
Markdown
142 lines
5.0 KiB
Markdown
# Resources during testing and development
|
|
|
|
For a quick development experience and fast testing setup, the app needed with
|
|
this action is configured using the [app manifest][manifest] and can be used in
|
|
experiments with the [Slack CLI][cli].
|
|
|
|
## Overview
|
|
|
|
This app showcases all three techniques of sending data into Slack and follows
|
|
patterns found in the integration tests.
|
|
|
|
- **Technique 1** Slack Workflow Builder: Use a Slack webhook trigger to start a
|
|
workflow in Slack Workflow Builder.
|
|
- **Technique 2** Slack API method: Call a Slack API method using a token and
|
|
data provided through the GitHub workflow.
|
|
- **Technique 3** Incoming webhook: Post a message to a Slack channel using an
|
|
incoming webhook.
|
|
|
|
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]
|
|
|
|
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
|
|
[steps for CI](#testing-in-ci) is useful when using this app in an actual GitHub
|
|
Actions workflow.
|
|
|
|
### Getting started
|
|
|
|
Start by gathering credentials of an application equipped for action:
|
|
|
|
```sh
|
|
$ slack install
|
|
$ slack trigger create # SLACK_WEBHOOK_TRIGGER
|
|
$ slack deploy # SLACK_BOT_TOKEN and SLACK_INCOMING_WEBHOOK
|
|
```
|
|
|
|
Gather the **webhook trigger** from the output of the `trigger create` command
|
|
and collect the **bot token** and **incoming webhook** from app settings.
|
|
|
|
Where these are stored will depend on the configurations to run and will follow
|
|
in the next sections.
|
|
|
|
Also be sure to add the new bot to a channel, and while keeping track of that
|
|
**channel ID** for posting messages or errors happen.
|
|
|
|
## Running the workflows
|
|
|
|
Both setups share the same starting test suite to make sure the similar examples
|
|
as in the `README.md` are correct, but changes while testing are encouraged!
|
|
|
|
The app uses the values stored in `.slack` and can also be adjusted for changing
|
|
scopes or workflows.
|
|
|
|
### Testing in CI
|
|
|
|
Run the workflow as a complete CI check for the changes upstream.
|
|
|
|
**Requirements**:
|
|
|
|
- The credentials collected above
|
|
- Access to secrets for the repo
|
|
|
|
The saved `test.yml` include common workflows from the `README.md` and other
|
|
code checks including linting and tests.
|
|
|
|
Add gathered credentials and [secrets to save][secrets] to the repository being
|
|
tested. Required values include:
|
|
|
|
- `SLACK_BOT_TOKEN`: xoxb-01010101-example
|
|
- `SLACK_CHANNEL_ID`: C0123456789
|
|
- `SLACK_INCOMING_WEBHOOK`:
|
|
https://hooks.slack.com/services/T0123456789/B0123456789/abcdefghijklmnopqrstuvwxyz
|
|
- `SLACK_WEBHOOK_TRIGGER`:
|
|
https://hooks.slack.com/triggers/T0123456789/00000000000/abcdefghijklmnopqrstuvwxyz
|
|
|
|
### Experimenting for development
|
|
|
|
Run the workflow to post messages without pushing changes upstream.
|
|
|
|
**Requirements**:
|
|
|
|
- The credentials collected above
|
|
- An installation of [`nektos/act`](https://github.com/nektos/act)
|
|
- A running instance of [Docker](https://www.docker.com)
|
|
|
|
The saved `develop.yml` workflows use the same `webhook` and `method` examples
|
|
but skip tests that happen during upstream checks:
|
|
|
|
```sh
|
|
$ cp .env.example .env # Create credentials
|
|
$ vim .env # Update credentials
|
|
$ cat .env # Reveal credentials
|
|
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
|
|
```
|
|
|
|
Environment variables and credentials should be set in the created `.env` file
|
|
for use in workflows and actions.
|
|
|
|
Once credentials are configured and workflows updated, the following command
|
|
runs the workflow using `act` and the above settings:
|
|
|
|
```sh
|
|
$ npm run dev # Test techniques
|
|
...
|
|
[Local run/run] 🏁 Job succeeded
|
|
```
|
|
|
|
## Configuring different things
|
|
|
|
### Updating the workflow
|
|
|
|
The `develop.yml` file contains the workflow used for testing. Updates to these
|
|
steps can be made to test various functionalities and edge cases.
|
|
|
|
The same applies to test workflows in the `test.yml` file! However, some hope of
|
|
keeping examples in the `README.md` similar to the tests could be neat.
|
|
|
|
### Changing secrets
|
|
|
|
To use `${{ secrets.* }}` in the workflow, add more environment variable values
|
|
to the `.env` file or update the secrets saved to the repository.
|
|
|
|
### Mocking event payloads
|
|
|
|
Different event payloads can be mocked in development with changes to the values
|
|
of the `.github/resources/.actions/event.json` file.
|
|
|
|
Reference: https://docs.github.com/en/webhooks/webhook-events-and-payloads
|
|
|
|
[cli]: https://docs.slack.dev/tools/slack-cli/
|
|
[develop]: ../workflows/develop.yml
|
|
[manifest]: https://docs.slack.dev/app-manifests/
|
|
[secrets]: https://github.com/slackapi/slack-github-action/settings/secrets/actions
|
|
[slacktion]: ./.slack/manifest.json
|