Building an auto-release notes agent for GitHub PRs

‍TL;DR

• Automates release notes: The agent converts GitHub PR metadata into structured Notion pages and posts Slack notifications instantly, reducing manual overhead and improving documentation consistency.
• Polling vs Webhook: Offers two modes of operation—periodic polling for local setups and real-time webhooks for instant updates, ensuring flexibility for different environments.
• Handles Complex Workflow: Tracks PRs, ensures idempotency to avoid duplicates, and manages errors with automatic retries, allowing for smooth scaling and integration.
• Integration Simplified: Leverages Scalekit for OAuth, API calls, and seamless connection between GitHub, Notion, and Slack, eliminating the need for manual token management.
• Increased Productivity: Reduces context switching, accelerates release cycles, and allows developers to focus on coding rather than repetitive admin tasks like drafting release notes.

Dev teams, release chaos, and the "Where are the release notes?" dilemma

Picture this: it’s peak hour before a major deployment, your team is merging the final pull requests, and suddenly the dreaded question pops up in your project channel: “Do we have the release notes ready?” For most developers, this is a familiar pain point. Someone ends up sifting through countless commits, deciphering the forest of code changes, drafting release notes manually, and pasting links across Slack and Notion. The cost isn’t just wasted hours; context switching at this critical stage derails momentum and increases the risk of missing crucial updates or introducing inconsistencies.

Manual documentation during release cycles fragments developer attention and introduces asynchronous bottlenecks. Every release, teams struggle with:

• Information overload: Sifting through merged PRs, cross-referencing issues, and translating technical changes into coherent updates.
• Lost productivity: Hours spent on release documentation mean less time for building features or fixing bugs, often resulting in inconsistent or incomplete notes.
• Notification overhead: Updating Notion, pushing Slack links, or syncing across multiple tools causes delays and missed updates, leaving everyone frustrated.

What if every PR merge triggered a reliable agent that automatically generated curated Notion pages, synced context-rich release notes using your existing repository metadata, and instantly posted a link to the correct Slack channel, without interrupting developer flow? That’s exactly what the GitHub to Notion release notes agent does. In this deep dive, you’ll learn the architectural decisions, API strategies, and implementation techniques behind building an end-to-end, idempotent auto-documenting release flow, and the concrete developer problems it solves.

Technical challenges behind manual release notes

Manually generating release notes seems simple at first glance, but it hides several technical challenges that become painfully apparent in real-world developer workflows. Handling multiple merged PRs, cross-referencing issues, and keeping documentation up-to-date quickly becomes a complex, error-prone process.

Processing numerous PRs: In active repositories, dozens of PRs might merge within hours. Tracking each PR’s metadata, title, description, author, SHA, and linked issues requires careful attention. Missing a single commit can result in incomplete release notes or miscommunication.

Synchronizing multiple tools: Release notes rarely live in GitHub alone. Teams often use Notion for documentation and Slack for notifications. Manually copying PR details into Notion and then sharing updates in Slack introduces friction, increases latency, and multiplies the opportunity for human error.

Ensuring idempotency: When automating, it’s crucial that each PR is processed exactly once. Reprocessing the same PR could create duplicate entries in Notion or spam Slack channels, which quickly erodes trust in the automation. Maintaining a reliable state and mapping between PRs and release notes is essential.

Delivering timely notifications: Teams expect immediate updates after a merge. Delays in creating release notes or sending Slack notifications slow down workflows, force developers to manually check for changes, and reduce confidence in release communication.

These challenges demonstrate why manual release notes don’t scale and why automation isn’t just convenient, it’s necessary. The GitHub → Notion release notes agent addresses each of these pain points systematically, which we’ll explore next.

Architecture overview of the automated release notes agent

The GitHub to Notion release notes agent is designed to handle the complexity of generating release notes automatically, integrating GitHub, Notion, and optionally Slack into a seamless workflow. Its architecture focuses on modularity, reliability, and idempotency, allowing developers to automate release documentation without disrupting their existing processes.

Core components

Polling server: The polling server periodically checks GitHub for merged PRs, typically every 60 seconds. It ensures that even in local or offline environments without public endpoints, PR merges are detected and processed reliably. The server maintains a polling_state.json to track processed PRs, preventing duplicates.

