Skip to main content

ADR ↔ Discussions workflow

Philosophy​

Ideas are discussed in GitHub Discussions (category Ideas). When a conversation matures and the team wants to formalize the decision, any member with write access comments /adr on the thread and a workflow:

  1. Creates a PR with an ADR stub (frontmatter + empty sections).
  2. The stub includes discussion: <number> pointing to the original thread.
  3. Posts a link to the PR in the Discussion.

The Discussion is not closed when the PR is merged: it remains as a permanent thread for amendments, clarifications, and revisiting the decision later.

There is no separate Decisions category. For a small team, creating another conversation channel would be unnecessary ceremony.

Flow​

  Ideas (Discussions)
         │
         ▼  open conversation, days or weeks
         │
    someone comments:
         /adr
         │
         ▼
 .github/workflows/adr-from-discussion.yml
    1. Guard: /adr + category=ideas + write access
    2. Checkout main
    3. Next ADR number = max(files in docs/adrs/) + 1
    4. Create branch adr/NNNN-<slug-from-title>
    5. Write docs/adrs/NNNN-<slug>.md with:
         - frontmatter (title, status:Proposed, date, discussion:<num>)
         - empty sections + :::info bootstrap note
    6. gh pr create
    7. React to /adr with a rocket reaction
    8. Comment on the Discussion with the PR link
         │
         ▼
  ADR author completes the content, opens review
         │
         ▼
  PR merge → ADR published
  (Discussion stays open as a permanent channel)

How to use it​

Scenario 1: ADR originates from a discussion​

  1. Open a Discussion in the Ideas category, with the title matching the future ADR title.
  2. Discuss freely (no ceremony).
  3. When there is consensus, someone simply comments: 
    /adr
  4. Within ~30 seconds the bot opens a PR and comments with the link.
  5. Edit the PR, complete the sections, request review, merge.

Scenario 2: ADR without a prior Discussion​

Some decisions are obvious and do not warrant a thread. Open the PR directly by copying docs/adrs/template.md. The card renders No discussion linked in the Discussion row — this is informational and does not block anything.

Triple guard on the workflow (zero cost when it does not match)​

if: |
  startsWith(github.event.comment.body, '/adr') &&
  github.event.discussion.category.slug == 'ideas' &&
  contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'),
           github.event.comment.author_association)
yaml
  • Regular comments: the workflow run is marked as Skipped, no runner is assigned, zero minutes consumed.
  • /adr outside the Ideas category: skipped.
  • /adr from someone without write access: skipped (prevents abuse by outside contributors).

Setup (one-time)​

These steps require admin access and the web UI:

  1. Enable Discussions on the repo: Settings → General → Features → Discussions. Already enabled.
  2. Ideas category: included by default when you enable Discussions. Already exists.
  3. Workflow permissions: the workflow explicitly declares contents: write, discussions: write, pull-requests: write. No need to change the default.

Token permissions​

The action uses the default GITHUB_TOKEN with:

  • contents: write — create branch, commit, push
  • discussions: write — comment and react on the Discussion
  • pull-requests: write — open PR

If/when switching to the GitHub App eigenoid-release-bot, the scopes are identical — just swap the token env var.

Troubleshooting​

  • I commented /adr and nothing happened
    • Is the Discussion in the Ideas category? (other categories do not trigger the workflow)
    • Do you have write access to the repo? (outside contributors are filtered out)
    • Check the Actions tab: look for the "ADR from Discussion" run. If it shows as Skipped, the guard rejected it. If it shows as Failed, check the logs.
  • PR was created but the Discussion does not show the comment
    • Could be a race condition or API delay. Refresh after 30 seconds. If it persists, check the logs.
  • "File already exists"
    • Two /adr commands fired simultaneously on different threads and collided. One succeeds, the other fails. Comment /adr again and it will take the next available number.
  • Original Discussion linked to a merged ADR is left orphaned
    • By design. We leave it open permanently as a channel for post-Accepted follow-ups.
  • ADR template: docs/adrs/template.md
  • Workflow: .github/workflows/adr-from-discussion.yml
  • Script: .github/scripts/bootstrap-adr-from-discussion.mjs