Skip to content
Open
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
2 changes: 1 addition & 1 deletion .github/workflows/open-discussion.yml
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ jobs:
stem = os.path.splitext(os.path.basename(filepath))[0]
slug = re.sub(r"^\d{4}-\d{2}-\d{2}-", "", stem)

discussion_title = f"{title} | Bluefin"
discussion_title = title
post_url = f"https://docs.projectbluefin.io/blog/{slug}"

print(f"\nProcessing: {filepath}")
Expand Down
23 changes: 11 additions & 12 deletions docs/skills/giscus-discussions.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: giscus-discussions
version: "1.2"
version: "1.3"
last_updated: "2026-09-06"
id: giscus-discussions
one_line_purpose: Verify, recover, and archive blog Giscus discussion threads.
Expand Down Expand Up @@ -46,31 +46,30 @@ Discussion are both verified.
secret with Discussion write access in `ublue-os/bluefin`, then rerun the
workflow. Do not create a replacement token, GitHub App, or credential
scheme.
3. Search `ublue-os/bluefin` for the exact title
`<post title> | Bluefin`. If it already exists, verify its body contains the
expected SHA-1 marker and do not create a duplicate.
3. Search `ublue-os/bluefin` for the exact title `<post title>`. If it already
exists, verify its body contains the expected SHA-1 marker and do not create
a duplicate.
4. If the post is live, the workflow cannot run with its existing secret, and
an authorized maintainer must recover the thread immediately, use GitHub
GraphQL with the maintainer’s existing authenticated `gh` account. Obtain
the repository and category IDs from
`src/components/GiscusComments/index.tsx`; they are the source of truth for
the configured Giscus target.
5. Create the Discussion with the exact title `<post title> | Bluefin` and a
body containing:
5. Create the Discussion with the exact title `<post title>` and a body
containing:

```md
A new blog post is up: **[<post title>](https://docs.projectbluefin.io/blog/<slug>)**

Read it and join the conversation below! 🦕

<!-- sha1: <sha1 of "<post title> | Bluefin"> -->
<!-- sha1: <sha1 of "<post title>"> -->
```

Calculate the marker from the complete title, including the spaces around
the vertical bar:
Calculate the marker from the complete title:

```sh
printf %s '<post title> | Bluefin' | sha1sum
printf %s '<post title>' | sha1sum
```

GitHub’s documented `createDiscussion` mutation requires `repositoryId`,
Expand Down Expand Up @@ -118,14 +117,14 @@ Discussion are both verified.
| Rationalization | Reality |
| ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| “The workflow failed, but the post is live, so comments can wait.” | A strict Giscus mapping has no discussion to attach to. Create or recover the exact matching Discussion before closing the source thread. |
| “A similar title is close enough.” | Giscus strict mode matches the exact `og:title` hash. Use the blog title and its `Bluefin` suffix exactly. |
| “A similar title is close enough.” | Giscus strict mode matches the exact `og:title` hash. Use the blog title exactly. |
| “I can make a new token to unblock this.” | The supported automation uses `BLUEFIN_DISCUSSIONS_TOKEN`. Restore that secret; do not add another credential scheme. |
| “The original discussion can be closed first.” | Readers lose the migration path until the post and its comments are both live. Archive it last. |

## Red Flags

- The workflow claims success without a new `ublue-os/bluefin` Discussion.
- The Giscus title differs from the blog title plus ` | Bluefin`.
- The Giscus title differs from the blog title.
- The Discussion body lacks its SHA-1 marker.
- More than one Discussion exists with the exact blog-comment title.
- The source draft Discussion is closed before the live post and comment
Expand Down
Loading