Google Docs Session Sync Automation
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Google Docs Session Sync Automation is a system designed to automate the publication of development session summaries from the repository to a Google Doc. This feature ensures that the SESSION_SUMMARY.md file, which tracks daily progress and initiatives in both English and French, is synchronized to a central document for external communication and stakeholder review.
The system utilizes the Google Docs API and a dedicated Python script to handle authentication and document updates. It supports multiple execution modes, including local manual runs and scheduled automation via GitHub Actions. This automation fulfills project requirements for traceability and "always leaving a trail" of AI-assisted development sessions.
Sources: GOOGLE_DOCS_SYNC.md:1-5, README.md:162-170, copilot-instructions.md:139-145
Architecture and Components
The automation architecture follows a "Spokes" model where the synchronization script acts as an adapter between the project core (the summary markdown file) and an external API (Google Docs).
Core Components
- Sync Script:
scripts/publish_session_summary_to_gdocs.pyhandles the reading of the source markdown, authentication with Google Cloud, and the construction of API requests. - Google Cloud Service Account: Provides the necessary credentials to interact with the Google Docs API without requiring user-interactive login.
- GitHub Actions Workflow: A CI/CD component that triggers the sync script on a schedule (weekdays at 22:30 UTC) or manually.
- Environment Configuration: Uses environment variables and repository secrets to manage sensitive information like Doc IDs and service account keys.
Sources: scripts/publish_session_summary_to_gdocs.py:12-25, GOOGLE_DOCS_SYNC.md:30-41, copilot-instructions.md:37-43
Data Flow Diagram
The following diagram illustrates how session data moves from the local repository to the final Google Document.
This diagram shows the relationship between the source markdown file, the Python execution script, and the Google Cloud infrastructure.
Sources: scripts/publish_session_summary_to_gdocs.py:167-185, GOOGLE_DOCS_SYNC.md:15-32
Authentication and Security
The system supports two primary authentication methods for the Google Cloud service account to accommodate different environments.
Authentication Methods
| Method | Description | Implementation |
|---|---|---|
| Service Account File | Uses a local JSON key file path. | --service-account-file or GOOGLE_SERVICE_ACCOUNT_FILE env var. |
| Service Account JSON | Uses the raw JSON string content. | --service-account-json or GOOGLE_SERVICE_ACCOUNT_JSON env var. |
Sources: scripts/publish_session_summary_to_gdocs.py:14-25, GOOGLE_DOCS_SYNC.md:15-28
Security Constraints
- Service account JSON keys must never be committed to the repository.
- The
.gitignorefile is configured to excludegoogle-service-account.jsonand*.service-account.json. - The service account must be granted the "Editor" role on the target Google Doc.
Sources: GOOGLE_DOCS_SYNC.md:43-47, scripts/publish_session_summary_to_gdocs.py:126-130
Synchronization Logic
The sync script provides flexible modes for how the content is presented in the destination document.
Update Modes
- Append Mode: Adds a new timestamped block to the end of the document. This is the default mode used for daily progress tracking.
- Replace Mode: Deletes the existing content of the document body and replaces it entirely with the latest content of
SESSION_SUMMARY.md.
Sources: scripts/publish_session_summary_to_gdocs.py:65-70, GOOGLE_DOCS_SYNC.md:34-36
Execution Sequence
The script follows a deterministic sequence to ensure the document is updated correctly:
- Read Source: Loads the text from the specified markdown file (default
SESSION_SUMMARY.md). - Build Payload: Wraps the markdown text with a UTC timestamp header.
- Authenticate: Loads credentials from the file or environment variable.
- Initialize Service: Builds the Google Docs "v1" discovery service.
- Create/Retrieve Doc: Checks for an existing
--doc-id. If missing, it creates a new document with the provided--title. - Batch Update: Calculates the
endIndexof the document and sends abatchUpdaterequest containing eitherdeleteContentRange(for replace mode) andinsertTextinstructions.
Sources: scripts/publish_session_summary_to_gdocs.py:136-155, scripts/publish_session_summary_to_gdocs.py:167-185
This sequence diagram details the interaction between the script and the Google Docs API during an update cycle.
Sources: scripts/publish_session_summary_to_gdocs.py:133-164
Configuration and CLI Reference
The automation is configured via command-line arguments which can also be mapped to environment variables.
CLI Arguments
| Argument | Default | Description |
|---|---|---|
--source | SESSION_SUMMARY.md | Path to the markdown file to be uploaded. |
--doc-id | os.getenv("GOOGLE_DOC_ID") | The unique ID of the target Google Doc. |
--mode | append | Synchronization behavior: append or replace. |
--title | NeuralDBG Daily Work Summary | Title used if a new document must be created. |
--dry-run | False | Prints the payload to the console without calling the API. |
Sources: scripts/publish_session_summary_to_gdocs.py:42-80
Integration with Project Milestones
The development of this automation was established as a core DevOps/MLOps task in Milestone 0. It serves the "Session Sync Automation Script" task, intended to save approximately 15 minutes per session in administrative overhead by converting session summaries for external communication.
Sources: infrastructure_planning/milestone_0_tasks.md:68-72, CHANGELOG.md:12-16
Conclusion
The Google Docs Session Sync Automation is a critical infrastructure tool for NeuralDBG, ensuring that the mandated traceability rules are met with minimal manual effort. By bridging the gap between local development logs and shared cloud documentation, it maintains a transparent and up-to-date record of project evolution.