Automation rules

An automation rule watches for a trigger, checks conditions, and runs actions on the work items it selects.

Anatomy of a rule

A rule has a name, a project, an enabled flag and a trigger. It is written as a list of steps that run in order for each work item the trigger selects:

condition: stops the list when it is false.
if / else: tests a list of conditions (1 to 20, all or any) and runs a then or an else list of steps.
action: does something to the work item.
branch: runs its steps for related work: the item’s children, its parent or epic, work linked to it (optionally of one link type), the work this run created for it, or the work a JQL query finds as the rule’s actor.

Limits: 50 steps, 25 actions, 3 levels of nesting and 5,000 executed steps per run. Branches reach work in the rule’s project only, up to 100 items each and 500 in a whole run. Past that the run fails and changes nothing. Conditions see the earlier actions of the same run, and the actions of one run are atomic: a failed run rolls back all its changes.

Triggers

Trigger	Starts when
`issue.created`, `issue.updated`, `issue.transitioned`	A work item is created, changed or moved to another status
`issue.commented`	A new comment, by a person or another rule
`issue.assigned`	The assignee changes to someone
`issue.field.changed`	Any of 1 to 10 chosen fields changes (summary, description, type, status, priority, assignee, reporter, story points, labels, sprint, epic, due date, fix versions, components)
`issue.worklogged`	A work log is added, edited or deleted
`sprint.started`, `sprint.completed`	A sprint starts or completes. On completion the rule acts on the items still in the sprint.
`version.released`	A version is released, also by a Kanban board’s release
`scheduled`	On a schedule, see below
`manual`	A person runs the rule
`webhook.received`	A signed request arrives, see below

Development triggers. What GitHub and GitLab report through a development integration can also start a rule on the linked work items: dev.branch.created, dev.commit.created, dev.pullrequest.created, dev.pullrequest.merged, dev.pullrequest.declined, dev.build.succeeded, dev.build.failed, dev.build.changed, dev.deployment.succeeded, dev.deployment.failed and dev.deployment.changed. Deployment triggers can be limited to 1 to 10 environments. A rule starts only on news: a delivery sent again, an older report or a report of the same state starts nothing. These triggers depend on the GitHub and GitLab integration, which is also in development.

A rule can be told whether events caused by another rule’s run may start it (allowRuleTrigger). A person’s own action always may. A chain of rules stops after five rules, and no rule runs twice in one chain.

Schedules

A scheduled rule runs every N minutes (1 to 10,080), or on a calendar schedule: daily, weekly or monthly, with an interval, an IANA time zone, a local time, and the weekdays or day of month.

The time is a wall-clock time in the zone and is kept across daylight saving changes. On the day the clock skips the time, the rule runs when the clock jumps (02:30 runs at 03:00). When the clock goes back it runs once, at the first 02:30.
A month without the chosen day is passed over.
A run missed while the server was down still starts within 15 minutes, never twice, and never for a time before the rule was created.
A scheduled rule may select its work with a JQL query (up to 2,000 characters). Each run takes the first 500 matching work items, oldest first, and records that it was truncated when more match. The next run takes what still matches.
You can check a calendar schedule without saving: Orbit shows the next five run times.

Conditions

Field tests: equals, not_equals, contains, not_contains, starts_with, empty, not_empty, greater_than, less_than, in, not_in and changed (the event that started the run changed the field, optionally from and to given values). Status names resolve against the project’s catalog.
JQL: the work item matches a query, evaluated as the rule’s actor. See Search and JQL reference.
Related work: children, parent or linked work exist, or all, any or none of it matches a query.
Initiator: who made the change that started the run, by account or by project role.

Actions

assign, transition, set_priority, add_label, remove_label, comment, notify, edit (summary, description, priority, assignee, due date, story points, labels), create_issue, link and web_request. A web request is queued with the run, so a failed run sends nothing, and it is sent after commit to public addresses within 10 seconds, with up to three attempts for network errors, 429 and 5xx answers.

