Skip to content

Commit 18d0229

Browse files
slackapi[bot]lukegalbraithrussell
slackapi[bot]
and
lukegalbraithrussell
authored
docs: organize documentation as markdown files to match web pages (#422)
Co-authored-by: lukegalbraithrussell <31357343+lukegalbraithrussell@users.noreply.github.com>
1 parent 79ad3a9 commit 18d0229

15 files changed

Lines changed: 634 additions & 0 deletions

‎docs/additional-configurations.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Additional configurations
2+
3+
There are some additional, possibly useful, customization options for workflows.
4+
5+
## Exiting with errors
6+
7+
Invalid API requests or unexpected webhook payloads cause a failing response that can be used to fail the GitHub Actions step with the `errors` option.
8+
9+
The `errors` option defaults to `false` so failed requests do not cause the step to fail. This result can still be gathered from the `ok` output.
10+
11+
```yaml
12+
- name: Attempt to call an unknown method
13+
uses: slackapi/slack-github-action@v2.0.0
14+
with:
15+
errors: true
16+
method: chat.reverse
17+
token: ${{ secrets.SLACK_BOT_TOKEN }}
18+
payload: |
19+
text: "palindrome"
20+
```
21+
22+
Invalid inputs to the GitHub Action, such as not including a payload, will always cause the GitHub step to fail.
23+
24+
## Flattening nested payloads
25+
26+
Variables and data provided in the payload might contain nested fields that need to be flattened before being sent with a [webhook trigger](/slack-github-action/sending-techniques/sending-data-webhook-slack-workflow) to match the expected input format of [Workflow Builder](https://slack.com/features/workflow-automation).
27+
28+
The `payload-delimiter` option will flatten the input payload using the provided delimiter and will also make values stringified:
29+
30+
```yaml
31+
- name: Flatten the default GitHub payload
32+
uses: slackapi/slack-github-action@v2.0.0
33+
with:
34+
payload-delimiter: "_"
35+
webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
36+
webhook-type: webhook-trigger
37+
```
38+
39+
Reference to the flattening implementation is available for exploration from within the [`flat`](https://www.npmjs.com/package/flat) package.
40+
41+
## Parsing templated variables
42+
43+
Additional variables provided in the Github event [context](https://github.com/actions/toolkit/blob/main/packages/github/src/context.ts#L6) and event [payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads) can be used to replace templated variables in the input payload with the `payload-templated` option:
44+
45+
```yaml
46+
- name: Send custom JSON data to Slack workflow
47+
uses: slackapi/slack-github-action@v2.0.0
48+
with:
49+
payload-file-path: "./payload-slack-content.json"
50+
payload-templated: true
51+
webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
52+
webhook-type: webhook-trigger
53+
```
54+
55+
This replaces variables templated as `${{ github.payload.repository.html_url }}` with the values found in the GitHub Action event [payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads).
56+
57+
## Proxying HTTPS requests
58+
59+
If you need to use a proxy to connect to Slack, you can use the `proxy` option. In this example we use the technique that calls a Slack API method, but configuring a proxy is the same for all techniques:
60+
61+
```yaml
62+
- name: Post to a Slack channel via a proxy
63+
uses: slackapi/slack-github-action@v2.0.0
64+
with:
65+
method: chat.postMessage
66+
proxy: "http://proxy.example.org:8080" # Change this to a custom value
67+
token: ${{ secrets.SLACK_BOT_TOKEN }}
68+
payload: |
69+
channel: ${{ secrets.SLACK_CHANNEL_ID }}
70+
text: "This message was sent through a proxy"
71+
```
72+
73+
The `proxy` option can also be provided with the `HTTPS_PROXY` or `https_proxy` [environment variable](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) from within the GitHub Actions step.
74+
75+
## Retrying failed requests
76+
77+
Sometimes outgoing requests fail due to [rate limits](https://api.slack.com/apis/rate-limits) or similar [HTTP responses](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) and can be retried later.
78+
79+
The `retries` option can be configured to the needs of your workflow with one of these values:
80+
81+
- `0`: No retries, just hope that things go alright.
82+
- `5`: Five retries in five minutes. **Default**.
83+
- `10`: Ten retries in about thirty minutes.
84+
- `RAPID`: A burst of retries to keep things running fast.
85+
86+
```yaml
87+
- name: Attempt a burst of requests
88+
uses: slackapi/slack-github-action@v2.0.0
89+
with:
90+
method: chat.postMessage
91+
retries: RAPID
92+
token: ${{ secrets.SLACK_BOT_TOKEN }}
93+
payload: |
94+
channel: ${{ secrets.SLACK_CHANNEL_ID }}
95+
text: "status: all things are going good"
96+
```
97+
98+
Behind the scenes, [automatic retries](https://tools.slack.dev/node-slack-sdk/web-api/#automatic-retries) are handled with the [`@slack/web-api`](https://tools.slack.dev/node-slack-sdk/web-api) package for Slack API methods, and [`axios-retry`](https://www.npmjs.com/package/axios-retry) when sending with a webhook.
99+
100+
## Sending to a custom API URL
101+
102+
In certain circumstances, such as testing the sent payload, a [custom API URL](https://tools.slack.dev/node-slack-sdk/web-api/#custom-api-url) can be used to change where `method` requests are sent:
103+
104+
```yaml
105+
- name: Send to a custom API URL
106+
uses: slackapi/slack-github-action@v2.0.0
107+
with:
108+
api: http://localhost:8080
109+
method: chat.postMessage
110+
token: ${{ secrets.SLACK_BOT_TOKEN }}
111+
payload: |
112+
channel: ${{ secrets.SLACK_CHANNEL_ID }}
113+
text: "What's happening on localhost?"
114+
```
115+
116+
The default value of `api` is `https://slack.com/api/` for steps using `method`.

‎docs/sending-techniques/sending-data-slack-api-method/direct-message-author.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Example workflow: direct message the author
2+
3+
This workflow sends a direct message to the user that pushed the most recent commits.
4+
5+
This example uses the email of the pusher to find the user to send a message to.
6+
7+
## Files
8+
9+
### GitHub Actions workflow
10+
11+
```js reference
12+
https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_2_Slack_API_Method/author.yml
13+
```

‎docs/sending-techniques/sending-data-slack-api-method/invite-usergroup-to-channel.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Example workflow: invite a usergroup to channel
2+
3+
This workflow creates a channel after a bug is reported and add members of a usergroup.
4+
5+
This example chains multiple Slack API methods together to help fix bugs fast.
6+
7+
## Files
8+
9+
### GitHub Actions workflow
10+
11+
```js reference
12+
https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_2_Slack_API_Method/invite.yml
13+
```

‎docs/sending-techniques/sending-data-slack-api-method/sending-data-slack-api-method.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
sidebar_label: Overview
3+
---
4+
5+
# Sending data using a Slack API method
6+
7+
A bot token or user token or [token of some other kind](https://api.slack.com/concepts/token-types) must be used to call one of [the Slack API methods](https://api.slack.com/methods) with this technique.
8+
9+
## Setup
10+
11+
Different [Slack API methods](https://api.slack.com/methods) require different [scopes](https://api.slack.com/scopes), but setup should be similar for all methods:
12+
13+
1. [Create a Slack app](https://api.slack.com/apps/new) for your workspace or use an existing app.
14+
2. Depending on the Slack API [method](https://api.slack.com/methods) you wish to call, add the required **scopes** to your app under the **OAuth & Permissions** page on [app settings](https://api.slack.com/apps).
15+
3. Install the app to your workspace using the **Install App** page.
16+
4. Once your app is installed to a workspace, a new [token](https://api.slack.com/concepts/token-types) with your app's specified scopes will be minted for that workspace. It is worth noting that tokens are only valid for a single workspace! Find the token on the **OAuth & Permissions** page.
17+
5. Add the token as [a repository secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) called `SLACK_BOT_TOKEN` or something similar and memorable.
18+
6. [Add this Action as a step](https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idsteps) to your GitHub workflow and provide an input payload to send to the method.
19+
20+
Methods that require an app configuration token should gather this token from the [app configuration token](https://api.slack.com/reference/manifests#config-tokens) settings instead of from a specific app since this token is associated with the workspace.
21+
22+
## Usage
23+
24+
Choosing inputs for these steps is left as an exercise for the actioneer since each of the Slack API methods requires certain values and specific parameters, but these snippets might be helpful when starting.
25+
26+
### Posting a message with text
27+
28+
Posting a message with the [`chat.postMessage`](https://api.slack.com/methods/chat.postMessage) method can be achieved by adding this step to a job in your GitHub workflow and inviting the bot associated with your app to the channel for posting:
29+
30+
```yaml
31+
- name: Post text to a Slack channel
32+
uses: slackapi/slack-github-action@v2.0.0
33+
with:
34+
method: chat.postMessage
35+
token: ${{ secrets.SLACK_BOT_TOKEN }}
36+
payload: |
37+
channel: ${{ secrets.SLACK_CHANNEL_ID }}
38+
text: "howdy <@channel>!"
39+
```
40+
41+
### Posting a message with blocks
42+
43+
More complex message layouts, such as messages made with [Block Kit](https://api.slack.com/surfaces/messages#complex_layouts) blocks, can also be sent with one of the Slack API methods:
44+
45+
```yaml
46+
- name: Post blocks to a Slack channel
47+
uses: slackapi/slack-github-action@v2.0.0
48+
with:
49+
method: chat.postMessage
50+
token: ${{ secrets.SLACK_BOT_TOKEN }}
51+
payload: |
52+
channel: ${{ secrets.SLACK_CHANNEL_ID }}
53+
text: "GitHub Action build result: ${{ job.status }}\n${{ github.event.pull_request.html_url || github.event.head_commit.url }}"
54+
blocks:
55+
- type: "section"
56+
text:
57+
type: "mrkdwn"
58+
text: "GitHub Action build result: ${{ job.status }}\n${{ github.event.pull_request.html_url || github.event.head_commit.url }}"
59+
```
60+
61+
### Updating a message
62+
63+
Updating a message after it's posted can be done with the [`chat.update`](https://api.slack.com/methods/chat.update) method and chaining multiple steps together using outputs from past steps as inputs to current ones:
64+
65+
```yaml
66+
- name: Initiate the deployment launch sequence
67+
id: launch_sequence
68+
uses: slackapi/slack-github-action@v2.0.0
69+
with:
70+
method: chat.postMessage
71+
token: ${{ secrets.SLACK_BOT_TOKEN }}
72+
payload: |
73+
channel: ${{ secrets.SLACK_CHANNEL_ID }}
74+
text: "Deployment started :eyes:"
75+
attachments:
76+
- color: "dbab09"
77+
fields:
78+
- title: "Status"
79+
short: true
80+
value: "In Progress"
81+
- name: Countdown until launch
82+
run: sleep 10
83+
- name: Update the original message with success
84+
uses: slackapi/slack-github-action@v2.0.0
85+
with:
86+
method: chat.update
87+
token: ${{ secrets.SLACK_BOT_TOKEN }}
88+
payload: |
89+
channel: ${{ secrets.SLACK_CHANNEL_ID }}
90+
ts: "${{ steps.launch_sequence.outputs.ts }}"
91+
text: "Deployment finished! :rocket:"
92+
attachments:
93+
- color: "28a745"
94+
fields:
95+
- title: "Status"
96+
short: true
97+
value: "Completed"
98+
```
99+
100+
### Replying to a message
101+
102+
Posting [threaded replies to a message](https://api.slack.com/messaging/sending#threading) from a past job can be done by including the `thread_ts` attribute of the parent message in the `payload`:
103+
104+
```yaml
105+
- name: Initiate a deployment
106+
uses: slackapi/slack-github-action@v2.0.0
107+
id: deployment_message
108+
with:
109+
method: chat.postMessage
110+
token: ${{ secrets.SLACK_BOT_TOKEN }}
111+
payload: |
112+
channel: ${{ secrets.SLACK_CHANNEL_ID }}
113+
text: "Deployment started :eyes:"
114+
- name: Conclude the deployment
115+
uses: slackapi/slack-github-action@v2.0.0
116+
with:
117+
method: chat.postMessage
118+
token: ${{ secrets.SLACK_BOT_TOKEN }}
119+
payload: |
120+
channel: ${{ secrets.SLACK_CHANNEL_ID }}
121+
thread_ts: "${{ steps.deployment_message.outputs.ts }}"
122+
text: "Deployment finished! :rocket:"
123+
```
124+
125+
### Uploading a file
126+
127+
Calling [a Slack API method](https://api.slack.com/methods) with [`@slack/web-api`](https://tools.slack.dev/node-slack-sdk/web-api) makes [uploading a file](https://api.slack.com/messaging/files#upload) just another API call with all of the convenience of the [`files.uploadV2`](https://tools.slack.dev/node-slack-sdk/web-api/#upload-a-file) method:
128+
129+
```yaml
130+
- name: Share a file to that channel
131+
uses: slackapi/slack-github-action@v2.0.0
132+
with:
133+
method: files.uploadV2
134+
token: ${{ secrets.SLACK_BOT_TOKEN }}
135+
payload: |
136+
channel_id: ${{ secrets.SLACK_CHANNEL_ID }}
137+
initial_comment: "the results are in!"
138+
file: "./path/to/results.out"
139+
filename: "results-${{ github.sha }}.out"
140+
```
141+
142+
## Example workflows
143+
144+
* [**Direct message the author**](/slack-github-action/sending-techniques/sending-data-slack-api-method/direct-message-author): Write to the Slack user with a matching email.
145+
* [**Invite a usergroup to channel**](/slack-github-action/sending-techniques/sending-data-slack-api-method/invite-usergroup-to-channel): Create a channel and invite members.

‎docs/sending-techniques/sending-data-slack-incoming-webhook/post-blocks-found-in-file.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Example workflow: post blocks found in a file
2+
3+
This workflow links to the GitHub Actions job in progress.
4+
5+
This example uses file data when posting to an incoming webhook.
6+
7+
## Files
8+
9+
### Payload file being sent
10+
11+
```js reference
12+
https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_3_Slack_Incoming_Webhook/saved.data.json
13+
```
14+
15+
### GitHub Actions workflow
16+
17+
```js reference
18+
https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_3_Slack_Incoming_Webhook/saved.gha.yml
19+
```

‎docs/sending-techniques/sending-data-slack-incoming-webhook/post-inline-block-message.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Example workflow: post an inline block message
2+
3+
This workflow formats a response to recent adventures.
4+
5+
This example uses incoming webhooks to post a message with Block Kit.
6+
7+
## Files
8+
9+
### GitHub Actions workflow
10+
11+
```js reference
12+
https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_3_Slack_Incoming_Webhook/blocks.yml
13+
```

‎docs/sending-techniques/sending-data-slack-incoming-webhook/post-inline-text-message.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Example workflow: post an inline text message
2+
3+
This workflow writes a line of text after a push event is received.
4+
5+
This example uses incoming webhooks to post a plain text message.
6+
7+
## Files
8+
9+
### GitHub Actions workflow
10+
11+
```js reference
12+
https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_3_Slack_Incoming_Webhook/text.yml
13+
```

‎docs/sending-techniques/sending-data-slack-incoming-webhook/sending-data-slack-incoming-webhook.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
sidebar_label: Overview
3+
---
4+
5+
# Sending data as a message with a Slack incoming webhook URL
6+
7+
This technique uses this Action to post a message to a channel or direct message with [incoming webhooks](https://api.slack.com/messaging/webhooks) and a Slack app.
8+
9+
Incoming webhooks follow the same [formatting](https://api.slack.com/reference/surfaces/formatting) patterns as other Slack messaging APIs. Posted messages can be as short as a single line of text, include additional interactivity with [interactive components](https://api.slack.com/messaging/interactivity), or be formatted with [Block Kit](https://api.slack.com/surfaces/messages#complex_layouts) to build visual components.
10+
11+
## Setup
12+
13+
Gather a Slack incoming webhook URL:
14+
15+
1. [Create a Slack app](https://api.slack.com/apps/new) for your workspace or use an existing app.
16+
2. Add the [`incoming-webhook`](https://api.slack.com/scopes/incoming-webhook) bot scope under **OAuth & Permissions** page on [app settings](https://api.slack.com/apps).
17+
3. Install the app to your workspace and select a channel to notify from the **Install App** page.
18+
4. Create additional webhooks from the **Incoming Webhooks** page.
19+
5. Add the generated incoming webhook URL as [a repository secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) called `SLACK_WEBHOOK_URL`.
20+
6. [Add this Action as a step](https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idsteps) to your GitHub workflow and provide an input payload to send as a message.
21+
22+
The webhook URL will resemble something like so:
23+
24+
```txt
25+
https://hooks.slack.com/services/T0123456789/B1001010101/7IsoQTrixdUtE971O1xQTm4T
26+
```
27+
28+
## Usage
29+
30+
Add the collected webhook from above to a GitHub workflow and configure the step using [`mrkdwn`](https://api.slack.com/reference/surfaces/formatting) formatting values for a message or [Block Kit](https://api.slack.com/surfaces/messages#complex_layouts) blocks:
31+
32+
```yaml
33+
- name: Post a message in a channel
34+
uses: slackapi/slack-github-action@v2.0.0
35+
with:
36+
webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
37+
webhook-type: incoming-webhook
38+
payload: |
39+
text: "*GitHub Action build result*: ${{ job.status }}\n${{ github.event.pull_request.html_url || github.event.head_commit.url }}"
40+
blocks:
41+
- type: "section"
42+
text:
43+
type: "mrkdwn"
44+
text: "GitHub Action build result: ${{ job.status }}\n${{ github.event.pull_request.html_url || github.event.head_commit.url }}"
45+
```
46+
47+
## Example workflows
48+
49+
* [**Post an inline text message**](/slack-github-action/sending-techniques/sending-data-slack-incoming-webhook/post-inline-text-message)
50+
* [**Post an inline block message**](/slack-github-action/sending-techniques/sending-data-slack-incoming-webhook/post-inline-block-message)
51+
* [**Post blocks found in a file**](/slack-github-action/sending-techniques/sending-data-slack-incoming-webhook/post-blocks-found-in-file)

0 commit comments

Comments
 (0)