{"id":19541594,"url":"https://github.com/brigadecore/brigade-slack-gateway","last_synced_at":"2025-04-26T17:30:50.999Z","repository":{"id":37787235,"uuid":"406102323","full_name":"brigadecore/brigade-slack-gateway","owner":"brigadecore","description":null,"archived":false,"fork":false,"pushed_at":"2023-03-07T01:37:10.000Z","size":158,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-04T16:27:46.584Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brigadecore.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-13T19:26:35.000Z","updated_at":"2022-03-21T19:05:07.000Z","dependencies_parsed_at":"2024-06-19T11:23:50.493Z","dependency_job_id":"d38d336b-a4a5-4c1e-a467-a3961c74d3d4","html_url":"https://github.com/brigadecore/brigade-slack-gateway","commit_stats":{"total_commits":47,"total_committers":1,"mean_commits":47.0,"dds":0.0,"last_synced_commit":"583d6bb233f815c90f7dbfdba34162b67032daa9"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brigadecore%2Fbrigade-slack-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brigadecore%2Fbrigade-slack-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brigadecore%2Fbrigade-slack-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brigadecore%2Fbrigade-slack-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brigadecore","download_url":"https://codeload.github.com/brigadecore/brigade-slack-gateway/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251025588,"owners_count":21524829,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T03:11:11.983Z","updated_at":"2025-04-26T17:30:50.691Z","avatar_url":"https://github.com/brigadecore.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Brigade Slack Gateway\n\n![build](https://badgr.brigade2.io/v1/github/checks/brigadecore/brigade-slack-gateway/badge.svg?appID=99005)\n[![codecov](https://codecov.io/gh/brigadecore/brigade-slack-gateway/branch/main/graph/badge.svg?token=rlzg9dnm02)](https://codecov.io/gh/brigadecore/brigade-slack-gateway)\n[![Go Report Card](https://goreportcard.com/badge/github.com/brigadecore/brigade-slack-gateway)](https://goreportcard.com/report/github.com/brigadecore/brigade-slack-gateway)\n[![slack](https://img.shields.io/badge/slack-brigade-brightgreen.svg?logo=slack)](https://kubernetes.slack.com/messages/C87MF1RFD)\n\n\u003cimg width=\"100\" align=\"left\" src=\"logo.png\"\u003e\n\nThis is a work-in-progress\n[Brigade 2](https://github.com/brigadecore/brigade/tree/v2)\ncompatible gateway that receives events from Slack slash commands and propagates\nthem into Brigade 2's event bus.\n\n\u003cbr clear=\"left\"/\u003e\n\n## Installation\n\nThe installation for this gateway is multi-part, and not particularly easy, at\nleast in part because of a potential \"chicken and egg\" problem. Setting up this\ngateway requires values obtained during the creation of a Slack App. Setting\nup the Slack App _may_ require the gateway's public IP (if you're not using a\ndomain or subdomain name instead). We will use an approach of setting up the\nSlack App first, with a placeholder value for the gateway's address, if\nnecessary, in which case the Slack App configuration will be revisited after\nthe gateway is configured and deployed.\n\nPrerequisites:\n\n* A Kubernetes cluster:\n    * For which you have the `admin` cluster role\n    * That is already running Brigade 2\n    * Capable of provisioning a _public IP address_ for a service of type\n      `LoadBalancer`. (This means you won't have much luck running the gateway\n      locally in the likes of kind or minikube unless you're able and willing to\n      mess with port forwarding settings on your router, which we won't be\n      covering here.)\n\n* `kubectl`, `helm` (commands below require Helm 3.7.0+), and `brig` (the\n  Brigade 2 CLI)\n\n### 1. Create a Slack App\n\nA Slack App is a special kind of trusted entity that is \"installable\" into a\nSlack workspace to enable integrations.\n\nThis gateway can support multiple Slack Apps, but these instructions walk you\nthrough the steps for setting up just one.\n\n* Visit https://api.slack.com/apps. Log in if you are not logged in already.\n\n* Click __Create New App__ and __From scratch__.\n\n* Specify an __App Name__, select the workspace to install your new App into,\n  and click __Create App__. This will create the App and take you to the App's\n  own page.\n\n* Under the heading __Add features and functionality__, click\n  __Slash Commands__, and then __Create New Command__.\n\n* Set __Command__ to be the word, with a leading slash (`/`), that should\n  trigger an event. Example: `/demo`.\n\n* Set the __Request URL__ to \n  `https://\u003cyour gateway domain or subdomain name\u003e/slash-commands`.\n    * If you're not using a domain or subdomain name and want to use a public IP\n      here instead, put a placeholder such as\n      `http://example.com/slash-commands` here for now and revisit this section\n      later after a public IP has been established for your gateway.\n\n* Provide a __Short Description__ of what the command will do and optionally,\n  provide a __Usage Hint__.\n\n* Click __Save__\n\n* Return to https://api.slack.com/apps and select the App you just created.\n  This will take you to the App's page.\n\n* Under the __App Credentials__ heading, make note of the __App ID__ and\n  __Signing Secret__. You will be using these values again in another step.\n\n* Click __OAuth \u0026 Permissions__ and make note of the __Bot User OAuth Token__\n  found under the __OAuth Tokens for Your Workspace__ heading. You will be using\n  this value again in another step.\n\n### 2. Create a Service Account for the Gateway\n\n__Note:__ To proceed beyond this point, you'll need to be logged into Brigade 2\nas the \"root\" user (not recommended) or (preferably) as a user with the `ADMIN`\nrole. Further discussion of this is beyond the scope of this documentation.\nPlease refer to Brigade's own documentation.\n\nUsing Brigade 2's `brig` CLI, create a service account for the gateway to use:\n\n```shell\n$ brig service-account create \\\n    --id brigade-slack-gateway \\\n    --description brigade-slack-gateway\n```\n\nMake note of the __token__ returned. This value will be used in another step.\n_It is your only opportunity to access this value, as Brigade does not save it._\n\nAuthorize this service account to read all events and to create new ones:\n\n```shell\n$ brig role grant READER \\\n    --service-account brigade-slack-gateway\n\n$ brig role grant EVENT_CREATOR \\\n    --service-account brigade-slack-gateway \\\n    --source brigade.sh/slack\n```\n\n__Note:__ The `--source brigade.sh/slack` option specifies that\nthis service account can be used _only_ to create events having a value of\n`brigade.sh/slack` in the event's `source` field. _This is a\nsecurity measure that prevents the gateway from using this token for\nimpersonating other gateways._\n\n### 3. Install the Slack Gateway\n\nWe're using the [GitHub Container Registry](https://ghcr.io) (which is\nan [OCI registry](https://helm.sh/docs/topics/registries/)) to host our Helm\nchart. Helm 3.7 has support for installing charts directly from OCI registries.\n\nFirst, be sure you are using\n[Helm 3.7.0](https://github.com/helm/helm/releases/tag/v3.7.0) or greater and\nenable OCI support:\n\n```shell\n$ export HELM_EXPERIMENTAL_OCI=1\n```\n\nAs this chart requires some custom configuration, we'll need to create a chart\nvalues file with said config.\n\nUse the following command to extract the full set of configuration options into\na file you can modify:\n\n```shell\n$ helm inspect values oci://ghcr.io/brigadecore/brigade-slack-gateway \\\n    --version v0.3.1 \u003e ~/brigade-slack-gateway-values.yaml\n```\n\nEdit `~/brigade-slack-gateway-values.yaml`, making the following changes:\n\n* `brigade.apiAddress`: Address of the Brigade API server, beginning with\n  `https://`\n\n* `brigade.apiToken`: Service account token from step 2\n\n* `github.apps`: Specify the details of your Slack App(s), including:\n\n    * `appID`: This is the unique ID for a Slack App. You took note of this\n      value in a previous step.\n\n    * `appSigningSecret`: This secret can be used to validate signatures on\n      inbound slash commands. This is the __Signing Secret__ you took note of in\n      a previous step.\n\n    * `apiToken`: This token can be used to authenticate when sending messages\n      back to Slack. This is the __Bot User OAuth Token__ you took note of in a\n      previous step.\n\n* `receiver.host`: Set this to the host name where you'd like the gateway to be\n  accessible.\n\n* `receiver.service.type`: If you plan to enable ingress (advanced), you can\n  leave this as its default -- `ClusterIP`. If you do not plan to enable\n  ingress, you probably will want to change this value to `LoadBalancer`.\n\nSave your changes to `~/brigade-slack-gateway-values.yaml` and use the following\ncommand to install the gateway using the above customizations:\n\n```shell\n$ helm install brigade-slack-gateway \\\n    oci://ghcr.io/brigadecore/brigade-slack-gateway \\\n    --version v0.3.1 \\\n    --create-namespace \\\n    --namespace brigade-slack-gateway \\\n    --values ~/brigade-slack-gateway-values.yaml \\\n    --wait \\\n    --timeout 300s\n```\n\n### 4. (RECOMMENDED) Create a DNS Entry\n\nIf you overrode defaults and set `receiver.service.type` to `LoadBalancer`, use\nthis command to find the gateway's public IP address:\n\n```shell\n$ kubectl get svc brigade-slack-gateway-receiver \\\n    --namespace brigade-slack-gateway \\\n    --output jsonpath='{.status.loadBalancer.ingress[0].ip}'\n```\n\nIf you overrode defaults and enabled support for an ingress controller, you\nprobably know what you're doing well enough to track down the correct IP without\nour help. 😉\n\nWith this public IP in hand, edit your name servers and add an `A` record\npointing your domain to the public IP.\n\n__Note:__ If you do not want to use a domain or subdomain name, or are unable\nto, and elected to use a placeholder URL when initially setting up your Slack\nApp, return to https://api.slack.com/apps and edit your App's configuration\nto send your slash command to `https://\u003cpublic ip\u003e/slash-commands`.\n\n### 5. Add a Brigade Project\n\nYou can create any number of Brigade projects (or modify an existing one) to\nlisten for events that were sent from Slack to your gateway and, in turn,\nemitted into Brigade's event bus. You can subscribe to all event types emitted\nby the gateway, or just specific ones.\n\nIn the example project definition below, we subscribe to all events emitted by\nthe gateway, provided they've originated from the fictitious Slack app with the\nID `FAKEAPPID` (see the `appID` qualifier).\n\n```yaml\napiVersion: brigade.sh/v2\nkind: Project\nmetadata:\n  id: slack-demo\ndescription: A project that demonstrates integration with Slack\nspec:\n  eventSubscriptions:\n  - source: brigade.sh/slack\n    qualifiers:\n      appID: FAKEAPPID\n    types:\n    - \"*\"\n  workerTemplate:\n    defaultConfigFiles:\n      brigade.js: |-\n        const { events } = require(\"@brigadecore/brigadier\");\n\n        events.on(\"brigade.sh/slack\", \"demo\", () =\u003e {\n          console.log(\"Someone sent the /demo slash command!\");\n        });\n\n        events.process();\n```\n\nIn the alternative example below, we subscribe _only_ to `demo` events:\n\n```yaml\napiVersion: brigade.sh/v2\nkind: Project\nmetadata:\n  id: slack-demo\ndescription: A project that demonstrates integration with Slack\nspec:\n  eventSubscriptions:\n  - source: brigade.sh/slack\n    qualifiers:\n      appID: FAKEAPPID\n    types:\n    - demo\n  workerTemplate:\n    defaultConfigFiles:\n      brigade.js: |-\n        const { events } = require(\"@brigadecore/brigadier\");\n\n        events.on(\"brigade.sh/slack\", \"demo\", () =\u003e {\n          console.log(\"Someone sent the /demo slash command!\");\n        });\n\n        events.process();\n```\n\nAssuming this file were named `project.yaml`, you can create the project like\nso:\n\n```shell\n$ brig project create --file project.yaml\n```\n\nTyping `/demo` in a Slack channel should now send an event (slash command) from\nSlack to your gateway. The gateway, in turn, will emit the event into Brigade's\nevent bus. Brigade should initialize a worker (containerized event handler) for\nevery project that has subscribed to the event, and the worker should execute\nthe `brigade.js` script that was embedded in the project definition.\n\nList the events for the `slack-demo` project to confirm this:\n\n```shell\n$ brig event list --project slack-demo\n```\n\nFull coverage of `brig` commands is beyond the scope of this documentation, but\nat this point, additional `brig` commands can be applied to monitor the event's\nstatus and view logs produced in the course of handling the event.\n\n## Events Received and Emitted by this Gateway\n\nUnlike most Brigade gateways, this gateway dynamically determines the value of\nthe `type` field on events it emits into Brigade's event bus by simply stripping\nthe leading slash (`/`) from the incoming slash command.\n\nAll events are qualified by `appID` and labeled with `teamID` (workspace ID),\n`channelID`, and `userID`. Qualifying events by `appID` ensures disambiguation\nif you are using multiple Slack Apps that each support one or more slash\ncommands having the same names. Labeling events with `teamID`, `channelID`, and\n`userID` enables subscriptions to optionally be very specific about what events\nthey're interested in.\n\nEvent payloads are composed of any text that followed the slash command when\nentered by the Slack user.\n\nHere is an abbreviated representation of a sample event emitted by this gateway:\n\n```yaml\napiVersion: brigade.sh/v2\nkind: Event\nmetadata:\n  created: \"2021-09-24T20:46:47.037Z\"\n  id: 33b0e475-1414-4142-a682-f7b916ad2989\nprojectID: slack-demo\nsource: brigade.sh/slack\nqualifiers:\n  appID: A02C3GPHM6D\nlabels:\n  channelID: C02CU7ZMJMA\n  teamID: TFNLDR3SP\n  userID: UGN3UHXAM\ntype: demo\npayload: foobar\n```\n\n## Examples Projects\n\nSee `examples/` for complete Brigade projects that demonstrate various\nscenarios.\n\n## Contributing\n\nThe Brigade project accepts contributions via GitHub pull requests. The\n[Contributing](CONTRIBUTING.md) document outlines the process to help get your\ncontribution accepted.\n\n## Support \u0026 Feedback\n\nWe have a slack channel!\n[Kubernetes/#brigade](https://kubernetes.slack.com/messages/C87MF1RFD) Feel free\nto join for any support questions or feedback, we are happy to help. To report\nan issue or to request a feature open an issue\n[here](https://github.com/brigadecore/brigade-slack-gateway/issues)\n\n## Code of Conduct\n\nParticipation in the Brigade project is governed by the\n[CNCF Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrigadecore%2Fbrigade-slack-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrigadecore%2Fbrigade-slack-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrigadecore%2Fbrigade-slack-gateway/lists"}