Automations

Some work should start without anyone asking for it. An automation is a task you set up once: an agent, the code it checks out and what to do. It runs whenever its trigger fires, either on a schedule or when another service sends it a request. Sentry reports a new error, and an agent looks into it. Monday morning comes around, and an agent updates your dependencies.

A few things teams set up:

• Fix new errors. Sentry sends each new issue, and the agent finds the cause and opens a pull request when the fix is clear.
• Look into alerts. Grafana, Alertmanager or PagerDuty sends an alert, and the agent investigates in a chat thread with your on-call people. That’s a response.
• Keep things up to date. Every Monday, the agent upgrades dependencies, runs the checks and ships what passes.
• Tidy up on a schedule. Every night, the agent goes through flaky tests from the day’s CI runs, or looks for issues that were fixed and never closed.

Two ways to start

A schedule comes due. Pick a schedule, such as Weekdays at 09:00, or write a cron expression, and a timezone. Runs then happen at that time in that zone, daylight saving included. A schedule can fire every five minutes at most. If Ryph is down when a slot comes due, that slot is skipped, and the next one runs as usual.

Another service sends a request. Ryph gives the automation its own URL, and anything that can send a webhook can start it. Ryph knows how these services sign and shape their requests:

A request without a valid secret is refused, so knowing the URL isn’t enough to start a run. For a known service, Ryph also reads what the request is about: its title, whether it’s firing or resolved, and which alert or issue it is. For Something else, you can point Ryph at those fields in your own payload.

Set one up

Go to Triggers, click New trigger and choose Webhook or schedule.

1. Trigger

   Under Starts when, choose A schedule comes due or Another service sends a request. For a schedule, pick it and the timezone. For a request, pick your service under What sends it?, and Ryph fills in how requests are checked. This choice is fixed once the automation exists.

2. Response

   Start a run gives each fire a run of its own. The other options open a conversation in a chat channel and put the agent in it, where later fires about the same thing join it. Responses explains them.

3. Agent and code

   Pick the Agent, and what it Checks out: a repository and branch, or a workspace.

4. Instructions

   Write what the agent should do each time, as you’d write a task. Then review it and click Create automation.

5. Connect your service

   For a request, Ryph shows the URL and the values to paste into your service, step by step. Copy the secret now, since Ryph shows it only once. For a service that signs with its own secret, paste its secret into Ryph. Ryph then waits for the first request and links the run it starts.

The instructions stay fixed

Every fire runs the same instructions, with the same agent and the same code. What a service sends is attached below them, as context: the first 16 KB of the request, marked as untrusted data from outside. So a request can tell the agent what happened, and it has no way to change what the agent is asked to do.

That matters because requests carry text from anywhere. An alert can include log lines, and an error can include whatever a user typed. If that text tries to talk the agent into something, the agent is still held by everything that holds any run: its permissions, its network allowlist and Ryph’s forge. Anything it wants to remember for future runs waits in the memory inbox for a person to accept.

If a secret leaks, the worst anyone can do with it is run your automation again, up to its rate limit. Replace the secret on the automation’s page, and the old one stops working at once.

Watch it and pause it

Each automation has a page under Triggers:

• Activity lists every fire: the runs it started, and the fires that started nothing, with the reason, such as Rate limited or Refused.
• Pause stops new runs. Requests that come in while it’s paused are refused, and Resume opens it again.
• Replace secret makes a new secret, or takes one you paste, for when it was lost or leaked.
• Fires a minute, at most caps how many runs a webhook can start, one a minute by default. A misconfigured alert that fires every few seconds then can’t start a run every few seconds. Requests over the cap are dropped and show in Activity.

Whose runs they are

An automation’s runs belong to the person who made it. Every fire checks again that they can still write to the repository, and that their account is linked on its forge. Take away their access, and the automation stops starting runs.

Members can make automations and manage their own. Operators and owners can manage everyone’s.