Keep in sync
Repositories
Architecture documentation drifts the moment the code moves on, and nobody volunteers to redraw it. A repository connection turns a GitHub, GitLab, or Azure DevOps repo into a diagram and a written architecture doc that keep themselves current: Datadef reads a bounded selection of the repo's most architecture-dense files, generates both, and re-syncs about once a day, skipping the work entirely when the branch has not moved. Repository connections are a paid-plan feature.
How it works
- 1Connect the repo. Public repos need only their reference; private ones take a read-only token that is validated, then stored encrypted.
- 2Pick a branch or tag. Datadef reads the repo at that ref and generates a diagram plus an architecture doc, grounded only in the files it read.
- 3The diagram re-syncs about once a day on its own, and you can refresh manually anytime, from the repositories page or over MCP.
- 4Edit, share, and embed the project like any other. Unlink whenever you want; the project survives with its content.
Supported providers
| Provider | Host | Repository reference |
|---|---|---|
| GitHub | github.com | owner/repo |
| GitLab | gitlab.com | Full project path, subgroups included: group/subgroup/repo |
| Azure DevOps | dev.azure.com | organization/project/repo |
Self-hosted instances (GitHub Enterprise Server, self-managed GitLab, Azure DevOps Server) are not supported yet: connections always talk to the cloud hosts above.
Connecting a repository
A connection is the repo plus, for private repos, a token. Public repos need no token at all: enter the reference and connect.
For private repos, create a read-only personal access token. Exact scopes per provider:
GitHub
Use a fine-grained personal access token (Settings, Developer settings, Fine-grained tokens) scoped to the one repository, with the repository permission Contents: Read-only. GitHub adds Metadata: Read-only automatically. A classic token with the repo scope also works, but that scope includes write access, so prefer fine-grained.
GitLab
Create a personal access token with the read_api scope. Datadef lists branches, tags, and the file tree through the GitLab API, which is what this scope grants read access to.
Azure DevOps
Create a personal access token with the Code: Read scope for the organization that owns the repo.
How tokens are handled
The token is validated immediately by listing the repo's branches, then stored encrypted (AES-256-GCM). After that, Datadef shows only its last 4 characters, and the token never appears in logs, API responses, or error messages. Datadef never writes to your repository; the token is used for reads only.
Creating a diagram from a repo
From a connection, pick a branch or tag and create a diagram. Datadef creates a new project, reads the repo at that ref's current commit, and generates two things:
- The diagram: the project's working canvas, editable like any other Datadef diagram.
- An architecture doc in markdown: an overview, a component inventory, the data flow, how the system deploys, and notes per notable directory. It is grounded only in the files that were read; services that do not appear in the repo do not appear in the doc.
Generation runs in the background; the link shows its status and finishes on its own. One connection can back several diagrams: a diagram per service branch, or one per release tag.
Inside the diagram, the Canvas tab of the right-hand panel is where the repo link lives: it shows the tracked branch or tag, the sync status and controls, and the architecture doc with copy and download.
What Datadef reads
Not the whole repo. Datadef selects up to 40 files, 250KB total, in priority order, plus a compact summary of the directory tree:
| Priority | Files |
|---|---|
| 1. Infrastructure as code | *.tf, serverless.yml, cdk.json, Pulumi and CloudFormation templates |
| 2. Containers and orchestration | Dockerfile, docker-compose*, Kubernetes and Helm YAML |
| 3. Data | dbt_project.yml with model SQL, SQL DDL, prisma/schema.prisma, sampled migrations |
| 4. APIs | OpenAPI and Swagger specs, *.proto, GraphQL schemas |
| 5. CI | .github/workflows/*, .gitlab-ci.yml, azure-pipelines.yml |
| 6. Manifests | package.json, pyproject.toml, go.mod, pom.xml, Cargo.toml, composer.json |
| 7. Prose | README files and docs/architecture* |
Files over 30KB are truncated with a marker; binaries, lockfiles, and vendor directories like node_modules are skipped. The consequence worth knowing: the diagram is grounded in these files, so architecture that lives nowhere in them will not be drawn.
Keeping it fresh
- Daily sync runs about once a day per linked diagram while it is enabled (it is on by default, and can be turned off per diagram).
- Manual refresh re-syncs on demand, from the repositories page or through the MCP
repo_refreshtool. - Unchanged means untouched. Every sync first resolves the ref's head commit; if it matches the last synced commit, nothing is regenerated.
- Daily sync only runs while the connection owner's plan is active. A lapsed account keeps its diagrams but background syncs stop.
Sync regenerates the diagram
In this first version, a sync rebuilds the diagram from the repo. Manual edits you made on the canvas may be replaced on the next refresh. If you want to hand-tune a repo diagram, turn off daily sync for it first, or unlink it; a published version also preserves the state you want to keep.
Unlinking and deleting
- Unlinking a diagram removes only the link to the repo. The project survives with its current content; it just stops syncing.
- Deleting a connection removes the stored token and all of its links. Every project survives with its last synced content.
From agents
Two MCP tools cover repo-linked diagrams, using the project id: repo_status reports the link, connection, and freshness; repo_refresh triggers a sync. See MCP and agents for setup.
Troubleshooting
| Status | Meaning | Fix |
|---|---|---|
auth_failed | The provider rejected the token: revoked, expired, or missing the read scope. | Create a fresh token with the exact scope listed above and reconnect the repository. |
not_found | The provider says the repo does not exist for this token. | Check the reference spelling and casing. On GitHub, a fine-grained token must explicitly include the repository. A renamed or deleted repo, or a public repo that went private on a tokenless connection, also lands here. |
Sync failed | The last sync errored; the message is shown with the link. | Read the error, fix the cause, and run a manual refresh. The previous diagram is untouched. |
Stuck on running | A sync crashed mid-run. | A sync that has shown running for more than 10 minutes is considered stale and can simply be retried. |
Further reading