Create Knowledge from GitHub PRs

Overview

The GitHub Action for Create-Suggestions integration automates the creation of plain-language Brainfish knowledge base (KB) draft suggestions from GitHub pull request (PR) changes. When code is merged, the workflow captures the PR metadata and code diff, sends it to Brainfish for analysis, and produces a human-reviewable suggestion in the Brainfish platform.

This approach reduces documentation lag, keeps customer-facing guidance accurate, and requires zero additional effort from developers.

Problem

Engineering teams often face two recurring issues:

• Documentation lag: Customer enablement and support documentation can trail code deployments by days or weeks.
• Tool skepticism and evaluation fatigue: New AI/documentation workflows can fail to gain adoption if they require developers to change habits or add manual steps.

Solution

Embed Brainfish suggestion creation directly into the existing GitHub PR workflow using a GitHub Action triggered on PR merge.

Key design principles:

• “No” default / no workflow change: The action runs inside existing CI/CD processes.
• Immediate context and value: It converts technical diffs into business-friendly enablement content as soon as changes land.

How the Workflow Works

The integration runs when a pull request is merged and follows these stages.

1. Trigger
   • Event: on: pull_request: [closed]
   • Starts when a PR is closed via merge, signaling a deployed (or deployment-ready) code change.
2. Capture PR context and diff
   • Actions/steps: actions/checkout@v3 plus a custom script
   • Captures:
     • The diff between branches
     • PR title and body
3. Send data to Brainfish
   • Action: brainfish/suggestion-action@v1
   • Sends diffs and PR metadata to the Brainfish API endpoint.
4. AI processing (Brainfish backend)
   • Service: Discovery Service
   • Brainfish AI:
     • Analyzes the change
     • Synthesizes plain-language content
     • Classifies the change type
5. Suggestion output in Brainfish
   • Service: Discovery Service
   • Creates a tagged, human-reviewable suggestion draft in the Brainfish platform.

What the Create-Suggestions Draft Includes

The generated suggestion is structured as an enablement-ready KB draft, typically containing:

• What Changed: Plain-language summary of the update.
• Who Is Affected: Impacted customer segments, plans, or personas.
• How It Works Now: Step-by-step explanation from the customer’s perspective.
• What to Tell Customers: Copy/paste response guidance for Support and CS.
• Internal Notes: Rollout details, limitations, or implementation caveats suitable for internal review.

Operational Impact

Developer-centric benefits

• Zero effort required: Developers do not need to write separate documentation or update external systems.
• High adoption likelihood: Works silently within the standard PR merge workflow.

Business and commercial benefits

• Speed: Draft suggestions are generated within minutes of merge.
• Coverage: Every significant code change is evaluated for documentation impact.
• Proactivity: Support and Customer Success can be informed before customers ask.

Safeguards (Integrity and Security)

The integration is designed to protect internal details and maintain editorial control:

1. No code exposure: Suggestions must not reveal raw code, file names, or sensitive implementation details.
2. No auto-publishing: A human reviewer must approve drafts before publication.
3. Supportive role: The output is a first draft to eliminate the “blank page” problem; it does not replace writers.

Additional Information

• Related reference: Brainfish GitHub Actions sync documentation: https://help.brainfi.sh/articles/brainfish-oas-github-actions-sync-mSe3TY5Zi9