diff --git a/.github/MAINTAINERS_GUIDE.md b/.github/MAINTAINERS_GUIDE.md index 8043b2a3..3dafe32c 100644 --- a/.github/MAINTAINERS_GUIDE.md +++ b/.github/MAINTAINERS_GUIDE.md @@ -256,6 +256,7 @@ Certain things are common during development and require a few commands. - [Running](#running) - [Setting a global alias](#setting-a-global-alias) - [Generating documentation](#generating-documentation) + - [Synchronizing changes upstream](#synchronizing-changes-upstream) - [Versioning](#versioning) - [Updating](#updating) - [Bumping the Golang version](#bumping-the-golang-version) @@ -461,6 +462,26 @@ You can generate documentation for all commands in the `docs/` directory with: slack docgen ``` +#### Synchronizing changes upstream + +Automated workflows run on documentation changes to [sync][sync] files between +this project and the documentation build. + +A GitHub application called [`@slackapi[bot]`][github-app-docs] mirrors changes +to these files and requires certain permissions: + +- **Actions**: Read and write +- **Contents**: Read and write +- **Metadata**: Read +- **Pull requests**: Read and write + +Access to both this project repo and documentation repo must also be granted. + +Credentials and secrets for the app can be stored as the following variables: + +- `GH_APP_ID_DOCS` +- `GH_APP_PRIVATE_KEY_DOCS` + ### Versioning We use git tags and [semantic versioning][semver] to version this program. The @@ -509,7 +530,22 @@ to ensure all references were updated properly: - GitHub Actions in: `.github/workflows/tests.yml` - e.g. `actions/setup-go` Automation that powers can be found in [this workflow][wf-dependencies] and -[this app][github-app]. Secrets are found elsewhere. +[this app][github-app-releaser]. Secrets are found elsewhere. + +For these changes to complete, certain application permissions are needed: + +- **Actions**: Read and write +- **Contents**: Read and write +- **Metadata**: Read +- **Pull requests**: Read and write +- **Workflows**: Read and write + +Access to this project is also required with the selected application scopes. + +Credentials and secrets for the app can be stored as the following variables: + +- `GH_APP_ID_RELEASER` +- `GH_APP_PRIVATE_KEY_RELEASER` #### Bumping Go package versions @@ -776,7 +812,8 @@ When in doubt, find the other maintainers and ask. [dev-release]: https://github.com/slackapi/slack-cli/releases/tag/dev-build [e2e]: https://github.com/slackapi/slack-cli/actions/workflows/e2e_tests.yml [effective-go]: https://golang.org/doc/effective_go -[github-app]: https://github.com/apps/slack-cli-releaser +[github-app-docs]: https://github.com/apps/slackapi +[github-app-releaser]: https://github.com/apps/slack-cli-releaser [goinstaller]: https://go.dev/doc/install [golang]: https://golang.org/ [golang-standards]: https://github.com/golang-standards/project-layout @@ -792,5 +829,6 @@ When in doubt, find the other maintainers and ask. [practical-go]: https://dave.cheney.net/practical-go/presentations/qcon-china.html [scripts]: ../scripts [semver]: https://semver.org/ +[sync]: https://github.com/slackapi/slack-cli/blob/main/.github/workflows/sync-docs-from-cli-repo.yml [vscode]: https://github.com/slackapi/slack-cli/blob/main/.vscode/settings.json [wf-dependencies]: ./workflows/dependencies.yml diff --git a/.github/workflows/dependencies.yml b/.github/workflows/dependencies.yml index e5a3685e..c2c57f3e 100644 --- a/.github/workflows/dependencies.yml +++ b/.github/workflows/dependencies.yml @@ -12,8 +12,8 @@ jobs: id: credentials uses: actions/create-github-app-token@v2.0.2 with: - app-id: ${{ secrets.GH_APP_ID }} - private-key: ${{ secrets.GH_APP_PRIVATE_KEY }} + app-id: ${{ secrets.GH_APP_ID_RELEASER }} + private-key: ${{ secrets.GH_APP_PRIVATE_KEY_RELEASER }} - name: Checkout the repo uses: actions/checkout@v4.2.2 with: diff --git a/.github/workflows/sync-docs-from-cli-repo.yml b/.github/workflows/sync-docs-from-cli-repo.yml index 5c9dff6d..627a4e1d 100644 --- a/.github/workflows/sync-docs-from-cli-repo.yml +++ b/.github/workflows/sync-docs-from-cli-repo.yml @@ -23,9 +23,9 @@ jobs: id: ghtoken uses: actions/create-github-app-token@v2.0.2 with: - app-id: ${{ secrets.GH_APP_ID }} + app-id: ${{ secrets.GH_APP_ID_DOCS }} owner: slackapi - private-key: ${{ secrets.GH_APP_PRIVATE_KEY }} + private-key: ${{ secrets.GH_APP_PRIVATE_KEY_DOCS }} - name: Checkout the tool repo (source) uses: actions/checkout@v4.2.2 diff --git a/docs/guides/authorizing-the-slack-cli.md b/docs/guides/authorizing-the-slack-cli.md index 96611a26..c90c9f08 100644 --- a/docs/guides/authorizing-the-slack-cli.md +++ b/docs/guides/authorizing-the-slack-cli.md @@ -72,7 +72,7 @@ Setting up a CI/CD pipeline requires authorization using a service token. Servic To get a service token, you'll use the `slack auth token` command to get a `slackauthticket`, which you'll copy and paste into your workspace to exchange for the service token. The service token will not be saved to your `credentials.json` file; instead, it is presented in the terminal for you to copy and paste for use in your CI/CD pipeline. Once copied, you'll use the `slack login --auth ` command to authorize your Slack CLI. Detailed instructions are below. -:::info +:::info The service token will not conflict with your regular authentication token; you can continue using your regular authentication token within the Slack CLI while using the service token for your CI/CD pipeline. @@ -86,7 +86,8 @@ This "Slack service account" will be identical to other user accounts, but servi ### Obtaining a service token {#obtain-token} -Run the following command to get a `slackauthticket`: +Run the following command to get a `slackauthticket`: + ``` slack auth token ```