Skip to content

Notifications ​

Tara sends notifications through notify kits and doesn't hard-code Telegram, email, or Slack. To add a new channel, you release a new kit and pin it in the configuration, with no change to Tara. This page is for administrators: install kits on the server, then let each organization's owners and admins choose their own channel.

What Tara notifies about ​

Tara emits five events, and each event goes to the channel of an organization.

EventWhenChannel ofRecipients
submission.pendingA submission to the official catalog passes the checks and awaits review (other stores have no review)The PhillipCLI platformStaff accounts of the admin console that are active, have the role moderator or super_admin and have an email
submission.approvedA submission is approved and releasedThe owning organizationThe author
submission.returnedA submission is returned, not counting when the author withdraws it themselvesThe owning organizationThe author
version.publishedA new version of an organization's resource is releasedThe owning organizationThe shared channel
version.yankedA version is yanked by an admin or a staff moderator, or removed for malicious code on a rescanThe owning organizationThe author

Tara doesn't yet store who follows which resource, so version.published and version.yanked go only to the organization's shared channel. Community resources belong to the organization of the person who submitted them.

The content is only metadata and links back to the Portal: name, version, author, and the person who acted. The reason for a return and the submission content stay on the Portal.

Events from Bandum and Ryoma ​

Besides its own five events, Tara carries events sent by Bandum and Ryoma to the same channels, so those services don't need a channel of their own. The owners and admins of an organization pick them in Settings, Notifications, in two groups: Bandum (testing and releases) and Ryoma (usage and delivery).

  • Bandum: bandum.awaiting_test, bandum.rejected, bandum.test_overdue, bandum.ready_for_release, bandum.release_succeeded, bandum.release_failed.
  • Ryoma: ryoma.quota, ryoma.telemetry_gap, ryoma.task_risks, ryoma.digest, ryoma.guardrails.

The sender calls POST /v1/orgs/{org}/notify/events with a service account that has the scope scm (the same kind of token Ryoma uses for scm/token). A session, a personal token or an owner gets 403.

json
{"kind":"bandum.rejected","key":"rejected:o/r#12@1731990000","subject":"[Bandum] GH-12 was sent back","text":"...","link":"https://bandum.example/acme/tasks/o/r/12","to":["a@x.com"]}
  • kind and key are required, and kind must be one of the events above. key (1 to 300 characters) prevents duplicates: the same key for the same organization within 30 days answers 202 with {"queued":0,"duplicate":true} and sends nothing.
  • subject (at most 200 characters, one line), text (at most 4000) and an optional link (an http or https URL) are sent as written, without a [Tara] prefix.
  • to (at most 50 emails) is narrowed to members of the organization, ignoring case. Other addresses are dropped silently, so Tara can't be used to send spam. The recipients only matter to channels that send to individuals, such as email.
  • The answer is 202 with {"queued":N,"duplicate":false}, where N is the number of channels that receive the event. N is 0 when no channel takes this kind, or when the server has no notify kit pinned.

The platform organization doesn't take these events.

Built-in channels ​

Tara ships with four notify kits.

KitChannelMain settings
kit-notify-telegramTelegram group through the Bot APIchatId, apiUrl
kit-notify-emailSMTP (STARTTLS, TLS, AUTH PLAIN)host, from, recipients, sendToPerson, security
kit-notify-slackSlack channel, through an Incoming Webhook or a bot tokenchannel, apiUrl
kit-notify-zaloZalo Official Account, advisory messages to individualsuserIds, apiUrl

Zalo has its own Zalo OA limits: a message goes out only within 7 days of the recipient's last interaction with the OA and only if they have not blocked it (free in the first 48 hours, charged after that), and the access token is short-lived, so an operator must renew it before expires_in ends. Treat Zalo as a secondary channel.

Each channel has a step-by-step guide with pictures. Pick one below.

Install kits on the server ​

The server downloads the kit from Tara by the sha256 you pinned, verifies the digital signature and the yank list, then runs the kit in a separate Node.js process with node --permission. The kit can read only its own directory, can't write files, can't run child processes, and can't see Tara's environment variables. You need Node.js 22.13 or later on the server.

Sending happens outside the user's action. Tara queues the notification in the same transaction as the change, so if the transaction is rolled back, no notification goes out. Transient errors, such as a network problem or a channel that isn't up yet, are retried up to 8 times with increasing intervals. Configuration errors, such as a wrong token or missing settings, stop immediately and are logged for an admin to fix. A failed send never breaks a review or submission action.

Configure the server with these variables.

VariableNotes
TARA_NOTIFY_PLUGINSComma-separated list of name@version:sha256. Get the sha256 on the resource page. If empty, Tara sends nothing
TARA_NOTIFY_TOKENRead-only Tara token to download kit packages. Required when you pin kits from Tara
TARA_NOTIFY_URLWhere to download kit packages, default TARA_PUBLIC_URL. Set an internal address if the API can't reach the public address itself
TARA_NOTIFY_KEYSed25519:<base64> public key to verify kit signatures, default Tara's own signing key
TARA_NOTIFY_SETTINGSJSON of default settings for each kit, for example the email host and sender address
TARA_NOTIFY_SECRET_<KIT_NAME>The platform's shared secret for the kit, for example TARA_NOTIFY_SECRET_KIT_NOTIFY_TELEGRAM for the bot token. Organizations without their own secret use it
TARA_NODE_BIN, TARA_PLUGIN_CACHEThe Node.js command (default node) and the directory where kits are extracted

