Chuyển tới nội dung chính

Automation

Quy tắc gửi một release note đã publish tới nơi người đọc của nó vẫn thường xem, và changelog công khai publish nó để bất kỳ ai cũng đọc được.

Quy tắc​

Một quy tắc gửi release note đã publish tới nơi người đọc của nó vẫn thường xem. Mở Automation trong thanh bên, mục chỉ quản trị viên mới thấy. Một quy tắc nêu rõ điều gì khiến nó chạy, project nó theo dõi (hoặc mọi project), và các action nó thực hiện theo thứ tự. Mỗi action nêu audience và ngôn ngữ của release note mà nó gửi.

Các rule automation cùng trigger và trạng thái bật hay tắt của từng rule; một webhook path đã được che

Có năm điều có thể khiến một quy tắc chạy:

Chạy khiCần gìĐiều gì xảy ra
Release được publishKhông cần gìMỗi quy tắc khớp chạy một lần cho mỗi release
Chạy bằng tayMột release đã publish và một request IDCùng request ID là cùng một lần chạy, không bao giờ gửi lần thứ hai
Theo lịchMột release đã publish, một biểu thức cron sáu trường và một múi giờ IANARelease được gửi lại theo lịch đó. Những lần chạy bị lỡ trong lúc ReleaseFlow ngừng hoạt động gộp thành một lần chạy bù
Trước release dự kiếnThời gian báo trước từ 0 đến 365 ngàyMột release đã duyệt có thời điểm dự kiến được thông báo trước chừng ấy thời gian. Dời lịch release sẽ có thêm một lần nhắc
Do hệ thống khác gọiKhông cần gì; ReleaseFlow tạo đường dẫn và secretMột lời gọi có chữ ký nêu một release đã publish và bắt đầu một lần chạy

Quy tắc theo lịch và quy tắc nhắc trước chỉ nhận những action chỉ để thông báo cho mọi người — Slack, email và Microsoft Teams: không có ai theo dõi khi chúng chạy. Quy tắc theo lịch lấy project từ release mà nó lặp lại. Xem lần chạy tới trên trang, hoặc POST /api/automation/rules/cron-preview, cho biết khi nào một biểu thức sẽ chạy lần tới, trước khi quy tắc nào lưu nó.

Thử một lịch cron ở một múi giờ: trang cho biết lần chạy tới

Viết quy tắc trước; quy tắc mới luôn ở trạng thái tắt. Bật nó là lúc ReleaseFlow kiểm tra rằng các lần gửi có thể thực hiện được: project và mọi audience thuộc Organization của bạn, ngôn ngữ là một ngôn ngữ Organization của bạn viết release note, project của action GitHub Release có đúng một nguồn GitHub đang kết nối, hệ thống triển khai có khả năng thực hiện action đó, và cấu hình cùng secret đều dùng được. Một quy tắc bị từ chối sẽ cho biết điều nào trong số đó không đạt.

Bảng quy tắc với một quy tắc được đánh dấu là gửi tới một audience đã ngừng dùng; đường dẫn gọi của một quy tắc khác được che

Action​

Có tám loại action:

ActionCần gìLàm gì
GitHub ReleaseNguồn GitHub đang kết nối của chính project và access token của nóPublish release note làm nội dung release của tag phiên bản, có đánh dấu trong body để lần lặp lại nhận ra phần việc của chính nó
SlackMột incoming webhook URL, cũng là secret của actionĐăng release note vào channel bằng định dạng mrkdwn của Slack, tối đa 39.000 ký tự
EmailRELEASEFLOW_AUTOMATION_EMAIL_FROM và một SMTP serverGửi release note tới từ 1 đến 100 địa chỉ
Changelog công khaiKhông cần gìPublish release note trên trang changelog và RSS feed của chính bạn
NotionID của trang cha và một integration tokenTạo release note thành một trang con có tiêu đề Release <version>, tối đa 450.000 byte
ConfluenceMột site Cloud, email của tài khoản, ID số của space, trang cha không bắt buộc, và một API tokenTạo một trang có tiêu đề Release <version> trong space đó, tối đa 2.000.000 byte
Microsoft TeamsURL callback của Workflows, cũng là secret của actionĐăng release note dưới dạng văn bản thường vào chat hoặc channel mà flow nhắm tới, request tối đa 28 KiB
ZendeskMột subdomain, client ID và secret OAuth, ID số của section, và user segment không bắt buộcPublish release note thành một bài viết Help Center bằng ngôn ngữ của action, tối đa 1.000.000 byte

