Skip to main content

Automation

Rules deliver a published release note where its readers already are, and a public changelog publishes it for anybody to read.

Rules​

A rule delivers a published release note where its readers already are. Open Automation in the sidebar, which administrators alone can see. A rule names what makes it run, the project it watches (or every project), and the actions it carries out, in order. Each action names the audience and language whose note it delivers.

The automation rules with their triggers and whether each is enabled; a webhook path is covered

Five things can make a rule run:

Runs whenWhat it needsWhat happens
Release publishedNothingEvery matching rule fires once per release
Run by handA published release and a request IDThe same request ID is the same run, never a second delivery
On a scheduleOne published release, a six-field cron expression, and an IANA time zoneThe release is delivered again on that schedule. Firings missed while ReleaseFlow was down become one catch-up run
Before a planned releaseA notice of 0 to 365 daysAn approved release with a planned time is announced that long before it. Moving the release earns one more reminder
Called by another systemNothing; ReleaseFlow mints the path and the secretA signed call names a published release and starts a run

A schedule and a reminder take only the actions that tell people something — Slack, email, and Microsoft Teams: nobody is watching when they go off. A schedule takes its project from the release it repeats. Preview next run on the page, or POST /api/automation/rules/cron-preview, says when an expression would next fire before any rule keeps it.

Trying a cron schedule in a time zone: the page says when it would run next

Write the rule first; it starts disabled. Enabling it is the moment ReleaseFlow checks that the deliveries can be made: the project and every audience belong to your Organization, the language is one your Organization writes notes in, a GitHub Release action's project has exactly one connected GitHub source, the deployment can carry the action out at all, and the configuration and secret are usable. A rule that is refused says which of those failed.

The rules table with one rule marked as delivering a retired audience; another rule's call path is covered

Actions​

Eight kinds of action exist:

ActionWhat it needsWhat it does
GitHub ReleaseThe project's own connected GitHub source and its access tokenPublishes the note as the release of the version's tag, marking the body so a repeat knows its own work
SlackAn incoming webhook URL, which is the action's secretPosts the note to the channel in Slack's own mrkdwn, up to 39,000 characters
EmailRELEASEFLOW_AUTOMATION_EMAIL_FROM and an SMTP serverSends the note to between 1 and 100 addresses
Public changelogNothingPublishes the note on your own changelog page and RSS feed
NotionThe parent page's id and an integration tokenFiles the note as a child page titled Release <version>, up to 450,000 bytes
ConfluenceA Cloud site, the account's email, a numeric space id, an optional parent page, and an API tokenCreates a page titled Release <version> in that space, up to 2,000,000 bytes
Microsoft TeamsThe Workflows callback URL, which is the action's secretPosts the note as plain text into the chat or channel the flow targets, up to 28 KiB of request
ZendeskA subdomain, an OAuth client ID and secret, a numeric section, and an optional user segmentPublishes the note as a Help Center article in the action's language, up to 1,000,000 bytes

A rule that runs when a release is published, with nine actions in order; the Atlassian site and the Notion page are covered

A Slack webhook URL must name an origin the deployment allows — hooks.slack.com or hooks.slack-gov.com unless RELEASEFLOW_SLACK_ALLOWED_HOSTS says otherwise — and is checked again before every delivery. A Confluence site is checked the same way, against the shape rather than a list: it must be exactly one label beneath atlassian.net over HTTPS, with nothing after the host. A Notion page id is the 32 hexadecimal characters Notion shows, with or without dashes. A Microsoft Teams callback must be the HTTPS Workflows URL the flow displays — one label beneath environment.api.powerplatform.com, the Workflows trigger path, and its own sig signature — and a Zendesk subdomain is one label, not a URL, so the only help centre an action can reach is its own. A Confluence page carries an HTML comment naming the run that wrote it; nothing reads it back, so a delivery Notion or Confluence never confirmed stays unknown until a person says a second page is acceptable. A secret is write-only: once stored, no response, page, or log ever repeats it, and leaving the field empty while editing keeps the one already there.

The GitHub Release a rule wrote from the contributor note

The email a rule sent with the published note

The Slack message a rule posted for the release

The Notion page a rule created for the release

The Confluence page a rule created for the release

A rule another system calls​

