Announce a release to a chat channel¶

Goal: have a release say so in Discord, without a person posting it.

Configure the adapter¶

In .colophon.yaml:

announce:
  discord:
    webhook: $DISCORD_RELEASE_WEBHOOK
    when: minor

webhook names an environment variable. It is not the URL. A literal is refused when the file is parsed, because .colophon.yaml is committed and a webhook URL lets anyone holding it post to your channel.

when is the smallest release this adapter announces — any, patch, minor or major. It is the size of the release, not the shape of its version, so it works for a project whose versions are not semver. On such a project any is the sentence that means something.

Supply the webhook¶

Set DISCORD_RELEASE_WEBHOOK as a CI variable, masked and protected. Protected matters: if your release tags are protected — and they should be — an unprotected variable will not reach the tag pipeline, and the job will quietly announce nothing because it has no webhook to post to.

In this estate it is already a group-level variable, so most projects need no per-project setting.

Run it after the release exists¶

announce reads the release object, so it goes after the job that creates one:

announce:
  stage: release
  image: registry.gitlab.com/phpboyscout/images/release-tools:v0.1.12
  rules:
    - if: '$CI_COMMIT_TAG'
  needs:
    - job: colophon-release
  script:
    - colophon --ci announce --tag "$CI_COMMIT_TAG"

The needs is the part worth getting right. Without it the job may run before the release exists, and announcing a release that is not there is refused — correctly, since the announcement would link to nothing.

What you will see¶

$ colophon announce --tag v1.4.0
  announced  discord

A release too small for the filter:

  skipped    discord — a patch release, and this announces minor or larger

And a failure:

  failed     discord — 502 Bad Gateway

1 of 1 did not go out. The release stands; nothing here failed the pipeline.

The exit code is zero in all three cases. By the time this runs the release is public; a red pipeline over a chat message is worse signal than a yellow one. If you want a failed announcement to be loud, watch for the warning line rather than the job status.

If it announces twice¶

It will, if the job is retried. Announcing is the one thing colophon does that it cannot make idempotent — a webhook has no key to deduplicate on — so delivery is at least once and colophon does not pretend otherwise.

Retry a release job freely; retry the announce job only if you want the message again.

Why announcing is different has the reasoning.

If nothing is announced¶

See also¶

• colophon announce
• Announcing a release