Một quy tắc chạy khi release được publish, với chín action theo thứ tự; site Atlassian và trang Notion được che

Một Slack webhook URL phải trỏ tới một origin mà hệ thống triển khai cho phép — hooks.slack.com hoặc hooks.slack-gov.com, trừ khi RELEASEFLOW_SLACK_ALLOWED_HOSTS quy định khác — và được kiểm tra lại trước mỗi lần gửi. Một site Confluence được kiểm tra theo cách tương tự, nhưng dựa trên hình dạng thay vì danh sách: nó phải đúng một nhãn ngay dưới atlassian.net, qua HTTPS, không có gì sau host. ID trang Notion là 32 ký tự thập lục phân mà Notion hiển thị, có hoặc không có dấu gạch nối. Callback Microsoft Teams phải là URL Workflows dạng HTTPS mà flow hiển thị — một nhãn ngay dưới environment.api.powerplatform.com, đường dẫn trigger của Workflows, và chữ ký sig của chính nó — còn subdomain Zendesk là một nhãn, không phải URL, nên help centre duy nhất một action truy cập được là của chính nó. Trang Confluence mang một comment HTML ghi tên lần chạy đã tạo ra nó; không có gì đọc lại comment đó, nên một lần gửi mà Notion hoặc Confluence không bao giờ xác nhận sẽ giữ trạng thái không rõ kết quả cho tới khi một người chấp nhận có thêm trang thứ hai. Secret chỉ ghi được: một khi đã lưu, không phản hồi, trang hay log nào lặp lại nó, và để trống trường này khi sửa sẽ giữ nguyên secret đang có.

GitHub Release do một rule viết từ note contributor

Email một rule đã gửi kèm note đã publish

Tin nhắn Slack một rule đã đăng cho release

Trang Notion một rule đã tạo cho release

Trang Confluence một rule đã tạo cho release

Quy tắc do hệ thống khác gọi​

Lưu một quy tắc chạy khi có hệ thống khác gọi sẽ tạo cho nó một đường dẫn và một secret 256 bit, cả hai chỉ hiện một lần. Xoay secret thay secret và giữ nguyên đường dẫn; secret cũ ngừng hoạt động ngay lập tức.

Secret của một rule do hệ thống khác gọi, chỉ hiện một lần sau khi đổi secret; đã được che

Một lời gọi là một POST tới đường dẫn đó với {"releaseId": "…"} và ba header:

HeaderChứa gì
X-ReleaseFlow-TimestampSố giây tính từ epoch, lệch không quá năm phút so với hiện tại
X-ReleaseFlow-DeliveryMột UUID, gửi lại y nguyên khi thử lại để không có gì bị gửi hai lần
X-ReleaseFlow-Signature-256sha256= và HMAC-SHA256 dạng hex như dưới đây

Chữ ký bao gồm timestamp, delivery, phương thức viết hoa, đường dẫn request, và SHA-256 dạng hex của body, mỗi thứ một dòng:

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"

Phản hồi là 202 với {"runId", "status", "statusPath"}. Một lời gọi GET có chữ ký tới statusPath đó cho biết lần chạy kết thúc ra sao. Organization là của quy tắc, không bao giờ lấy từ body. Body lớn hơn 64 KiB trả về 413; đường dẫn không tồn tại, quy tắc đang tắt, thời điểm lệch quá năm phút, và chữ ký sai đều trả về 401.

