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.

Breaking change

Watches replace the former repository-level email notifications. The repository notification settings and the emails sent to commit authors were removed. Existing repository notification settings are not migrated to watches. Anyone who relied on commit-author emails must create watches instead. The notify: block in workflow files is ignored and produces a deprecation warning.

Watching a pipeline

Any user with pull access to a repository can watch its pipelines. Repository admin rights are not needed.

1. Open a pipeline

   Open a pipeline of the repository in the Crow web UI.

2. 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.

3. 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 pick 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

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

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

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/watching. 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

• 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

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 actually 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.

Email

1. Configure SMTP on the server

   Set the SMTP environment variables on the Crow server. At minimum, CROW_SMTP_HOST and CROW_SMTP_FROM are required:

   CROW_SMTP_HOST=smtp.example.com
   CROW_SMTP_PORT=587
   CROW_SMTP_FROM=crow@example.com
   CROW_SMTP_USERNAME=crow@example.com
   CROW_SMTP_PASSWORD=secret

   See the notification environment variables for details on each setting.

2. 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

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

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

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.

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

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: “The notify: block is deprecated and ignored. Watch the pipeline in the Crow UI instead.” Remove the block and watch the pipeline instead.

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.