GitLabgitlab-org

cli

main
ply5 git calls29 ms98 KiB4 cachedprotocol v2
190 lines7.8 KiBRaw

Slack Release Notifications

This project is configured to send automated Slack notifications when a new release is published using GoReleaser.

Setup

1. Create a Slack Incoming Webhook

  1. Go to your Slack workspace's Incoming Webhooks page
  2. Click "Create New App" or use an existing app
  3. Enable "Incoming Webhooks"
  4. Click "Add New Webhook to Workspace"
  5. Select the channel where you want release notifications
  6. Copy the webhook URL (format: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX)

2. Configure CI/CD Variables

Add the following variables to your GitLab CI/CD settings:

Settings → CI/CD → Variables

VariableValueProtectedMasked
SLACK_WEBHOOKYour webhook URL✓✓
SLACK_CHANNELChannel name (e.g., #releases)✓✗

Important:

  • Mark SLACK_WEBHOOK as Protected and Masked for security
  • Only protected tags will trigger the webhook
  • The SLACK_CHANNEL variable is optional; if not set, it uses the default channel from the webhook

3. Update CI/CD Configuration

The .gitlab-ci.yml release job needs to pass the Slack webhook environment variables to the GoReleaser Docker container.

Add the following lines to the docker run command in the release job:

diff
+      -e SLACK_WEBHOOK=$SLACK_WEBHOOK \
+      -e SLACK_CHANNEL=$SLACK_CHANNEL \

Notification Format

The Slack notification is a single markdown block, so headings, bold text, and links render in Slack. It includes:

  • Release version
  • Changelog grouped by conventional commit types, in this order:
    • Features - New functionality (feat:)
    • Bug Fixes - Bug fixes (fix:)
    • Documentation - Documentation updates (docs:)
    • Maintenance - CI changes, refactoring, other chores (chore:, ci:, refactor:)
    • Dependencies - Dependency updates (chore(deps):, chore(dependencies):)
    • Others - Everything else
  • Go module bumps - When a release has two or more update module commits, Slack shows them as a single * N Go module updates line under Dependencies. The Go version bump, a single module bump, and other dependency lines stay listed.
  • Commit information - Each entry has a bold type(scope): prefix, a linked commit hash, and the author name. Author emails are not included.
  • Author emoji - 🤖 for gitlab-bot@gitlab.com, :tanuki: for other @gitlab.com authors, and :community: for everyone else.
  • Link to the GitLab release page

Release notes longer than 10,000 characters are cut and end with …, to stay under Slack's 12,000-character limit for a markdown block.

Example Notification

markdown
🚀 **glab v1.120.0** has been released!

### ✨ Features
* **feat(df):** add package command to check a single PURL ([c81a40c8](https://gitlab.com/gitlab-org/cli/-/commit/c81a40c8)) by Michael Eddington :tanuki:
* **feat(stack):** add a command to delete a stack ([6d7a7473](https://gitlab.com/gitlab-org/cli/-/commit/6d7a7473)) by Maksym Tymoshyk :community:

### 🐛 Bug Fixes
* **fix(mr):** fast-forward a checked-out branch on repeat checkout ([cb7c3eb5](https://gitlab.com/gitlab-org/cli/-/commit/cb7c3eb5)) by Jeston Singh :community:

### 🔧 Maintenance
* **refactor:** remove the custom --project and --hostname flag pair ([729129ac](https://gitlab.com/gitlab-org/cli/-/commit/729129ac)) by Jean van der Walt :tanuki:

### 📦 Dependencies
* **chore(deps):** update module gitlab.com/gitlab-org/api/client-go/v3 to v3.15.0 ([ad728cd0](https://gitlab.com/gitlab-org/cli/-/commit/ad728cd0)) by GitLab Renovate Bot 🤖

[View release on GitLab](https://gitlab.com/gitlab-org/cli/-/releases/v1.120.0)

The GitLab release page uses the same changelog lines, without the author emoji, and lists every Go module bump individually.

Customization

Change Notification Format

In .goreleaser.yml:

  • Edit the text of the markdown block under announce.slack.blocks to change the Slack post. message_template is only the plain-text fallback shown in notifications.
  • Edit changelog.format to change each changelog line. This also changes the GitLab release page.

The changelog line writes the author type as a hidden HTML comment (<!--bot-->, <!--team-->, or <!--community-->). GitLab does not display it, and the Slack template replaces it with the author emoji.

Common template variables:

  • {{ .Tag }} - Release tag
  • {{ .Version }} - Version without 'v' prefix
  • {{ .ReleaseURL }} - GitLab release URL
  • {{ .ReleaseNotes }} - Generated changelog
  • {{ .ProjectName }} - Project name

Change Commit Grouping

Modify the changelog.groups section in .goreleaser.yml to adjust how commits are categorized. GoReleaser assigns each commit to the first group whose regexp matches, and order sets the display order. Keep Dependencies before Maintenance in the list, because the Maintenance pattern also matches chore(deps):.

Testing

Testing Slack notifications locally is challenging because:

  1. Snapshot mode skips announcements: Running goreleaser release --snapshot --clean will not send Slack notifications, as snapshot mode automatically skips the announce step. A passing CI pipeline does not exercise the Slack templates.
  2. GoReleaser Pro required: The goreleaser announce command (which would allow testing announcements separately) is only available in GoReleaser Pro
  3. Full release needed: To test announcements with the free version, you would need to do a full release (not recommended for testing)

The release jobs pin the GoReleaser image to v2.18.3. Earlier versions fail with slack blocks: failed to unmarshal when the configuration uses blocks.

Alternative: Test the Slack Webhook Directly

You can verify your Slack webhook works, and preview a markdown block, by sending a test message with curl:

shell
curl -X POST -H 'Content-type: application/json' \
  --data '{
    "text": "glab v1.0.0-test has been released",
    "blocks": [
      {
        "type": "markdown",
        "text": "🚀 **glab v1.0.0-test** has been released!\n\n### ✨ Features\n* **feat(mr):** test change ([abcd1234](https://gitlab.com/gitlab-org/cli/-/commit/abcd1234)) by Test User :tanuki:\n\n[View release on GitLab](https://gitlab.com/gitlab-org/cli/-/releases)"
      }
    ]
  }' \
  YOUR_SLACK_WEBHOOK_URL

To preview a block without posting it, paste the blocks JSON into the Block Kit Builder.

The most reliable way to verify Slack notifications work correctly is to:

  1. Test the webhook URL directly using curl (as shown above)
  2. Run goreleaser check to validate .goreleaser.yml
  3. Let the notification run during an actual release

Troubleshooting

Notifications not sending

  1. Verify SLACK_WEBHOOK is set and not expired
  2. Check that the webhook URL is correct
  3. Ensure the release job has access to protected variables
  4. Review GoReleaser logs in CI/CD pipeline

Wrong channel

  • Update the SLACK_CHANNEL variable
  • Or modify the webhook's default channel in Slack settings

Missing changelog entries

  • Ensure commits follow conventional commit format
  • Check changelog.filters.exclude in .goreleaser.yml for excluded patterns
  • Verify commits aren't filtered out by the exclude rules

References

1# Slack Release Notifications
3This project is configured to send automated Slack notifications when a new release is published using GoReleaser.
5## Setup
7### 1. Create a Slack Incoming Webhook
91. Go to your Slack workspace's [Incoming Webhooks](https://api.slack.com/messaging/webhooks) page
101. Click "Create New App" or use an existing app
111. Enable "Incoming Webhooks"
121. Click "Add New Webhook to Workspace"
131. Select the channel where you want release notifications
141. Copy the webhook URL (format: `https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX`)
16### 2. Configure CI/CD Variables
18Add the following variables to your GitLab CI/CD settings:
20**Settings → CI/CD → Variables**
22| Variable | Value | Protected | Masked |
23|-----------------|----------------------------------|-----------|--------|
24| `SLACK_WEBHOOK` | Your webhook URL | ✓ | ✓ |
25| `SLACK_CHANNEL` | Channel name (e.g., `#releases`) | ✓ | ✗ |
27**Important:**
29- Mark `SLACK_WEBHOOK` as **Protected** and **Masked** for security
30- Only protected tags will trigger the webhook
31- The `SLACK_CHANNEL` variable is optional; if not set, it uses the default channel from the webhook
33### 3. Update CI/CD Configuration
35The `.gitlab-ci.yml` release job needs to pass the Slack webhook environment variables to the GoReleaser Docker container.
37Add the following lines to the `docker run` command in the `release` job:
39```diff
40+ -e SLACK_WEBHOOK=$SLACK_WEBHOOK \
41+ -e SLACK_CHANNEL=$SLACK_CHANNEL \
42```
44## Notification Format
46The Slack notification is a single [`markdown` block](https://docs.slack.dev/reference/block-kit/blocks/markdown-block/),
47so headings, bold text, and links render in Slack. It includes:
49- **Release version**
50- **Changelog** grouped by conventional commit types, in this order:
51 - **Features** - New functionality (`feat:`)
52 - **Bug Fixes** - Bug fixes (`fix:`)
53 - **Documentation** - Documentation updates (`docs:`)
54 - **Maintenance** - CI changes, refactoring, other chores (`chore:`, `ci:`, `refactor:`)
55 - **Dependencies** - Dependency updates (`chore(deps):`, `chore(dependencies):`)
56 - **Others** - Everything else
57- **Go module bumps** - When a release has two or more `update module` commits, Slack shows
58 them as a single `* N Go module updates` line under **Dependencies**. The Go version bump,
59 a single module bump, and other dependency lines stay listed.
60- **Commit information** - Each entry has a bold `type(scope):` prefix, a linked
61 commit hash, and the author name. Author emails are not included.
62- **Author emoji** - 🤖 for `gitlab-bot@gitlab.com`, `:tanuki:` for other
63 `@gitlab.com` authors, and `:community:` for everyone else.
64- **Link** to the GitLab release page
66Release notes longer than 10,000 characters are cut and end with `…`, to stay under
67Slack's 12,000-character limit for a `markdown` block.
69### Example Notification
71```markdown
72🚀 **glab v1.120.0** has been released!
74### ✨ Features
75* **feat(df):** add package command to check a single PURL ([c81a40c8](https://gitlab.com/gitlab-org/cli/-/commit/c81a40c8)) by Michael Eddington :tanuki:
76* **feat(stack):** add a command to delete a stack ([6d7a7473](https://gitlab.com/gitlab-org/cli/-/commit/6d7a7473)) by Maksym Tymoshyk :community:
78### 🐛 Bug Fixes
79* **fix(mr):** fast-forward a checked-out branch on repeat checkout ([cb7c3eb5](https://gitlab.com/gitlab-org/cli/-/commit/cb7c3eb5)) by Jeston Singh :community:
81### 🔧 Maintenance
82* **refactor:** remove the custom --project and --hostname flag pair ([729129ac](https://gitlab.com/gitlab-org/cli/-/commit/729129ac)) by Jean van der Walt :tanuki:
84### 📦 Dependencies
85* **chore(deps):** update module gitlab.com/gitlab-org/api/client-go/v3 to v3.15.0 ([ad728cd0](https://gitlab.com/gitlab-org/cli/-/commit/ad728cd0)) by GitLab Renovate Bot 🤖
87[View release on GitLab](https://gitlab.com/gitlab-org/cli/-/releases/v1.120.0)
88```
90The GitLab release page uses the same changelog lines, without the author emoji, and lists
91every Go module bump individually.
93## Customization
95### Change Notification Format
97In `.goreleaser.yml`:
99- Edit the `text` of the `markdown` block under `announce.slack.blocks` to change the Slack
100 post. `message_template` is only the plain-text fallback shown in notifications.
101- Edit `changelog.format` to change each changelog line. This also changes the GitLab
102 release page.
104The changelog line writes the author type as a hidden HTML comment (`<!--bot-->`,
105`<!--team-->`, or `<!--community-->`). GitLab does not display it, and the Slack template
106replaces it with the author emoji.
108Common template variables:
110- `{{ .Tag }}` - Release tag
111- `{{ .Version }}` - Version without 'v' prefix
112- `{{ .ReleaseURL }}` - GitLab release URL
113- `{{ .ReleaseNotes }}` - Generated changelog
114- `{{ .ProjectName }}` - Project name
116### Change Commit Grouping
118Modify the `changelog.groups` section in `.goreleaser.yml` to adjust how commits are categorized.
119GoReleaser assigns each commit to the first group whose `regexp` matches, and `order` sets the
120display order. Keep **Dependencies** before **Maintenance** in the list, because the
121**Maintenance** pattern also matches `chore(deps):`.
123## Testing
125Testing Slack notifications locally is challenging because:
1271. **Snapshot mode skips announcements**: Running `goreleaser release --snapshot --clean` will not
128 send Slack notifications, as snapshot mode automatically skips the announce step. A passing
129 CI pipeline does not exercise the Slack templates.
1301. **GoReleaser Pro required**: The `goreleaser announce` command (which would allow testing announcements separately) is only available in GoReleaser Pro
1311. **Full release needed**: To test announcements with the free version, you would need to do a full release (not recommended for testing)
133The release jobs pin the GoReleaser image to v2.18.3. Earlier versions fail with
134`slack blocks: failed to unmarshal` when the configuration uses `blocks`.
136### Alternative: Test the Slack Webhook Directly
138You can verify your Slack webhook works, and preview a `markdown` block, by sending a test
139message with curl:
141```shell
142curl -X POST -H 'Content-type: application/json' \
143 --data '{
144 "text": "glab v1.0.0-test has been released",
145 "blocks": [
146 {
147 "type": "markdown",
148 "text": "🚀 **glab v1.0.0-test** has been released!\n\n### ✨ Features\n* **feat(mr):** test change ([abcd1234](https://gitlab.com/gitlab-org/cli/-/commit/abcd1234)) by Test User :tanuki:\n\n[View release on GitLab](https://gitlab.com/gitlab-org/cli/-/releases)"
149 }
150 ]
151 }' \
152 YOUR_SLACK_WEBHOOK_URL
153```
155To preview a block without posting it, paste the `blocks` JSON into the
156[Block Kit Builder](https://app.slack.com/block-kit-builder).
158### Recommended Approach
160The most reliable way to verify Slack notifications work correctly is to:
1621. Test the webhook URL directly using curl (as shown above)
1631. Run `goreleaser check` to validate `.goreleaser.yml`
1641. Let the notification run during an actual release
166## Troubleshooting
168### Notifications not sending
1701. Verify `SLACK_WEBHOOK` is set and not expired
1711. Check that the webhook URL is correct
1721. Ensure the release job has access to protected variables
1731. Review GoReleaser logs in CI/CD pipeline
175### Wrong channel
177- Update the `SLACK_CHANNEL` variable
178- Or modify the webhook's default channel in Slack settings
180### Missing changelog entries
182- Ensure commits follow [conventional commit format](https://www.conventionalcommits.org/)
183- Check `changelog.filters.exclude` in `.goreleaser.yml` for excluded patterns
184- Verify commits aren't filtered out by the exclude rules
186## References
188- [GoReleaser Slack Announce Documentation](https://goreleaser.com/customization/announce/slack/)
189- [GoReleaser Changelog Documentation](https://goreleaser.com/customization/changelog/)
190- [Conventional Commits Specification](https://www.conventionalcommits.org/)
Diagnostics5 git calls · 29 ms
CallStatusSizeTime029 ms
discover200185 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=185
git.server.agent=git/2.56.g1891de4-Linux
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch server-option object-format
git.server.fetch=shallow wait-for-done filter
git.protocol.version=2
git.pkt.frames=9
git.pkt.data=7
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=185
git.pkt.payload.max=35
ls-refs20058 KiB · hit4 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=4
git.response.bytes=59849
git.response.cache=HIT
git.response.duration_ms=4
git.protocol.version=2
git.pkt.frames=731
git.pkt.data=730
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=59849
git.pkt.payload.max=143
git.ls_refs.count=730
git.ls_refs.head=refs/heads/main
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit1 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=4273
git.response.cache=HIT
git.response.duration_ms=1
git.fetch.filter=combine:blob:none+tree:2
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=1
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=4273
git.pkt.payload.max=4173
git.sideband.band1.bytes=4173
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=11
git.pack.bytes=4173
git.fetch.wide.objects=11
git.fetch.wide.extra_bytes=3930
git.fetch.wide.blobs=0
fetchtree:0 · deepen 1020032 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=1
git.response.bytes=32926
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=22
git.pkt.data=20
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=32926
git.pkt.payload.max=32046
git.sideband.band1.bytes=32046
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=80
git.pack.bytes=32046
git.pack.ofs_delta=36
git.pack.ref_delta=0
git.pack.chain.max=2
git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91
git.pack.full=44
Open pack map
fetch2003.3 KiB · hit22 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=21
git.response.bytes=3388
git.response.cache=HIT
git.response.duration_ms=22
git.fetch.wants=1f9bf0e1f67930cb1612cdccdbcaee965d73eefb
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=3388
git.pkt.payload.max=3361
git.sideband.band1.bytes=3361
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://gitlab.com/gitlab-org/cli
Ref
refs/heads/main
Commit
0dd7574dce9e385c5c30540e6c15657adc6bdce9
cf-ray
a5e150d27f240acb
Request
d99d556f…
Protocol
v2 · sha1
Agent
git/2.56.g1891de4-Linux
Filter
advertised
Fetch
shallow wait-for-done filter
Capabilities
agent ls-refs fetch server-option object-format