How to store architecture diagrams in GitHub
Connect a repository and store architecture there, so the diagram travels with the code rather than beside it.
When this is useful
- Architecture documentation keeps drifting because it lives somewhere the engineers do not go.
- You want an architecture change to be reviewable in the same place as a pull request.
- The repository is already the system of record for everything else about the system.
Before you start
- A GitHub repository you can write to, and the GitHub integration enabled for your organisation.
Step 1: Connect the repository
The GitHub connection and the repository settings are both in the Arch menu.
Arch ▸ GitHubArch ▸ Repository
Step 2: Decide where architecture lives in the repo
Put it near the code it describes. Architecture in a repository nobody clones is architecture nobody updates — the location is most of the benefit.
Step 3: Review architecture changes like code changes
Once the architecture is in the repository, an architecture change can go through the same review as a code change, and the approval workflow covers the sign-off that a pull request review does not.
Diagram ▸ Approval workflowDiagram ▸ Version history
What happens next
Combined with an architecture imported from code, this closes the loop: the codebase produces the diagram, and the diagram lives with the codebase.
Example
A platform team that moved architecture into the service repository found the documentation updated in the same pull requests as the changes it described — for the first time without anyone chasing it.
Tips
- Agree the location before the first commit. Moving it later is easy; getting everyone to look somewhere new is not.
Limitations
- GitHub storage is separately enabled.
- Commit access is governed by your GitHub permissions, not by Yantra Studio.