Lần chạy​

Publish một release chỉ ghi nhận rằng việc đó đã xảy ra, không làm gì thêm, nên một quy tắc không ai thực hiện được không bao giờ cản trở một release. Trong vòng một giây, worker tạo một lần chạy cho mỗi quy tắc khớp và đi qua lần lượt các action của nó. Lịch sử chạy cho thấy từng lần gửi và kết quả của nó. Action đầu tiên thất bại sẽ chặn các action phía sau, và Chạy lại chỉ lặp lại đúng action đó. Một action mà không ai xác nhận được kết quả — kết nối bị ngắt sau khi request đã đi, hoặc worker dừng trong năm phút — được ghi là không rõ kết quả và không bao giờ tự gửi lại; lặp lại nó sẽ yêu cầu bạn xác nhận rằng lần gửi có thể xảy ra hai lần. Huỷ để action đang thực hiện ghi lại kết quả của nó và dừng các action còn lại.

Một action cho một audience đã ngừng dùng được bỏ qua với audience_retired trước khi gọi bất cứ thứ gì: không có gì được gửi cho nó, các action phía sau vẫn chạy, và một lần chạy mà các action khác thành công thì thành công. Lịch sử chạy đánh dấu action đó Đã bỏ qua và nói lý do, và trang Automation đánh dấu một quy tắc vẫn gửi tới audience đã ngừng dùng. Bật một quy tắc như vậy bị từ chối với 409 automation_audience_retired; trước hết hãy trỏ action sang một audience đang dùng, hoặc dùng lại audience đó. Trạng thái của một action qua API là PENDING, RUNNING, SUCCEEDED, FAILED, UNKNOWN, CANCELLED hoặc SKIPPED.

Một action mà note của nó không có gì cho audience của nó cũng được bỏ qua, với nothing_for_audience: không thay đổi nào trong release liên quan tới audience đó, nên note của nó chỉ có tiêu đề, tóm tắt release, và dòng nói rằng release này không có gì liên quan tới họ. Không có gì được gửi, nên không có mục changelog công khai, trang, bài viết hay tin nhắn nào chỉ nói điều đó, và phần còn lại của lần chạy tiếp tục như với một audience đã ngừng dùng. Việc này được quyết định khi action chạy, với mọi trigger, từ các thay đổi của release theo đúng quy tắc chọn thay đổi cho một note (xem Release Note), không bao giờ từ nội dung của note. Các bước kiểm tra theo thứ tự này: audience đã ngừng dùng được bỏ qua với audience_retired; action không có note sẵn sàng thất bại với release_note_missing; note do một người sửa được gửi đúng như đã viết, dù các thay đổi của nó nói gì; và chỉ sau đó note không có gì cho audience của nó mới bị bỏ qua. Muốn gửi một note như vậy có chủ ý, hãy sửa nó trước khi publish. Bật một quy tắc không bao giờ bị từ chối vì lý do này, vì một quy tắc tồn tại lâu hơn mọi release.

Các thay đổi được đọc theo trạng thái lúc action chạy, nên một note đã publish và việc bỏ qua nó có thể không khớp nhau. Nếu sau khi publish, một lần review bỏ cờ phá vỡ tương thích của một thay đổi, hoặc AI được nhờ viết một narrative còn thiếu, thì một thay đổi mà note liệt kê có thể không còn liên quan tới audience, và chạy lại quy tắc sẽ bỏ qua một note vốn có nội dung. Ngược lại, một note nói rằng không có gì liên quan tới audience của nó sẽ được gửi khi một thay đổi của nó trở nên liên quan. Xem amendment của ADR-0035.

Lần chạy của một quy tắc cho một release, Thành công: mười lần gửi theo thứ tự, lần thứ sáu là Email Đã bỏ qua với audience_retired và câu giải thích không gửi gì và các action sau vẫn chạy