The shared secrets live only in the server's environment. On Kubernetes, put them in the chart's Secret, and pass non-secret variables through config.* or api.extraEnv. Both tara-api (test sends) and the worker (real sends) read this same configuration.

Choose a channel for each organization ​

An organization's owner or admin chooses a channel for their own organization, after signing in with a browser session. The channels of the official catalog (platform organization) are managed by a super_admin on the Notifications page of the admin console, not in the Portal. On the Portal, open the account menu, choose Admin, open Notifications, choose a pinned kit, enter the channel-specific configuration such as chatId, choose the events to receive, then send a test.

On the command line, view the current channel with ph tara notify, set a channel with ph tara notify set, and send a test or remove a channel with ph tara notify test and ph tara notify remove.

bash
ph tara notify set acme kit-notify-telegram --set chatId=-1001234567890 --events submission.pending,version.yanked
ph tara notify test acme kit-notify-telegram

To give a channel its own secret (a bot token or webhook), add --secret-stdin: Phillip reads one line from stdin, or asks with hidden input in a terminal. It never takes the secret from an argument and never prints it.

bash
printf %s "$BOT_TOKEN" | ph tara notify set acme kit-notify-telegram --set chatId=-1001234567890 --secret-stdin

Without --secret-stdin the current secret is kept. --clear-secret removes it, so the channel uses the server's shared secret if there is one (the two flags can't be combined). ph tara notify list shows each channel's secret source: own secret, platform or missing, and the event names you can pass to --events.

An organization's settings override the server's default settings. Tara rejects setting names that look like secrets, such as token, secret, or password: a secret has its own field, described next. Every channel change is recorded in the log, without the settings values. The matching API endpoint contains channel configuration, so it isn't published in the API reference.

An organization's own secret ​

On a hosted Tara, each organization pastes its own bot token, webhook URL, access token or SMTP password in the Notifications form, so it doesn't depend on the platform's shared bot.

  • The secret is encrypted with the same key as SSO secrets (TARA_SECRET_KEY, or Vault Transit) and stored in the database. Without a key, saving a secret fails with "This server has no key to store secrets (TARA_SECRET_KEY)". The encrypted value is bound to the organization and the kit, so copying it elsewhere doesn't work.
  • The secret is write-only. The API never returns it (it only says hasSecret), it never appears in logs or the audit log, and it isn't part of an organization's data export. Leaving the field empty keeps the saved secret; Remove deletes it. Deleting the organization deletes the channel row too.
  • For each kit, the server reports whether TARA_NOTIFY_SECRET_<KIT_NAME> exists (without its value). If a kit needs a secret and there is neither an own nor a shared one, saving is refused.
  • If a saved secret can't be decrypted (for example the key changed), sends fail with a configuration error and aren't retried. Paste the secret again.

Destination settings need your own secret ​

Setting names that define where to connect, or how, can only be set on a channel that has its own secret. Otherwise an organization could point apiUrl or host at its own machine and receive the platform's shared secret. A name counts as a destination setting when it contains url, uri, host, port, endpoint, server, security, tls, from, helo or proxy (any letter case), or ends in user or username. Names such as recipients, chatId, channel, userIds and sendToPerson are not affected.

  • Channels that use the platform's secret can't have these settings. Saving fails with "apiUrl can only be set together with your own secret", and an older row that still has them has them ignored when sending (logged once). The mail server and sender address come from TARA_NOTIFY_SETTINGS.
  • Channels with their own secret can set them, but a value can't point to localhost, a private network, link-local or cloud-metadata addresses, CGNAT, or a name ending in .local or .internal. TARA_NOTIFY_SETTINGS is set by you and isn't checked, so a local Mailpit still works in development.
  • Tara checks the value only when it's saved. A public name that later resolves to an internal address (DNS rebinding) isn't caught, so also restrict outbound traffic of the API and worker at the network level.

Test a kit with ph kit check ​

Before you pin a kit on the server, test it from your own machine. Pass the token through the PHILLIP_KIT_TOKEN variable, not through a parameter.

bash
PHILLIP_KIT_TOKEN=... ph kit check kit-notify-telegram --set chatId=-1001234567890 --send "test"

The command checks the contract and the required settings. With --send, the command sends a real notification to the channel, and --live calls check() to confirm the token and the destination without sending anything. A Slack webhook has no API to check without sending, so for this channel check() checks only the format, and you need --send for a real test.

Alerts from Bandum ​

Bandum also sends alerts through notify kits and contains no provider code. When nothing is configured, Bandum only writes alerts to the log. You declare the kit with environment variables, and each environment chooses its own kit and version:

sh
BANDUM_NOTIFY_PLUGINS=kit-notify-telegram@<version>:<package sha256> # both from the Tara resource page
BANDUM_NOTIFY_SETTINGS={"kit-notify-telegram":{"chatId":"-100123"}}
BANDUM_NOTIFY_SECRET_KIT_NOTIFY_TELEGRAM=<bot token>

Bandum downloads the package with BANDUM_TARA_TOKEN, then verifies the sha256, signature, and yank list before running it.

Set up a channel ​

Further reading ​