Setup Guide for the Repository Synchronization Agent

This document details the necessary procedures for deploying the PR Synchronization Agent, which establishes a bidirectional link between your GitHub source control management system and your Notion knowledge base/project management environment.

Prerequisites for Operation

Before commencing installation, ensure the following system components are readily available: - The curl utility (essential for Unix-like operating systems: macOS/Linux). - A functional installation of Python version 3.x on your host machine.

Installation Procedures

Phase 1: Installing the uv Package Manager

For MacOS/Linux Environments: Execute the following command to fetch and run the installer script for uv: bash curl -LsSf https://astral.sh/uv/install.sh | sh

🔄 Crucial Note: After script execution completes, initiate a new terminal session. This step is mandatory to correctly integrate the uv executable into your system's PATH environment variable.

---

Phase 2: Initializing and Configuring the Project Structure

For MacOS/Linux Environments: bash

Establish a dedicated directory for the synchronization project

uv init repo_sync_tool cd repo_sync_tool

Construct and activate the isolated Python virtual environment

uv venv source .venv/bin/activate

Incorporate essential software packages (MCP framework, HTTP client, env management, Notion SDK)

uv add "mcp[cli]" requests python-dotenv notion-client

---

Phase 3: Defining Dependencies via requirements.txt and Installation

Generate a file named requirements.txt containing the precise dependency specifications:

txt

Defined dependencies for the Synchronization Engine

requests>=2.31.0 # Required for communicating with the GitHub API python-dotenv>=1.0.0 # Used for securely loading environmental configurations mcp[cli]>=1.4.0 # Core framework component for server operations notion-client>=2.3.0 # SDK for interacting with the Notion API

Execute the dependency installation routine: bash uv pip install -r requirements.txt pip install -r requirements.txt

---

Phase 4: Configuring Environment Secrets

In the project's root directory, create a configuration file named .env and populate it with the required credentials:

env GITHUB_TOKEN=your_github_secret_token NOTION_API_KEY=your_notion_secret_key NOTION_PAGE_ID=your_target_notion_page_identifier

Acquiring the GitHub Access Credential:

1. Navigate to GitHub: Settings → Developer Settings → Personal Access Tokens.
2. Select the option: "Generate new token (classic)".
3. Grant the following minimum access permissions (scopes):
4. read:org
5. read:repo_hook
6. repo (Full control of private repositories is often needed)
7. Securely copy the generated token and assign it to the GITHUB_TOKEN variable in your .env file.

Establishing the Notion Connection Details:

1. Visit the Notion Developer Integrations Page.
2. Initiate the creation of a New Integration, selecting the Internal classification.
3. Ensure this new integration is associated with the correct workspace.
4. Retrieve the Internal Integration Secret and assign it to NOTION_API_KEY.
5. Extract the unique identifier (UUID) found at the terminus of the integration setup URL; this value becomes NOTION_PAGE_ID.

---

Phase 5: Creating the Primary Execution Script

Generate the foundational script file where the application logic will reside:

bash touch sync_engine.py

Populate sync_engine.py with your application's operational code.

---

Phase 6: Initiating the Application Service

With the virtual environment active and the .env file correctly populated, you can launch the synchronization service:

bash python sync_engine.py

---