Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 102 additions & 0 deletions .github/actions/announce/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
# Announce release

Posts release news for the `wolfstar-project` repositories to a Discord webhook. One action, three modes:

| Mode | Used by | What it does |
| ---------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `packages` | `stars-components`, `plugins` | Renders each published package from its `CHANGELOG.md` section, Sapphire-style (`# @wolfstar/[email protected] - (date)`, then 💥 / 🚀 / 🐛 / 🏠 sections). No AI: the same release renders the same message. |
| `draft` | `wolfstar`, `staryl`, the site | Reads the pull requests merged between two refs, has the [Pullfrog](https://docs.pullfrog.com) agent write the announcement as JSON, and renders it. Nothing is sent. |
| `post` | the job after a reviewed `draft` | Sends the rendered draft. |

The agent only writes words. This action builds the Discord payload, so every message is valid, pings only the announced role (`allowed_mentions`), and carries the buttons and screenshots chosen here.

## Formats

`draft` renders one of two formats; `format: auto` lets the agent pick.

- **`text`**: the Skyra / WolfStar Announcements plain message. `## Title`, then `Updated **WolfStar Alpha**:` with nested bullets, and an italic closing hint. Split into several messages when it passes 2000 characters.
- **`components`**: a Components V2 container with the WolfStar gold accent (`#FEC609`), `##` sections split by separators, the screenshots as a media gallery, and link buttons (invite, release notes). Falls back to `text` past 4000 characters.

## Site screenshots

With `kind: site`, the action reads the pr-evidence comment of every merged pull request: a `| Before | After |` table, or images whose alt text says After. The newest capture wins. The agent picks up to `max-screenshots` pull requests whose change is the headline; the After images are downloaded and uploaded as attachments, so Discord never has to reach GitHub. Only images GitHub hosts (`github.com/user-attachments/assets/…`) are used.

## Review before posting

`draft` writes `message.json` and a preview in the job summary. The reusable workflow runs `post` in a separate job bound to a GitHub environment with required reviewers (the `environment` input, `discord-announcements` by default). The approver reads the preview, then the job sends it.

## Signed callbacks

Following the release notifications of [discordjs/discord.js#11673](https://github.com/discordjs/discord.js/pull/11673), every mode can POST `started`, `drafted`, `completed`, and `failed` events to `callback-url`. Each body is JSON with `schemaVersion`, `id`, `sequence` (a fixed position: `started` 1, `drafted` 2, `completed` 3, `failed` 4), `event`, `mode` (`packages`, `draft`, or `post`), `kind` (`bot`, `site`, or `null` for packages), `repository`, `runId`, `runUrl`, and event details, and carries:

- `X-Release-Delivery`: the event ID,
- `X-Release-Timestamp`: an ISO timestamp,
- `X-Release-Signature-256`: `sha256=` + HMAC-SHA256 of `<timestamp>.<body>` with `callback-secret`.

Callbacks are off unless both inputs are set, need HTTPS, refuse redirects, time out after 5 seconds, and retry 5xx and 429 twice. A failed callback only logs a warning. A receiver, such as a Cloudflare Worker or the Ring app, can verify the signature and react without holding the Discord webhook.

## Secrets and variables

| Name | Where | Use |
| ----------------------------------------------- | -------- | --------------------------------------------------------------------- |
| `DISCORD_*_WEBHOOK_URL` | secret | The webhook of the announcement channel. Without it, nothing is sent. |
| `DISCORD_*_ROLE_ID` | variable | The role pinged by the first message. |
| `ANTHROPIC_API_KEY` or another provider key | secret | `draft` only, read by Pullfrog from the env of the calling step. |
| `RELEASE_WEBHOOK_URL`, `RELEASE_WEBHOOK_SECRET` | secret | Optional signed callbacks. |

`draft` needs `id-token: write` (Pullfrog authenticates with OIDC) and `contents: read`. Pullfrog runs with `push: disabled`, `shell: restricted`, and no progress comments.

## Usage

Most repositories call one of two reusable workflows, which wrap this action: `reusable-announce-packages.yml` for published packages (needs `contents: read` and `pull-requests: read`) and `reusable-announce-release.yml` for a bot or site release, with the draft, review, and post jobs (also needs `id-token: write`). They are separate so a packages caller never has to grant `id-token: write`: GitHub checks the permissions of a called workflow even for the jobs it skips.

```yaml
# After the job that publishes (it exposes changesets/action's outputs)
announce:
needs: release
if: needs.release.outputs.published == 'true'
permissions:
contents: read
pull-requests: read
uses: wolfstar-project/.github/.github/workflows/reusable-announce-packages.yml@main
with:
published-packages: ${{ needs.release.outputs.publishedPackages }}
role-id: ${{ vars.DISCORD_PACKAGES_ROLE_ID }}
secrets:
DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_PACKAGES_WEBHOOK_URL }}
```

```yaml
# A bot or site release: draft, wait for the environment's reviewers, post
announce:
needs: tag
permissions:
contents: read
pull-requests: read
id-token: write # Pullfrog authenticates with OIDC
uses: wolfstar-project/.github/.github/workflows/reusable-announce-release.yml@main
with:
kind: bot
product: WolfStar Alpha
version: ${{ needs.tag.outputs.tag }}
from-ref: ${{ needs.tag.outputs.from }}
stage: alpha
role-id: ${{ vars.DISCORD_ANNOUNCEMENTS_ROLE_ID }}
button-label: Invite WolfStar Alpha
button-url: ${{ vars.DISCORD_INVITE_URL }}
secrets:
DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_ANNOUNCEMENTS_WEBHOOK_URL }}
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
```

The caller grants the permissions, because a called workflow can only keep or lower them, and maps only the secrets it wants to share. The `post` job runs in the caller's `discord-announcements` environment (the `environment` input), so the reviewers are the caller's. `published-packages` also takes `name@version` entries, which is how a manual workflow re-sends an announcement. `dry-run: true` renders into the job summary and sends nothing.

To call the action without the workflow, use `wolfstar-project/.github/.github/actions/announce@main` with the inputs of `action.yml`.

## Tests

```bash
node --test '.github/actions/announce/test/*.test.ts'
```

The sources run on Node.js 24 type stripping, so they use erasable TypeScript only and import with `.ts` extensions.
239 changes: 239 additions & 0 deletions .github/actions/announce/action.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,239 @@
name: Announce release
description: >-
Post release news to a Discord webhook. `packages` renders npm releases from
the changelogs with no AI; `draft` has the Pullfrog agent write a bot or
site announcement for review; `post` sends a reviewed draft.
author: wolfstar-project

inputs:
mode:
description: "`packages`, `draft`, or `post`."
required: true
github-token:
description: Token used to read pull requests, comments, and compare refs.
required: false
default: ${{ github.token }}
repository:
description: The `owner/name` the release belongs to.
required: false
default: ${{ github.repository }}
dry-run:
description: Render and write the job summary, but send nothing to Discord.
required: false
default: "false"

# packages
published-packages:
description: "`packages` mode: the `publishedPackages` output of changesets/action (JSON `[{ name, version }]`)."
required: false
default: "[]"
packages-dir:
description: "`packages` mode: the folder that holds the packages, relative to the workspace."
required: false
default: packages

# draft
kind:
description: "`draft` mode: `bot` or `site`. A site draft can include the After screenshots from PR evidence comments."
required: false
default: bot
product:
description: "`draft` mode: the name readers know, such as `WolfStar Alpha` or `wolfstar.rocks`."
required: false
default: ""
version:
description: "`draft` mode: the version or tag being announced."
required: false
default: ""
from-ref:
description: "`draft` mode: the previous release tag or commit. Pull requests merged after it are read."
required: false
default: ""
to-ref:
description: "`draft` mode: the tag or commit being released."
required: false
default: ${{ github.sha }}
stage:
description: "`draft` mode: `alpha`, `beta`, `preview`, `stable`, or `hotfix`. It decides the warning."
required: false
default: stable
format:
description: "`draft` mode: `auto`, `text` (Skyra-style plain message), or `components` (Components V2 container)."
required: false
default: auto
notes:
description: "`draft` mode: facts from the maintainer the repository cannot tell, such as a deadline or a data reset."
required: false
default: ""
language:
description: "`draft` mode: the language the announcement is written in."
required: false
default: English
include-open-pulls:
description: "`draft` mode: read open pull requests for the Coming soon section."
required: false
default: "true"
max-screenshots:
description: "`draft` mode: the most After screenshots a site announcement carries."
required: false
default: "3"
ai-model:
description: "`draft` mode: Pullfrog model override (a curated slug or a models.dev specifier). Empty uses the repository setting in the Pullfrog console."
required: false
default: ""
ai-effort:
description: "`draft` mode: Pullfrog reasoning effort."
required: false
default: medium
ai-timeout:
description: "`draft` mode: how long the Pullfrog agent may take."
required: false
default: 15m

# draft and post
output-dir:
description: Where `draft` writes the reviewed message and `post` reads it. Defaults to `$RUNNER_TEMP/announcement`.
required: false
default: ""

# Discord
webhook-url:
description: The Discord webhook URL. Without it nothing is sent and the job summary keeps the preview.
required: false
default: ""
thread-id:
description: Post into this thread of a forum or media channel.
required: false
default: ""
role-id:
description: The role pinged by the first message, as in `New announcement for @Subscribers:`.
required: false
default: ""
username:
description: Override the webhook's display name.
required: false
default: ""
avatar-url:
description: Override the webhook's avatar.
required: false
default: ""
button-label:
description: "`draft` mode: label of the link button, such as `Invite WolfStar Alpha`."
required: false
default: ""
button-url:
description: "`draft` mode: target of the link button, such as the invite URL."
required: false
default: ""
release-url:
description: "`draft` mode: GitHub release page, linked from a second button."
required: false
default: ""

# Signed lifecycle callbacks (discord.js release workflow style)
callback-url:
description: Optional HTTPS endpoint that receives signed `started`, `drafted`, `completed`, and `failed` events.
required: false
default: ""
callback-secret:
description: HMAC-SHA256 key for `callback-url`. Both are needed, or neither.
required: false
default: ""

outputs:
message-count:
description: How many Discord messages were rendered.
value: ${{ steps.run.outputs.message-count }}
output-dir:
description: The folder holding `message.json` and its attachments.
value: ${{ steps.run.outputs.output-dir }}
skipped:
description: "`true` when there was nothing user-visible to announce."
value: ${{ steps.run.outputs.skipped || steps.collect.outputs.skipped }}

runs:
using: composite
steps:
- name: Setup Node.js v24
uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
with:
node-version: 24

# draft: collect the release context and write the agent prompt.
- name: Collect release context
id: collect
if: inputs.mode == 'draft'
shell: bash
run: node "$GITHUB_ACTION_PATH/src/main.ts"
env:
INPUT_MODE: collect
INPUT_REPOSITORY: ${{ inputs.repository }}
INPUT_KIND: ${{ inputs.kind }}
INPUT_PRODUCT: ${{ inputs.product }}
INPUT_VERSION: ${{ inputs.version }}
INPUT_FROM_REF: ${{ inputs.from-ref }}
INPUT_TO_REF: ${{ inputs.to-ref }}
INPUT_STAGE: ${{ inputs.stage }}
INPUT_FORMAT: ${{ inputs.format }}
INPUT_NOTES: ${{ inputs.notes }}
INPUT_LANGUAGE: ${{ inputs.language }}
INPUT_INCLUDE_OPEN_PULLS: ${{ inputs.include-open-pulls }}
INPUT_MAX_SCREENSHOTS: ${{ inputs.max-screenshots }}
INPUT_OUTPUT_DIR: ${{ inputs.output-dir }}
GITHUB_TOKEN: ${{ inputs.github-token }}
RELEASE_WEBHOOK_URL: ${{ inputs.callback-url }}
RELEASE_WEBHOOK_SECRET: ${{ inputs.callback-secret }}

# draft: the Pullfrog agent writes the announcement as JSON that matches
# the schema. It cannot push, and the provider keys come from the env of
# the step that calls this action.
- name: Write the announcement with Pullfrog
id: pullfrog
if: inputs.mode == 'draft' && steps.collect.outputs.skipped != 'true'
uses: pullfrog/pullfrog@0d318bef8c7cf7ae3f193ef32b2bc74e1d94b4d1 # v0.1.90
with:
prompt_file: ${{ steps.collect.outputs.prompt-file }}
output_schema: ${{ steps.collect.outputs.schema }}
model: ${{ inputs.ai-model }}
effort: ${{ inputs.ai-effort }}
timeout: ${{ inputs.ai-timeout }}
push: disabled
shell: restricted
progress_comments: disabled
token: ${{ inputs.github-token }}

- name: Run
id: run
if: inputs.mode != 'draft' || steps.collect.outputs.skipped != 'true'
shell: bash
run: node "$GITHUB_ACTION_PATH/src/main.ts"
env:
INPUT_MODE: ${{ inputs.mode == 'draft' && 'render' || inputs.mode }}
INPUT_AGENT_RESULT: ${{ steps.pullfrog.outputs.result }}
INPUT_REPOSITORY: ${{ inputs.repository }}
INPUT_DRY_RUN: ${{ inputs.dry-run }}
INPUT_PUBLISHED_PACKAGES: ${{ inputs.published-packages }}
INPUT_PACKAGES_DIR: ${{ inputs.packages-dir }}
INPUT_KIND: ${{ inputs.kind }}
INPUT_PRODUCT: ${{ inputs.product }}
INPUT_VERSION: ${{ inputs.version }}
INPUT_FROM_REF: ${{ inputs.from-ref }}
INPUT_TO_REF: ${{ inputs.to-ref }}
INPUT_STAGE: ${{ inputs.stage }}
INPUT_FORMAT: ${{ inputs.format }}
INPUT_NOTES: ${{ inputs.notes }}
INPUT_LANGUAGE: ${{ inputs.language }}
INPUT_INCLUDE_OPEN_PULLS: ${{ inputs.include-open-pulls }}
INPUT_MAX_SCREENSHOTS: ${{ inputs.max-screenshots }}
INPUT_OUTPUT_DIR: ${{ inputs.output-dir }}
INPUT_THREAD_ID: ${{ inputs.thread-id }}
INPUT_ROLE_ID: ${{ inputs.role-id }}
INPUT_USERNAME: ${{ inputs.username }}
INPUT_AVATAR_URL: ${{ inputs.avatar-url }}
INPUT_BUTTON_LABEL: ${{ inputs.button-label }}
INPUT_BUTTON_URL: ${{ inputs.button-url }}
INPUT_RELEASE_URL: ${{ inputs.release-url }}
GITHUB_TOKEN: ${{ inputs.github-token }}
DISCORD_WEBHOOK_URL: ${{ inputs.webhook-url }}
RELEASE_WEBHOOK_URL: ${{ inputs.callback-url }}
RELEASE_WEBHOOK_SECRET: ${{ inputs.callback-secret }}
47 changes: 47 additions & 0 deletions .github/actions/announce/src/actions.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
import { appendFileSync } from 'node:fs';
import { EOL } from 'node:os';

/** Reads an `INPUT_*` variable the composite action sets from its inputs. */
export function input(name: string, fallback = ''): string {
const value = process.env[`INPUT_${name.toUpperCase().replaceAll('-', '_')}`];
return value === undefined || value.trim() === '' ? fallback : value.trim();
}

export function booleanInput(name: string, fallback = false): boolean {
const value = input(name).toLowerCase();
if (value === '') return fallback;
return value === 'true' || value === '1' || value === 'yes';
}

export function setOutput(name: string, value: string | number | boolean): void {
const file = process.env.GITHUB_OUTPUT;
if (!file) return;
const text = String(value);
const delimiter = `ghadelimiter_${crypto.randomUUID()}`;
appendFileSync(file, `${name}<<${delimiter}${EOL}${text}${EOL}${delimiter}${EOL}`);
}

export function appendSummary(markdown: string): void {
const file = process.env.GITHUB_STEP_SUMMARY;
if (file) appendFileSync(file, `${markdown}${EOL}`);
else console.log(markdown);
}

export function warning(message: string): void {
console.log(`::warning::${escapeCommand(message)}`);
}

export function notice(message: string): void {
console.log(`::notice::${escapeCommand(message)}`);
}

function escapeCommand(message: string): string {
return message.replaceAll('%', '%25').replaceAll('\r', '%0D').replaceAll('\n', '%0A');
}

/** The URL of the current workflow run, or `null` outside GitHub Actions. */
export function runUrl(): string | null {
const { GITHUB_SERVER_URL, GITHUB_REPOSITORY, GITHUB_RUN_ID } = process.env;
if (!GITHUB_SERVER_URL || !GITHUB_REPOSITORY || !GITHUB_RUN_ID) return null;
return `${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}`;
}
Loading
Loading