Webhook server: For production environments requiring instant updates, the webhook server listens for GitHub PR merge events in real time. This approach eliminates polling latency and ensures the immediate generation of release notes, ideal for continuous deployment pipelines.

Notion API service: This module handles all interactions with the Notion database. It formats PR metadata, title, SHA, description, repository, and status into Notion pages according to the predefined schema. The database schema includes properties like PR Number, Status, Summary, and Repository to keep release notes structured and searchable.

Scalekit OAuth connectors: Scalekit manages authentication and API calls for GitHub, Notion, and Slack. Developers don’t have to handle OAuth tokens manually; Scalekit ensures secure, unified access across all services. This abstraction simplifies integration and reduces the risk of exposing sensitive credentials.

Slack integration (Optional): Once a Notion page is created, the agent can send a Slack notification to a specified channel, providing a direct link to the release notes. This keeps the team informed in real time without manual intervention.

Idempotency and state management

A key architectural decision is idempotency. The agent tracks processed PR SHAs to ensure that each PR generates only one Notion page and one Slack notification, even if polling overlaps or webhook events are retried. This guarantees consistent and reliable release notes without duplicates.

Step-by-step setup of the GitHub to Notion release notes agent

Automating release notes isn’t just about connecting GitHub and Notion; it requires careful orchestration of authentication, API calls, and state management. In this section, we’ll break down how the GitHub → Notion Release Notes Agent works end-to-end, from initial setup to running the agent and understanding the code flow.

Step 1: Setting up integrations for automated release notes

Before the agent can generate release notes, it needs secure access to GitHub, Notion, and Slack. Each integration involves authentication, configuration, and mapping to ensure proper functionality.

GitHub: OAuth app for secure repository access

The agent needs to read pull requests and commit data from GitHub. Using OAuth ensures credentials are not hardcoded, keeps the system secure, and allows Scalekit to handle API calls on your behalf.

Setup steps:

1. Go to GitHub → Settings → Developer Settings → OAuth Apps → New OAuth App.

2. Fill in the details:
   
   • Application Name: Scalekit Agent
   • Homepage URL: https://hey.scalekit.dev
   • Authorization Callback URL: https://hey.scalekit.dev/oauth/callback
3. Click Register Application, then copy the Client ID and Client Secret.
4. Add these credentials to Scalekit under Connections → GitHub.

Why this matters:

• OAuth tokens are scoped to specific repositories or organizations, reducing security risks.
• Scalekit handles token refreshing, retries, and error normalization, so your Python code doesn’t have to deal with raw HTTP calls or rate limits.

The above flow shows how a developer authorizes Scalekit to access GitHub, Notion, or Slack using magic links

2. Notion: Creating a database for release notes

The agent needs a structured place to store release notes, with clear properties for automation and searchability.

Database creation steps:

1. In Notion, create a new Table database.

2. Add the following properties exactly as named:
   
   • Name (Title): PR title
   • PR SHA (Text)
   • PR Number (Number)
   • Repository (Text)
   • Status (Select) with option Merged
   • Summary (Text, optional)
3. Copy the Database ID from the URL (32-character hex string).
4. Share the database with your Scalekit account or workspace to grant access.

Technical notes:

• The agent uses the Notion API via Scalekit. Only the Title property is reliably set; all other metadata (SHA, PR number, status) is embedded as child blocks in the page.
• This design choice is due to limitations in the Notion API tool, but it still allows structured, queryable content.

3. Slack: Workspace authorization and user mapping

Slack is used to send real-time notifications about newly generated release notes.

Setup Steps:

