-
-
Synkron
-
Inspiration
Every developer knows the feeling: you ship a clean piece of code, close your laptop, and two weeks later a teammate opens an issue saying the API docs are wrong. Not broken code wrong. Just out of date. The feature changed, the behaviour changed, but the documentation was never told.
This is not a discipline problem. It is a tooling problem. Documentation sits outside the pull request workflow, so it never gets the same automated attention that code does. You have linters, formatters, CI pipelines, and type checkers watching every commit, but nothing watches the docs. That gap is what Synkron was built to close.
What Synkron Does
Synkron connects to any GitLab repository and listens for code pushes. When a developer commits new code, Synkron automatically analyses what changed, identifies which documentation files are actually relevant to that change, rewrites only the affected sections, and opens a merge request titled "Docs:" for the developer to review and merge.
The human is always in the loop. Synkron never force pushes to main. It proposes the documentation update the same way a colleague would: as a merge request, ready for review.
How We Built It
The entire pipeline runs on Google Cloud. A FastAPI backend receives GitLab push webhooks, validates them using per repository tokens stored in MongoDB Atlas, and dispatches the documentation job to Google Cloud Tasks. Cloud Tasks then calls the internal pipeline endpoint, which runs the agent.
The core of Synkron is a Google ADK LlmAgent powered by Gemini 3.1 Flash Lite, connected to the official @zereight/mcp-gitlab MCP server over stdio. The agent does not follow a fixed sequence of function calls. It reads its goal in plain language and picks the right MCP tools at each step: fetching diffs, listing the repository tree, reading documentation files, creating branches, committing updates, and opening merge requests. Every one of those actions goes through the MCP server, making this a genuine Model Context Protocol integration rather than a wrapper around direct API calls.
The agent runs in process on Cloud Run, which turned out to be architecturally important. The MCP server spawns as a Node.js subprocess communicating over stdio. Running the agent on the same Cloud Run instance means the subprocess is always co located with the agent, with no network hop and no dependency on a managed runtime that might restrict subprocess execution.
The frontend is a multitenant SaaS dashboard built with TanStack Start and secured with Firebase Authentication. Any developer can sign in, connect their GitLab repository through the dashboard, and start receiving automated documentation merge requests immediately.
The Feedback Loop
The feature that separates Synkron from a one shot automation is the feedback loop. When a developer reviews a Synkron merge request and edits the proposed documentation before merging, that edit is a signal. It tells the system exactly how a human would have written it differently.
Synkron captures those edits by listening to GitLab merge request webhook events. When a "Docs:" MR is merged, it compares the final merged content to what the agent originally wrote, stores the correction pattern in MongoDB, and uses that context to improve future documentation runs on the same repository. Over time the system learns the team's writing style, terminology preferences, and structural conventions without any configuration.
Challenges We Ran Into
The hardest technical challenge was making the MCP agent reliable on Cloud Run's scale to zero infrastructure. Early versions of the agent would time out during MCP session initialisation before any tools were called. This required tuning the session timeout and ensuring the MCP server binary was preinstalled in the Docker image rather than fetched at runtime.
Rate limiting on the Gemini API free tier required careful architecture. An agentic pipeline that calls the model at each reasoning step can make ten or more requests in under a minute. With default queue settings, a failed run was retried immediately, creating concurrent runs that collectively exhausted the per minute quota in seconds. The fix was configuring Cloud Tasks to allow a single concurrent dispatch with no automatic retries, so one push always maps to exactly one pipeline attempt.
Webhook security across multiple tenants was also more complex than it first appeared. Each connected repository gets its own randomly generated token, stored as a SHA256 hash in MongoDB. The pattern of using a single shared webhook secret, which many similar tools rely on, is a real security weakness: one leaked token compromises every connected repository. Synkron avoids that entirely.
Accomplishments We Are Proud Of
Watching the full pipeline work end to end for the first time was genuinely satisfying. A code push lands on GitLab, the webhook fires, Cloud Tasks dispatches the job, the ADK agent connects to the MCP server, tools start firing in the logs, and seconds later a real merge request appears on GitLab with accurate, contextually relevant documentation changes. The system does in under a minute what would otherwise take a developer ten minutes and almost always gets skipped.
The multitenant architecture went further than most hackathon projects: real tenant isolation, per repository token security, and a feedback loop that makes the system measurably better over time.
What We Learned
Running a stateful MCP subprocess inside a stateless Cloud Run container required rethinking standard assumptions about ephemeral infrastructure. The asyncio interactions in the ADK agent, particularly around task boundaries and session lifecycle, revealed edge cases that only surface under real network conditions.
The most important lesson was about agent prompt design. The initial version tried to do too much in one pass and often lost track of context mid workflow. Rewriting the instruction as a numbered workflow in intent language, describing what to accomplish at each step rather than which function to call, dramatically improved reliability and made the agent's decisions much easier to trace in the logs.
What's Next for Synkron
Synkron is genuinely useful today for teams maintaining GitLab repositories with active documentation. The immediate next step is injecting the accumulated correction patterns as a per repository system prompt on every agent run, so the style learning becomes automatic and cumulative rather than stored and unused.
Further out: GitHub support, richer diff views in the dashboard, and a self hosted deployment option for teams with data residency requirements.
Log in or sign up for Devpost to join the conversation.