Lần chạy của một quy tắc cho một release, Thành công: chín lần gửi theo thứ tự; Slack, Email, Confluence và Microsoft Teams Đã bỏ qua với nothing_for_audience và câu rằng release không có thay đổi nào liên quan tới audience của chúng, nên không gửi gì và các Action sau vẫn chạy; GitHub Release, changelog công khai, Notion và Zendesk Thành công

Một lần chạy có action GitHub Release thất bại với github_release_conflict: các action sau nó đang chờ, cùng nút chạy lại và huỷ

Action GitHub Release mượn nguồn GitHub của project, nên nó phụ thuộc vào việc nguồn đó còn kết nối. Một lần chạy ghi lại repository của nguồn GitHub đang kết nối duy nhất của project, hoặc, khi không có nguồn nào đang kết nối, của nguồn duy nhất đã ngắt kết nối. Khi nguồn của repository đã ghi bị ngắt kết nối, action thất bại với github_source_disconnected trước khi gọi bất cứ thứ gì, và chạy lại sẽ thành công khi cùng repository đó được kết nối lại. Không có một repository duy nhất để ghi thì nó thất bại với github_source_missing. Ngắt kết nối không bao giờ tắt một quy tắc: trang xác nhận liệt kê các quy tắc đang bật mà nó để lại không có token, và trang Automation đánh dấu từng quy tắc Chưa kết nối nguồn GitHub cho tới khi project có lại một nguồn.

Một action không rõ kết quả: chạy lại có thể gửi hai lần

REST​

REST client làm được những việc tương tự, gửi cookie phiên đăng nhập và CSRF token của phiên đã đăng nhập kèm mọi thao tác ghi. Đăng nhập như REST API hướng dẫn, việc này đặt sẵn BASE, JAR và 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"

Tất cả endpoint, đều chỉ dành cho quản trị viên:

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

Một quy tắc là {"name", "triggerType", "projectId", "releaseId", "cronExpression", "cronTimeZone", "daysBefore", "actions"}, chỉ gồm các trường mà trigger của nó dùng. Một action là {"actionType", "audienceId", "language", "secret"} cộng các trường riêng của nó: recipients cho email, parentPageId cho Notion, siteUrl, email, spaceId và parentPageId cho Confluence, và subdomain, clientId, sectionId và userSegmentId cho Zendesk. Khi sửa một quy tắc, action đã có sẵn gửi kèm id của nó; chỉ khi đó một secret để trống mới giữ lại secret đã lưu, còn action gửi đi mà không có id là một action mới và cần secret của nó một lần nữa.

POST /{id}/execute trả về 202 kèm lần chạy. Request ID do bạn chọn, và là lời cam kết rằng một lần lặp lại là cùng một lần chạy chứ không phải một lần gửi thứ hai. DELETE /api/automation/rules/{id} lưu trữ một quy tắc, việc này huỷ các lần chạy chưa xong của nó và giải phóng tên của nó. GET /api/automation/runs trả về {"items", "page", "size", "total"}, với size từ 1 đến 100.

Lời từ chối của action changelog công khai là public_changelog_conflict, được ghi trên action chứ không trả về cho ai; xem Changelog công khai. Tương tự, một action mà release của nó không có release note sẵn sàng cho audience và ngôn ngữ của action sẽ thất bại với release_note_missing khi worker tới lượt nó; release vẫn được publish dù thế nào. Một action bị bỏ qua có trạng thái SKIPPED, với lý do trong errorCode là audience_retired hoặc nothing_for_audience (Lần chạy); bỏ qua không phải là lời từ chối và không có Problem Details.

Các lời từ chối mang mã cố định:

Trạng tháiMã
404automation_rule_not_found, automation_run_not_found — kể cả với quy tắc hoặc lần chạy của Organization khác, không bao giờ là 403, và với quy tắc đã lưu trữ: GET, PUT, bật, tắt và DELETE một quy tắc như vậy đều trả 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, quy tắcautomation_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, lịchautomation_cron_invalid, automation_cron_time_zone_invalid, automation_cron_no_occurrence, automation_cron_release_required, automation_reminder_days_invalid
400, Slack và emailautomation_slack_webhook_required, automation_slack_webhook_invalid, automation_email_recipients_required, automation_email_recipient_invalid
400, Notion và 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 và 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