Saving a rule that runs when another system calls it gives it a path and a 256-bit secret, both shown once. Rotate secret replaces the secret and keeps the path; the old secret stops working at once.

The secret of a rule another system calls, shown once after Rotate secret; covered here

A call is a POST to that path with {"releaseId": "…"} and three headers:

HeaderWhat it holds
X-ReleaseFlow-TimestampSeconds since the epoch, within five minutes of now
X-ReleaseFlow-DeliveryA UUID, repeated on a retry so nothing is delivered twice
X-ReleaseFlow-Signature-256sha256= and the hex HMAC-SHA256 below

The signature covers the timestamp, the delivery, the uppercase method, the request path, and the hex SHA-256 of the body, each on its own line:

bash
BODY='{"releaseId":"<release>"}'
TS=$(date +%s)
DELIVERY=$(uuidgen)
PATH_='/webhooks/automation/<webhook>'
DIGEST=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | cut -d' ' -f2)
SIGNATURE=$(printf '%s\n%s\nPOST\n%s\n%s' "$TS" "$DELIVERY" "$PATH_" "$DIGEST" \
| openssl dgst -sha256 -hmac "$SECRET" -hex | cut -d' ' -f2)
curl -X POST "http://localhost:8080$PATH_" \
-H "X-ReleaseFlow-Timestamp: $TS" \
-H "X-ReleaseFlow-Delivery: $DELIVERY" \
-H "X-ReleaseFlow-Signature-256: sha256=$SIGNATURE" \
-H 'Content-Type: application/json' -d "$BODY"

The answer is 202 with {"runId", "status", "statusPath"}. A signed GET of that statusPath says how the run ended. The Organization is the rule's, never the body's. A body over 64 KiB is 413; an unknown path, a rule that is turned off, a moment more than five minutes out, and a wrong signature are all 401.

Runs​

Publishing a release records that it happened and nothing more, so a rule nobody can carry out never holds up a release. Within a second the worker creates one run per matching rule and walks its actions in order. The run history shows each delivery and how it ended. The first action that fails stops the ones behind it, and Run again repeats only that one. An action whose outcome nobody could confirm — a connection that dropped after the request went out, or a worker that stopped for five minutes — is recorded as unknown and never sent again on its own; repeating it asks you to confirm the delivery may happen twice. Cancel lets the action already on its way record its result and stops the rest.

An action for an audience that has been retired is skipped with audience_retired before it calls anything: nothing is sent for it, the actions behind it still run, and a run whose other actions succeed succeeds. The run history marks the action Skipped and says why, and the Automation page marks a rule that still delivers a retired audience. Enabling such a rule is refused with 409 automation_audience_retired; point the action at an active audience, or bring the audience back, first. An action's status through the API is PENDING, RUNNING, SUCCEEDED, FAILED, UNKNOWN, CANCELLED, or SKIPPED.

An action whose note has nothing for its audience is skipped too, with nothing_for_audience: no change the release includes concerns that audience, so its note holds only the title, the release summary, and the line saying nothing in the release concerns it. Nothing is sent, so no public changelog entry, page, article, or message says only that, and the rest of the run goes on as for a retired audience. It is decided when the action runs, for every trigger, from the release's changes by the same rule that chooses a note's changes (see Release Notes), never from the note's text. The checks come in this order: a retired audience is skipped with audience_retired; an action with no ready note fails with release_note_missing; a note a person edited is delivered as written, whatever its changes say; and only then is a note with nothing for its audience skipped. To deliver such a note on purpose, edit it before publishing. Enabling a rule is never refused for it, because a rule outlives every release.

The changes are read as they are when the action runs, so a published note and its skip can disagree. If a review clears a change's breaking flag after publication, or the AI is asked for a narrative it lacked, a change the note lists may no longer concern the audience, and running the rule again skips a note that has something to say. The other way round, a note that says nothing concerns its audience is delivered once one of its changes does. See ADR-0035's amendment.

A rule&#39;s run for a release, Succeeded: ten deliveries in order, the sixth an Email Skipped with audience_retired and the sentence that nothing was sent and the actions after it still ran

A rule&#39;s run for a release, Succeeded: nine deliveries in order; Slack, Email, Confluence and Microsoft Teams Skipped with nothing_for_audience and the sentence that nothing in the release concerns their audience, so nothing was sent and the actions after it still ran; GitHub Release, the public changelog, Notion and Zendesk Succeeded

