Watching pipelines and notifications
Crow CI lets every user watch the pipelines they care about. A watch is personal: it only affects what you see and receive, never what other users see. Nothing is watched by default.
A watch has two independent channels:
- In-app: failing watched pipelines show up in the bell in the header and in the watching overview.
- Email: an optional email for the events you select.
To post outcomes of a repository or organization to a chat, use notification webhooks instead.
Watching a pipeline
Section titled “Watching a pipeline”Any user with pull access to a repository can watch its pipelines. Repository admin rights are not needed.
-
Open a pipeline
Open a pipeline of the repository in the Crow web UI.
-
Click Watch
Click Watch in the pipeline header. A panel titled with the watch label, for example Watch push → main, opens. The watch covers every future run with the same trigger.
-
Choose channels and events
Under Notify me, keep In Crow enabled to see failures in the header bell. Enable By email and select the events you want to receive under Email me when. Click Save.
Once a watch exists, the button reads Watching. Open the panel again to change the settings or click Unwatch.
You can also manage the watches of a repository in Repository Settings > Watches. This page is called “Your watched pipelines in <repo>” and is available to every user with pull access. Use Watch a pipeline to select an event and then a branch, cron job name or environment. The field after the event is labelled for that event, and tag and release watches take no value. A line below the fields says which runs the watch will cover, and Watch creates it.
A new watch has In Crow enabled, By email disabled and, once email is enabled, only the Pipeline fails event selected. At least one channel must stay enabled: the panel disables Save and the API rejects a watch with both channels off. With By email enabled, at least one event must be selected as well. To stop watching, click Unwatch. If the server has no SMTP configured or your account has no email address, By email is shown off, cannot be enabled and states the reason.
What a watch covers
Section titled “What a watch covers”A pipeline is a single run started by one trigger. A watch identifies a recurring pipeline by that trigger:
| Event | Watch key | Example label |
|---|---|---|
push |
event and branch | push → main |
manual |
event and branch | manual → main |
cron |
event and cron name | cron · nightly |
deployment |
event and target environment | deploy → production |
tag |
event only | tag |
release |
event only | release |
Pull request pipelines cannot be watched.
Watching applies to the pipeline as a whole, not to individual workflows. If any workflow of a run fails, the run counts as failing.
Which runs count
Section titled “Which runs count”Only genuine outcomes count: success, failure and error. An error counts as a failure, and so does a configuration error. Runs that were canceled or killed, declined, skipped, blocked, pending or still running are ignored. They never change the state of a watch and never send an email.
In-app overview
Section titled “In-app overview”The bell in the header shows the number of unread failing watches, plus your pipelines stuck in the queue.
The badge counts watches, not workflows, and is hidden at zero.
Click the bell to list the failing watches, unread first.
Only watches with In Crow enabled appear in the bell and count in the badge.
Each entry shows the repository, the watch label, the pipeline number, the failed workflows with the run each last failed in, for example build (#10), test (#12), and the time of the failure.
Click an entry to open that pipeline, or use Mark read to clear it from the badge.
Mark all read marks every entry at once.
The dropdown links to View all watched pipelines, the full overview at /user/watches.
Users without admin rights on a repository also find Your watches in the repository header.
It opens Repository Settings > Watches for that repository.
The overview has two tabs:
- Failing: your failing watches with the in-app channel enabled, grouped as Unread and Read, with Mark read and Unwatch.
- All watched: every watch across all repositories, including email-only ones, with its channels and the status of its last run, plus Edit and Unwatch.
The counter updates without a page reload when a watched pipeline finishes.
Unread and read
Section titled “Unread and read”- A failing watch is unread until you mark it as read.
- A read watch stays in the overview, greyed out, while it keeps failing, but it is not counted in the badge.
- A new failing run on a read watch makes it unread again.
- A watch leaves the overview on its own as soon as all of its workflows pass again, whether it was read or not.
- A watch you create while its latest run is already failing starts as read, so that the failure you are looking at does not bump the badge.
Workflows are tracked individually
Section titled “Workflows are tracked individually”Runs do not always contain the same workflows, because path filters and when conditions skip some of them.
Crow therefore tracks the state per workflow name within a watch.
A run only updates the workflows it ran, and skipped workflows keep their previous state.
For example, a push to main fails in the build workflow in run 10.
Run 11 is a docs-only push where only the docs workflow runs and passes.
After run 11, build is still failing and the watch stays in the overview until a run in which build itself passes.
The overview entry names the workflows that are still failing and links to the most recent run that failed.
A workflow that is removed from the configuration can never be fixed by a run. Crow stops counting it after 20 runs of the watch that do not contain it.
-
Configure SMTP on the server
Set the SMTP environment variables on the Crow server. At minimum,
CROW_SMTP_HOSTandCROW_SMTP_FROMare required:See the notification environment variables for details on each setting.
-
Enable email on a watch
Enable By email on a watch and select the events.
Emails are sent to the email address of your Crow account. One email is sent per user and per qualifying run. Without SMTP on the server, or without an email address on your account, the email option is disabled and explains why.
Events
Section titled “Events”| Event | Description |
|---|---|
| Failure | A run of the watched pipeline finished with a failure or error status. This is the default. |
| Success | A run of the watched pipeline finished successfully. |
| Status change | The watch as a whole flipped between failing and passing, following the per-workflow rules above. |
Because of the per-workflow tracking, a docs-only run that passes does not send a misleading “fixed” email while build is still failing.
Email content
Section titled “Email content”Notification emails contain:
- Repository name
- Pipeline number and status
- Branch and commit hash
- Commit message (first line)
- Link to the pipeline in the Crow web UI
Unsubscribing
Section titled “Unsubscribing”Every email contains an unsubscribe link. The link turns off the email channel of that single watch. If the in-app channel of that watch is off as well, the watch is deleted.
Notification webhooks
Section titled “Notification webhooks”Notification webhooks post pipeline outcomes to a chat or another service, so you can follow builds without an SMTP server. Unlike a watch, a webhook is shared: it belongs to a repository or an organization, and every admin of it sees and manages the same webhooks.
-
Create the webhook in the target service
For Discord, open Edit Channel > Integrations > Webhooks and copy the webhook URL. For Slack, Mattermost or Rocket.Chat, create an incoming webhook. For ntfy, use the topic URL, for example
https://ntfy.sh/my-topic. For Gotify, use the message URL with an application token, for examplehttps://gotify.example.com/message?token=…. -
Add the webhook in Crow
Open Repository Settings > Notification webhooks for one repository, or Organization Settings > Notification webhooks for every repository of an organization. Click Add webhook, select the service, paste the URL and select the events.
-
Send a test message
Open the row menu of the webhook and click Send test message. The result shows in the Last delivery column.
Repository admins manage the webhooks of a repository, and organization admins those of an organization. The webhooks of an organization apply to all of its repositories, in addition to their own webhooks.
Events and filters
Section titled “Events and filters”A webhook uses the same events as an email watch: Failure, Success and Status change. Status changes follow the per-workflow rules of watches, so a webhook says “fixed” only once every failing workflow passes again.
By default a webhook covers every pipeline that can be watched, which is every pipeline except those of pull requests. Set Event to cover one event only, and for push, manual, cron and deployment pipelines narrow it to one branch, cron job name or environment.
Services
Section titled “Services”| Service | Body |
|---|---|
| Discord | A message with an embed that links to the pipeline. Mentions in commit messages are not resolved. |
| Slack, Mattermost or Rocket.Chat | An incoming webhook message with a link to the pipeline. |
| ntfy | A plain text message with a title, a click link and a higher priority for failures. |
| Gotify | A message with a title, a click link and a higher priority for failures. |
| Crow JSON | Crow’s own versioned JSON, for your own receivers and automation tools. |
The Crow JSON body has this shape:
label is success, failure or error for the run, broken or fixed when the status changed, and test for a test message.
A test message has event set to test.
The X-Crow-Event header repeats event.
version only changes when a field is removed or changes meaning.
When a webhook has a signing secret, Crow sets two headers:
X-Crow-Timestamp: the Unix time of the delivery.X-Crow-Signature:sha256=followed by the hex HMAC-SHA256 of<timestamp>.<body>, keyed with the secret.
Compute the HMAC on the raw body and compare it in constant time. Reject old timestamps to stop replayed deliveries.
Delivery and security
Section titled “Delivery and security”Crow posts once per matching outcome and retries twice, after one and two seconds, when the service answers 429 or a 5xx status or cannot be reached. Each attempt times out after 10 seconds. Redirects are not followed. Delivery never blocks or fails a pipeline: an error only shows in the Last delivery column and the server log.
The webhook URL often is the credential of the webhook, so Crow never returns it and encrypts it at rest like secrets when encryption is configured. The settings only show its host. To change the URL, enter a new one.
Crow refuses webhook URLs that resolve to private, loopback, link-local or CGNAT addresses, so the setting cannot be used to reach internal services.
The check runs on the address Crow connects to, after name resolution.
To post to a service inside your network, an administrator lists its host in CROW_WEBHOOK_NOTIFY_ALLOWED_HOSTS.
Workflows stuck in the queue
Section titled “Workflows stuck in the queue”The bell also lists pipelines you triggered that have a workflow stuck in the queue, in a section above your failing watches. A workflow is stuck when it has waited longer than the server’s threshold (one hour by default) without starting, or when it waits on dependencies that finished without succeeding. Usually no agent matches the workflow’s labels, or the queue is paused. This does not depend on watching the pipeline: a pipeline counts as yours when your login on the repository’s forge is its sender, or its commit author when it has no sender, and you can read the repository.
Each entry names the stuck workflows and links to the pipeline. Stuck pipelines count towards the badge and have no read state. They leave the bell on their own once the workflow starts or is canceled. Workflows blocked on failed dependencies are skipped by the server within a minute, so they rarely stay listed.
When the administrator also sets CROW_QUEUE_STUCK_NOTIFY=true, Crow also emails you once, when a workflow of a pipeline you triggered first crosses the threshold.
See stuck workflows for the admin side.
The deprecated notify block
Section titled “The deprecated notify block”The notify: block in workflow files is no longer used.
It is still parsed so that existing pipeline files keep working, but its contents are ignored.
The linter reports a non-blocking deprecation warning, which says that the notify: block is deprecated and ignored and that you should watch the pipeline in the Crow UI instead.
Remove the block and watch the pipeline instead.
Admin SMTP status
Section titled “Admin SMTP status”Server administrators can verify the SMTP configuration in Admin Settings > Notifications. This page shows the configured SMTP host, port, and sender address (the password is never displayed). A Send test email button sends a test message to the configured sender address to verify connectivity.