Project secrets. A project keeps named credentials for web requests. A request names one as {{secret.name}} in its URL or a header value, for example Authorization: Bearer {{secret.github}}. The value never appears in a rule, its versions, its export or its run history, and is never returned by the API. Headers that carry credentials must use a secret. A project holds at most 100 secrets, and creating, rotating and deleting them is audited.

Smart values

A comment body, notification, label, summary, link target, or web request URL, header or body can include values such as {{issue.key}}, {{issue.summary}}, {{project.key}}, {{initiator.name}}, {{changes.<field>.from}}, {{comment.body}}, {{sprint.name}}, {{version.name}} or {{webhook.<path>}}, with up to four filters: upper, lower, trim, json, url, raw. Each value is escaped for its place: as a URL component in a request URL, as the content of a JSON string in a body, as one line in summaries. Unknown names or filters are refused when the rule is saved.

Scope and actor

Scope. A rule belongs to a project, may apply to up to 20 projects, or may be global and apply to every project of the site. Saving a rule across projects needs administration of each. Only site administrators manage global rules.
Actor. A run acts as owner (the rule’s creator, the default), initiator (the person whose action started it) or a service account of the site. Only the account’s owners and site administrators can save a rule that acts as it. The actor needs write access to the project, and the run reaches only work items the actor may read. See Service accounts and API tokens.

Versions and publishing

Saving edits the draft. Until a rule is first published, the draft runs. Afterwards the published version runs and draft edits wait for the next publish. Project administrators publish with an optional note, list versions, and restore an old version into the draft. Versions are never changed or removed.

Run audit, retry, cancel and replay

Every run keeps its trigger, attempts, timings and up to 200 steps with their outcome and error. Runs started by an event that fail outside their own steps are retried (after 2, 4, 8 and 16 seconds) and give up as failed after five attempts. Project administrators can:

cancel a waiting or running run. A running run stops before its next action and rolls back.
replay a failed, cancelled or skipped run, with an idempotency key so the same replay runs once.

Readers see only runs on work they may open. A rule runs at most 500 times an hour.

Usage and the monthly quota

Each ended run adds to the usage of its rule for the UTC day. A run that reached an action counts against the site’s monthly quota. Site administrators are notified when the site reaches 80% and 100% of the quota. Once it is used up, every run is recorded as skipped until the month ends. Per-rule, per-project and site usage are available to administrators.

Copy, export and import

A rule can be copied to the same or another project, and exported as an orbit.automation/v1 file. Records of the site travel as logical references that import resolves in the target project, and secrets are never exported, only their names. Import supports a dry run.

Signed incoming webhook

A rule with the webhook.received trigger runs when its own signed request arrives. Project administrators create the secret, which is shown once, and a new secret stops the old one. The response includes the URL to post to.

The request carries the header Orbit-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the secret> and a JSON body of at most 64 KiB:

{
  "issues": ["ORB-12", "ORB-13"],
  "data": { "deploy": { "id": "d-4512", "result": "ok" } }
}

issues names up to 100 work items of the rule’s project by key or id. data is available to smart values as {{webhook.deploy.result}}.

# WEBHOOK_URL and WEBHOOK_SECRET come from creating the rule's webhook.
body='{"issues":["ORB-12"],"data":{"deploy":{"result":"ok"}}}'
t=$(date +%s)
sig=$(printf '%s.%s' "$t" "$body" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -hex | sed 's/^.* //')
curl -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "Orbit-Signature: t=$t,v1=$sig" \
  --data "$body"

The request runs the published rule at once as the rule’s actor, on the named work items only, and answers with the run’s status. A request more than five minutes off the clock answers 401 webhook_signature_expired, and a missing or wrong signature answers 401 webhook_signature_invalid. Sending the same signed request again returns the first run instead of running twice.