1. Install the Scalekit app in your Slack workspace.
2. Identify the Channel ID where notifications should be posted. You can get this from the Slack web app URL (https://app.slack.com/client/TXXXXXXX/CYYYYYYY) → CYYYYYYY is the channel ID.
3. Create ^{user_mapping.json} to map Slack users to Scalekit identifiers:

Why is user mapping needed?

• Each Slack message must be posted on behalf of a valid Scalekit user.
• The mapping ensures messages are attributed correctly and the agent can fallback to a default identifier (^{SCALEKIT_DEFAULT_IDENTIFIER}) if a user isn’t mapped.

4. Environment configuration

All credentials and IDs are managed via a .env file to keep them out of source control:

Why is the environment config important:

• Centralizes sensitive information.
• Enables developers to switch between local, staging, and production environments easily.
• Makes the agent portable across machines and CI/CD pipelines.

Key takeaways for developers:

• OAuth ensures secure access to each platform.
• Notion database must follow a strict schema to support automation.
• Slack requires user mapping to post messages reliably.
• Environment variables keep credentials secure and configurable.

Step 2: Understanding core code modules and their logic

The agent is built around modular Python code, designed for clarity, maintainability, and integration with Scalekit. We’ll walk through the key modules, what they do, and how they interact with GitHub, Notion, and Slack. You can also refer to the sample app on GitHub for the full code.

1. ^settings.py: Central configuration

^settings.py manages all runtime configuration for the agent. It loads environment variables from .env (Scalekit credentials, GitHub repo info, Notion DB ID, Slack channel) and validates that required keys exist before execution. Flags like ^{NOTION_VIA_SCALEKIT} and ^{ALLOW_LOCAL_TESTING} control integration behavior and local testing.

Code snippet:

Explanation:

• ^load_env() reads and sets all environment variables.
• ^validate() ensures critical values exist, preventing runtime failures.
• ^{get_summary()} returns a safe snapshot of the configuration for debugging, without exposing secrets.

This module acts as a single source of truth for the agent, ensuring predictable behavior across polling, webhook, Notion, and Slack operations.

2. ^{sk_connectors.py}: Scalekit integration layer

^{sk_connectors.py} wraps the Scalekit SDK to simplify API interactions with GitHub, Notion, and Slack. Its responsibilities include executing tools, handling retries, and resolving user identifiers from Slack to Scalekit accounts. This abstraction allows developers to interact with multiple APIs reliably without managing OAuth tokens, retries, or error shapes manually.

Code snippet: Executing a tool with retries:

Explanation:

• Retries are performed automatically on transient failures, including rate limits or network errors.
• identifier resolves the user on whose behalf the action runs, using ^{user_mapping.json} or ^{SCALEKIT_DEFAULT_IDENTIFIER} as fallback.
• This mechanism ensures Slack messages or Notion inserts are reliable and attributed correctly.

The above flow shows how the users are mapped in Scalekit.

Code snippet: Resolving a user identifier:

Explanation:

• Maps Slack users to Scalekit identifiers.
• If the user isn’t mapped, the default identifier ensures the action executes without failure.

Developer perspective:

This module centralizes all API calls, retries, and user mapping logic, making the agent robust, idempotent, and easier to maintain. Developers don’t need to handle raw HTTP requests or token lifecycles, which significantly reduces boilerplate and potential errors.

3. ^{notion_service.py}: Building Notion payloads

^{notion_service.py} is responsible for converting GitHub PR data into structured Notion pages. It handles the title, description, metadata, commits, and links, then calls Scalekit to insert the page into the configured Notion database.

Code snippet: Constructing the notion payload:

Explanation:

• The Title property is mandatory; other metadata is embedded in child blocks due to Notion API limitations.
• Child blocks include the PR description, a callout with metadata, optional commit lists, and links.
• The ^{execute_action_with_retry} ensures the insertion is robust against transient errors and API rate limits.

Developer perspective:

This module abstracts the complexity of building Notion pages from PR data. It allows developers to automatically generate structured, readable, and searchable release notes while maintaining idempotency by embedding the SHA in the content blocks.

4. ^{polling_server.py}: Polling mode

^{polling_server.py} is responsible for periodically checking GitHub for merged PRs and processing them. It is ideal for local development or environments without a public endpoint, ensuring release notes are generated even without webhooks.

Code snippet: Polling loop:

Explanation:

• Fetches all recently closed PRs and filters out those already processed (^{polling_state.json}) to maintain idempotency.
• Each new PR is passed to ^{upsert_release_notes} to build and insert the Notion page.
• Slack notifications are sent via ^{post_slack_notification}, using the resolved Scalekit identifier for the PR author or the default.
• ^seen_prs is updated and persisted to avoid duplicate processing.
• The loop sleeps for ^{POLL_INTERVAL} seconds (configurable), balancing responsiveness with API rate limits.

Developer perspective:

Polling mode provides a reliable, incremental mechanism for generating release notes without requiring a public server or webhook setup. It ensures that all merged PRs are captured while maintaining consistency and avoiding duplicate notifications.

5. ^{webhook_server.py}: Webhook mode

webhook_server.py enables real-time processing of GitHub PR merge events. It is ideal for production or cloud environments where immediate release note creation is required. The module also provides endpoints for OAuth authorization and health checks.

Code snippet – Handling a PR merge webhook:

Explanation:

• Validates the webhook signature to ensure the request is from GitHub.
• Only processes PRs where merged=True, preventing unnecessary notifications for closed-but-unmerged PRs.
• Calls ^{upsert_release_notes} and ^{post_slack_notification} for immediate Notion page creation and Slack updates.
• Responds with the Notion page URL to confirm successful processing.

Code snippet – OAuth authorization endpoint:

Explanation:

• Generates a Scalekit magic link for authorizing Slack or Notion for a specific user.
• Supports dynamic authorization without exposing credentials in code.
• Useful for onboarding new developers or managing OAuth expirations.

Developer perspective:

Webhook mode eliminates polling latency, ensuring instant updates for merged PRs. The module also simplifies OAuth flows, enabling secure authorization of Slack and Notion accounts for multiple users without manual token management.

Step 3: End-to-end flow of a merged pull request

With integrations configured and core modules in place, the agent processes a merged PR from GitHub to Notion and Slack. The flow differs slightly between polling and webhook modes, but achieves the same goal: automated, idempotent release notes creation.

1. Polling mode flow

Polling mode periodically fetches closed PRs from GitHub and processes new merges.

The above flow shows how the agent periodically fetches merged PRs and processes them in batches while maintaining idempotency.

Steps:

1. Fetch merged PRs:

• Fetches recently closed PRs.
• Filters out PRs already processed (tracked in polling_state.json) to maintain idempotency.

2. Create Notion page:

^{upsert_release_notes(pr)}

• Builds payload with PR title, description, metadata, and links.
• Executes via Scalekit with retries for transient errors.
• Metadata like SHA, PR number, and repository are embedded in child blocks due to Notion API limitations.

3. Send Slack notification:

^{post_slack_notification(pr)}

• Posts the Notion page URL to the configured channel.
• Uses the mapped Scalekit identifier or the default for the PR author.

4. Update local state:

^{seen_prs.add(pr["number"])}

^{save_state(seen_prs)}

• Ensures the same PR is not reprocessed in future polling cycles.

5. Loop & sleep:

^{sleep(POLL_INTERVAL)}

• Runs at a configurable interval (default 60 seconds), balancing API rate limits and responsiveness.

Developer perspective:

Polling mode provides a simple, reliable fallback where webhooks are unavailable. Incremental processing ensures all PRs are captured without duplication, and local state tracking guarantees consistent release notes.

2. Webhook mode flow

Webhook mode enables real-time processing when GitHub sends PR merge events directly.

The above flow illustrates how the agent processes PR merge events immediately for real-time Notion page creation and Slack notifications.

Steps:

1. Receive webhook event:

• Signature validation ensures the event is authentic.
• Only merged PRs trigger processing.

2. Process PR:

• Builds Notion payload with metadata, description, and links.
• Posts Slack notification immediately after page creation.

3. Respond to GitHub:

^{return {"notion_page_url": notion_url}, 200}

• Confirms successful processing and returns the Notion page link.

Developer perspective:

Webhook mode provides instant feedback for merged PRs, improving team visibility. It eliminates polling delays and leverages OAuth endpoints for secure, dynamic authorization of Notion and Slack accounts.

3. Error handling and resilience

• Retries: ^{execute_action_with_retry} automatically retries transient API failures (e.g., rate limits or network errors).
• Safe logging: Truncates long PR descriptions and metadata in logs to avoid flooding.
• Fallback identifiers: Ensures messages and page inserts succeed even if a Slack user isn’t mapped.
• Partial idempotency: SHA stored in Notion blocks prevents duplicate pages when the API cannot deduplicate by property.

4. Conceptual data flow

This flow ensures automated, reliable, and consistent release notes, visible to both developers and the team immediately.

Step 4: Running and testing the agent

With integrations configured and core modules understood, the agent can be run in polling or webhook mode. Testing and monitoring ensure reliable behavior in both local and production environments.

1. Local testing with ^{test_any_pr.py}

Developers can simulate a PR merge without interacting with real GitHub events:

• Sends a signed payload to ^{/webhook/github}.
• Validates Notion page creation and Slack notifications locally.
• Supports ^{GITHUB_WEBHOOK_SECRET} for signature verification.

Why: Safe end-to-end testing ensures payload formatting, block structure, and notifications work as expected before production deployment.

2. Running in polling mode

Polling mode periodically checks GitHub for merged PRs and processes them:

^{python polling_server.py}

Flow highlights:

• Uses ^{polling_state.jso}n to maintain idempotency.
• Configurable interval balances responsiveness with GitHub API limits.
• Can run with ^--once to process a single polling cycle for testing.

3. Running in webhook mode

Webhook mode enables real-time PR processing:

^{python webhook_server.py}

Flow highlights:

• Validates webhook signatures for security (can bypass locally for testing).
• Processes merged PRs immediately, creating Notion pages and posting Slack notifications.
• OAuth endpoints handle secure, dynamic authorization for Notion and Slack accounts.

4. Monitoring and troubleshooting

Common checks:

• PR not detected → Confirm the PR is merged and the repository configuration is correct.
• Notion page missing → Verify database access and Scalekit authorization.
• Slack notification missing → Check channel ID and user mapping.
• OAuth token expired → Re-authorize via ^/auth/init.

Best practices:

• Monitor logs for retries and errors in ^{execute_action_with_retry}.
• Use local testing to validate changes before production deployment.
• Periodically ^{check polling_state.json} to ensure proper tracking of processed PRs.

Developer perspective:

This step ensures that the agent runs reliably in both local and production setups. Polling mode provides a lightweight, offline-friendly solution, while webhook mode enables instant, real-time automation. Combined with robust monitoring and testing, the system guarantees consistent, idempotent release notes with minimal manual intervention.

5. Monitoring and troubleshooting

Common checks:

• PR not detected → Verify ^{GITHUB_REPO_OWNER} and ^{GITHUB_REPO_NAME}. PR must be merged.
• Notion page missing → Check ^{NOTION_DATABASE_ID} and Scalekit authorization.
• Slack notification missing → Verify channel ID and user mapping.
• OAuth token expired → Re-authorize via ^/auth/init.

Best practices:

• Monitor logs for errors in execute_action_with_retry.
• Use local testing to validate changes before production.
• Periodically check polling_state.json for accuracy.

Developer perspective:

This step ensures the agent runs reliably, whether locally or in production. Polling mode offers a lightweight, local-friendly solution, while webhook mode provides instant, real-time automation for production deployments. Proper monitoring and testing guarantee consistent, idempotent release notes with minimal manual intervention.

How automated release notes improve developer productivity and reliability

The GitHub → Notion Release Notes Agent doesn’t just automate tasks; it directly addresses common pain points in release management, improving productivity, accuracy, and team communication.

1. Eliminates manual release note overhead

• Automatically extracts PR title, description, metadata, and links.
• Builds structured Notion pages with child blocks for SHA, repository, status, and optional commit summaries.
• Prevents inconsistent or incomplete release notes caused by manual summarization.

Impact: Saves hours of manual work, reduces errors, and ensures every PR is accurately documented.

2. Ensures timely and reliable notifications

• Sends Slack notifications immediately after a PR is processed (polling or webhook).
• Keeps teams informed without manually tracking merged PRs or switching between tools.

Impact: Improves team visibility, reduces context switching, and accelerates decision-making during releases.

3. Supports idempotency and scalability

• Tracks processed PRs via ^{polling_state.json} to prevent duplicates.
• Handles multiple simultaneous PR merges reliably.
• Can scale to multiple repositories by adding GitHub and Notion credentials through Scalekit.

Impact: Builds trust in automation and supports adoption in large, active projects without duplicating work.

4. Simplifies multi-platform integration

• Scalekit manages OAuth, retries, and API calls for GitHub, Notion, and Slack.
• Developers no longer need to manage tokens, rate limits, or API inconsistencies.
• Slack user mapping ensures notifications are attributed correctly.

Impact: Minimizes boilerplate, reduces errors, and allows developers to focus on building features rather than managing integrations.

5. Facilitates testing and safe iteration

• ^{test_any_pr.py} allows local simulation of PR merges, validating Notion pages and Slack notifications.
• Developers can test schema changes or workflow adjustments safely before production.

Impact: Encourages experimentation while reducing downtime and operational risk.

6. Real-world productivity gains

• Faster, consistent documentation of all merged PRs.
• Immediate visibility of changes across Notion and Slack.
• Fewer errors and miscommunications during releases.
• Streamlined workflows that allow developers to focus on coding rather than administrative tasks.

Developer perspective:

The agent translates technical automation into practical value, ensuring release notes are accurate, notifications are timely, and teams maintain focus on shipping features. The result is a predictable, scalable, and efficient release process that eliminates the stress of manual release note management.

Conclusion: Closing the loop on release notes pain points

Remember the scenario from the introduction: it’s the critical moments before a deployment, your team is merging the last PRs, and someone asks, “Do we have the release notes ready?” Traditionally, this question triggers hours of manual work, sifting through commits, drafting notes, updating Notion, and posting Slack messages, fragmenting attention and increasing the risk of errors.

The GitHub → Notion Release Notes Agent directly solves this problem. By automating the creation of release notes from merged PRs, inserting them into a structured Notion database, and posting notifications to Slack, the agent removes manual overhead, reduces context switching, and ensures consistent, accurate documentation. Whether running in polling mode or via webhook, it guarantees timely updates, handles retries and transient errors, and preserves idempotency to prevent duplicates, all while maintaining developer-friendly configurations and secure OAuth-based authentication.

Next steps for developers:

• Try it locally: Use ^{test_any_pr.py} to simulate PR merges and validate Notion and Slack integration.
• Deploy in production: Run the webhook server to automatically generate release notes in real time.
• Explore Scalekit further: Learn how the platform can unify integrations for other workflows beyond release notes.
• Iterate and customize: Adjust the Notion database schema, add commit details, or extend Slack notifications to suit your team’s workflow.

With the agent in place, your team can focus on shipping features, confident that every PR merge is automatically documented and communicated, eliminating the familiar stress of “Where are the release notes?” once and for all.

FAQ

1. How does Scalekit simplify OAuth and API integration for GitHub, Notion, and Slack?

Scalekit acts as a unified integration layer, handling OAuth authentication, token refreshing, and API retries for GitHub, Notion, and Slack. Developers can securely execute actions like notion_database_insert_row or slack_send_message without managing raw API calls, rate limits, or credentials, ensuring reliable automation of release notes and notifications.

2. Can Scalekit handle idempotency and error retries when automating release notes?

Yes. Scalekit provides robust retry mechanisms with exponential backoff for transient API failures (like 429 rate-limit errors) and ensures idempotent operations through local state management and user mapping. This prevents duplicate Notion pages or redundant Slack notifications when processing GitHub pull requests.

3. How does the GitHub to Notion Release Notes Agent handle multiple merged pull requests efficiently?

The agent fetches merged PRs using github_pull_requests_list and filters out previously processed PRs using polling_state.json. It then builds structured Notion payloads and posts Slack notifications in batches, maintaining idempotency and minimizing API calls to handle high-volume repositories without data loss.

4. Why is the Notion database schema important for automated release notes?

A precise Notion database schema with properties like PR SHA, PR Number, Repository, Status, and Summary ensures that automated release notes remain searchable, structured, and consistent. Child blocks store metadata and descriptions, allowing queries and analytics on PR activity while overcoming API limitations of property-only updates.

5. How can Slack user mapping improve automated notifications for PR merges?

Mapping Slack user IDs to Scalekit identifiers ensures that notifications are posted on behalf of the correct developer, maintaining accountability and context. This mapping also enables fallback to a default identifier, preventing failed message posts when an unmapped user triggers a pull request merge, ensuring consistent team communication.