A run whose GitHub Release action failed with github_release_conflict: the actions behind it are pending, with Run again and Cancel

A GitHub Release action borrows the project's GitHub source, so it depends on that source staying connected. A run records the repository of the project's one connected GitHub source, or, when none is connected, of its one disconnected one. When the recorded repository's source is disconnected, the action fails as github_source_disconnected before calling anything, and Run again succeeds once the same repository is reconnected. Without a single repository to record, it fails as github_source_missing. Disconnecting never disables a rule: the confirmation page lists the enabled rules it leaves without a token, and the Automation page marks each one No GitHub source connected until the project has one again.

An action whose outcome is unknown: running it again may deliver twice

REST​

REST clients do the same thing, sending the session cookie and the signed-in session's CSRF token with every write. Sign in as REST API shows, which sets BASE, JAR, and TOKEN:

bash
# BASE, JAR, and TOKEN as set in REST API → Sessions and CSRF
curl -s -b "$JAR" -H "X-CSRF-TOKEN: $TOKEN" -H 'Content-Type: application/json' \
-d '{"name":"Announce","triggerType":"RELEASE_PUBLISHED","projectId":"<project>",
"actions":[{"actionType":"SLACK","audienceId":"<audience>","language":"en",
"secret":"https://hooks.slack.com/services/T0/B0/secret"}]}' \
"$BASE/api/automation/rules"
curl -s -b "$JAR" -H "X-CSRF-TOKEN: $TOKEN" -X POST "$BASE/api/automation/rules/<rule>/enable"
curl -s -b "$JAR" -H "X-CSRF-TOKEN: $TOKEN" -H 'Content-Type: application/json' \
-d '{"releaseId":"<release>","requestId":"<uuid you choose>"}' \
"$BASE/api/automation/rules/<rule>/execute"
curl -s -b "$JAR" "$BASE/api/automation/runs?page=0&size=20"
curl -s -b "$JAR" -H "X-CSRF-TOKEN: $TOKEN" -H 'Content-Type: application/json' \
-d '{"confirmUnknown":true}' "$BASE/api/automation/runs/<run>/retry"

Every endpoint, all of them for administrators only:

text
GET /api/automation/rules
POST /api/automation/rules (201; a webhook rule's path and secret are in this response only)
GET /api/automation/rules/{ruleId}
PUT /api/automation/rules/{ruleId} (an empty secret keeps the stored one)
DELETE /api/automation/rules/{ruleId} (archives it)
POST /api/automation/rules/{ruleId}/enable
POST /api/automation/rules/{ruleId}/disable
POST /api/automation/rules/{ruleId}/execute {"releaseId", "requestId"} (202)
POST /api/automation/rules/{ruleId}/webhook-secret/rotate (the new secret, once)
POST /api/automation/rules/cron-preview {"cronExpression", "cronTimeZone"}
GET /api/automation/runs?page=0&size=20
GET /api/automation/runs/{runId}
POST /api/automation/runs/{runId}/retry {"confirmUnknown"}
POST /api/automation/runs/{runId}/cancel

A rule is {"name", "triggerType", "projectId", "releaseId", "cronExpression", "cronTimeZone", "daysBefore", "actions"}, with only the fields its trigger uses. An action is {"actionType", "audienceId", "language", "secret"} plus its own fields: recipients for email, parentPageId for Notion, siteUrl, email, spaceId, and parentPageId for Confluence, and subdomain, clientId, sectionId, and userSegmentId for Zendesk. When a rule is edited, an action that already exists also sends its id; only then does an empty secret keep the stored one, and an action sent without its id is a new action that needs its secret again.

POST /{id}/execute answers 202 with the run. The request ID is yours to choose and is the promise that a repeat is the same run rather than a second delivery. DELETE /api/automation/rules/{id} archives a rule, which cancels the runs it had not finished and frees its name. GET /api/automation/runs answers {"items", "page", "size", "total"}, with size between 1 and 100.

A public changelog action's refusal is public_changelog_conflict, recorded on the action rather than returned to anybody; see Public changelog. Likewise, an action whose release has no ready note for its audience and language fails as release_note_missing when the worker reaches it; the release is published either way. A skipped action is SKIPPED with its reason in errorCode, audience_retired or nothing_for_audience (Runs); a skip is not a refusal and has no Problem Details.

Refusals carry a stable code:

StatusCodes
404automation_rule_not_found, automation_run_not_found — also for a rule or run of another Organization, never 403, and for an archived rule: GET, PUT, enable, disable, and DELETE of one all answer 404 automation_rule_not_found
409automation_rule_name_taken, automation_rule_unavailable, automation_github_source_missing, automation_email_not_configured, automation_run_not_retryable, automation_unknown_needs_confirmation, automation_release_not_published, automation_scheduled_action_unsupported, automation_webhook_rule_required, automation_audience_retired
400, ruleautomation_action_required, automation_project_not_found, automation_audience_not_found, automation_language_not_configured, automation_secret_not_allowed, automation_request_id_required, invalid_automation_run_page
400, scheduleautomation_cron_invalid, automation_cron_time_zone_invalid, automation_cron_no_occurrence, automation_cron_release_required, automation_reminder_days_invalid
400, Slack and emailautomation_slack_webhook_required, automation_slack_webhook_invalid, automation_email_recipients_required, automation_email_recipient_invalid
400, Notion and Confluenceautomation_notion_parent_required, automation_notion_parent_invalid, automation_notion_token_required, automation_confluence_site_required, automation_confluence_site_invalid, automation_confluence_email_required, automation_confluence_email_invalid, automation_confluence_space_required, automation_confluence_space_invalid, automation_confluence_parent_invalid, automation_confluence_token_required
400, Teams and Zendeskautomation_teams_webhook_required, automation_teams_webhook_invalid, automation_zendesk_subdomain_required, automation_zendesk_subdomain_invalid, automation_zendesk_client_id_required, automation_zendesk_client_secret_required, automation_zendesk_section_required, automation_zendesk_section_invalid, automation_zendesk_user_segment_invalid

The signed webhook paths take no session, and refuse with webhook_signature_invalid (401), webhook_payload_too_large (413), or webhook_payload_malformed (400). See ADR-0020 and ADR-0021.

Public changelog​

A rule with a Public changelog action publishes the note on pages ReleaseFlow serves itself, for people who have no account:

AddressWhat it is
/changelog/{slug}The Organization's release notes, newest first, cached for five minutes
/changelog/{slug}/releases/{entry}One note, permanent, cached for a day with an ETag
/changelog/{slug}/rss.xmlRSS 2.0 with the 50 newest notes

The {slug} is your Organization's address: one DNS label, made from its name when you register. The Public changelog card on the Projects page shows it and lets an administrator change it — which moves the changelog, so links already shared stop working. GET/PUT /api/organization/slug does the same thing, and answers 400 organization_slug_invalid or 409 organization_slug_taken.

An entry is a snapshot: the Organization's name, the project, the version, the audience, and the note as they read when it was published. Nothing edits or removes it afterwards, not even direct SQL. Publishing the same note again is free — the action finds its own entry and succeeds — while a rule that would publish different words for a release, audience, and language that are already public fails as public_changelog_conflict rather than rewriting what somebody may have read. A public changelog action takes no secret and no configuration, and cannot be used by a rule that fires on a schedule.

A public changelog entry, read signed out

A release published for one audience in several languages, by one action per language, is one card on /changelog/{slug}: it opens on the language published first, and lists every language as a link named in its own language, such as English and Tiếng Việt, with hreflang and lang. An entry's own page names its language. It does not list the other languages: it is cached as immutable, and a language published later would be missing from it. The page around a note follows the reader's interface language, so <html lang> is that language and the note itself carries the entry's.

A public changelog read signed out: one card per release, with a link for each language

Set RELEASEFLOW_PUBLIC_BASE_URL to the address this deployment is reached at (default http://localhost:8080); every public link — the canonical URL, the RSS items, the address a run reports — is built from it and never from a request's Host header.

Setting RELEASEFLOW_PUBLIC_CHANGELOG_BASE_DOMAIN additionally serves each Organization at https://{slug}.{that domain}/, with /releases/{entry} and /rss.xml beneath it. Only GET is routed that way, only for exactly one label beneath the domain, and wildcard DNS and TLS are yours to provision. Leave it empty and changelogs answer by path only.