Telegram | HookCI docs

Telegram is meant to be a lighter alternative to Slack for people who want CI results on their phone without a workspace. It reports the same runs that GitHub Checks does. It does not change how checks run: your agent still executes everything on your server, and the hub only relays results.

What it will do

Post a message when a run fails, passes, or needs approval, depending on your notify settings.
Show the repo, branch, short SHA, author, and a line per job with its state and duration.
Offer inline buttons on each message: view logs, open in GitHub, and approve for fork pull requests waiting on a decision.
Work in a private chat with the bot or in a group where you add it.

Illustration. Design of a failed run message with inline buttons.

Connect flow (design)

Install the GitHub App and pair an agent as described in Pair an agent. Telegram only adds a notification target, so a working agent comes first.
Open the HookCI bot in Telegram and send /start. The bot replies with a one-time link code.
Enter the link code in the hub, or send it from the chat as the bot instructs, to bind the chat to your GitHub installation.
In the chat, choose the repos to watch, for example:
```
/watch acme/web
```

Link codes are expected to be single use and short lived, like pair tokens. The bot never asks for your GitHub or Telegram password.

Commands (design)

These mirror the Slack commands in Slack. The exact set is not final.

Command	Intended behaviour
`/watch owner/repo`	Report runs for this repo in this chat.
`/unwatch owner/repo`	Stop reporting this repo.
`/status`	Show agents and recent runs.
`/retry`	Retry the last failed run.
`/help`	List commands.

Configuration (design)

Per repo behaviour is expected to live in .hookci.yml next to the Slack settings. The telegram key below is a design placeholder and is not accepted by the current schema.

notify:
  telegram: { on: [failure], notify: normal }

on and notify are intended to take the same values as notify.slack: see the .hookci.yml reference.

Data

Telegram messages are expected to carry the same metadata as Slack messages: repo, branch, SHA, job names, states, durations, and a signed link to logs. Source code is not sent. See Security and data.