Các đường dẫn webhook có chữ ký không dùng phiên đăng nhập, và từ chối với webhook_signature_invalid (401), webhook_payload_too_large (413) hoặc webhook_payload_malformed (400). Xem ADR-0020 và ADR-0021.

Changelog công khai​

Một quy tắc có action Changelog công khai publish release note trên những trang do chính ReleaseFlow phục vụ, cho những người không có tài khoản:

Địa chỉLà gì
/changelog/{slug}Các release note của Organization, mới nhất trước, cache trong năm phút
/changelog/{slug}/releases/{entry}Một release note, cố định vĩnh viễn, cache trong một ngày kèm ETag
/changelog/{slug}/rss.xmlRSS 2.0 với 50 release note mới nhất

{slug} là địa chỉ của Organization: một nhãn DNS, tạo từ tên của nó khi bạn đăng ký. Thẻ Changelog công khai trên trang Project hiển thị nó và cho phép quản trị viên đổi nó — việc này dời changelog đi chỗ khác, nên các liên kết đã chia sẻ sẽ không còn dùng được. GET/PUT /api/organization/slug làm việc tương tự, và trả về 400 organization_slug_invalid hoặc 409 organization_slug_taken.

Mỗi mục là một bản chụp: tên Organization, project, phiên bản, audience, và release note đúng như lúc được publish. Sau đó không có gì sửa hay xoá được nó, kể cả SQL trực tiếp. Publish lại đúng release note đó không tốn gì — action tìm thấy mục của chính nó và thành công — còn một quy tắc định publish nội dung khác cho một release, audience và ngôn ngữ đã công khai sẽ thất bại với public_changelog_conflict, thay vì viết đè lên thứ mà ai đó có thể đã đọc. Action changelog công khai không cần secret hay cấu hình, và không dùng được cho quy tắc chạy theo lịch.

Một mục public changelog, đọc khi không đăng nhập

Một release được publish cho một audience bằng nhiều ngôn ngữ, mỗi ngôn ngữ một action, là một thẻ duy nhất trên /changelog/{slug}: thẻ mở bằng ngôn ngữ được publish trước, và liệt kê mọi ngôn ngữ dưới dạng liên kết gọi bằng chính ngôn ngữ đó, như English và Tiếng Việt, kèm hreflang và lang. Trang riêng của một mục ghi rõ ngôn ngữ của nó. Trang đó không liệt kê các ngôn ngữ khác: nó được cache dạng bất biến, nên một ngôn ngữ publish sau sẽ không có mặt trên đó. Phần khung quanh một release note theo ngôn ngữ giao diện của người đọc, nên <html lang> là ngôn ngữ đó, còn bản thân release note mang ngôn ngữ của mục.

Changelog công khai bằng tiếng Việt, mới nhất trước: mỗi release một thẻ với liên kết English và Tiếng Việt

Đặt RELEASEFLOW_PUBLIC_BASE_URL là địa chỉ dùng để truy cập hệ thống triển khai này (mặc định http://localhost:8080); mọi liên kết công khai — URL chuẩn, các mục RSS, địa chỉ mà một lần chạy báo lại — đều được dựng từ nó, không bao giờ từ header Host của request.

Đặt thêm RELEASEFLOW_PUBLIC_CHANGELOG_BASE_DOMAIN sẽ phục vụ mỗi Organization tại https://{slug}.{that domain}/, với /releases/{entry} và /rss.xml bên dưới. Chỉ GET được định tuyến theo cách đó, chỉ cho đúng một nhãn ngay dưới domain, và bạn tự lo wildcard DNS cùng TLS. Để trống thì changelog chỉ trả lời theo đường dẫn.