An architecture decision record in GitHub or GitLab can be a very good home for the reasoning behind a technical choice. The record sits beside the code, the proposed change can be reviewed, and the next engineer has somewhere to look when they need to understand why things were built this way. If a team already does this well, there is value in keeping it there.
ADRs deserve credit for taking the reasoning seriously. AWS's guidance describes a process with an owner, review, acceptance and a history of decisions. When the answer changes, a new ADR supersedes the old one. A team following that process has already done something useful about the departure and the re-argument: the person who knew why can leave without taking the only explanation with them.
The question I care about is who else needs to be part of the decision, and whether the process works for them too.
A choice about a software dependency might sit comfortably inside one engineering team. A choice about a supplier, a customer exception or a change to an operating policy can involve engineering, operations, finance, risk and the person accountable for the business commitment. The technical reasoning still matters. So do the commercial conditions, the alternatives rejected and the authority to accept the consequences. Someone has to keep that whole decision understandable to the people who will act on it.
GitHub lets people edit files and preview changes in a browser. Its comment fields have formatting tools so a reviewer does not have to learn Markdown syntax just to contribute a formatted comment. GitLab has a browser Web Editor and rich text editing for wikis, issues, merge requests and other supported surfaces. Editing a repository file and joining a discussion are different activities, with different interfaces.
Both products also offer configurable review controls. GitHub can require approving reviews before a pull request is merged, and can dismiss stale approvals when the proposed change changes. GitLab offers required merge approvals on Premium and Ultimate. These controls govern merges. The team still has to define how a merge approval represents acceptance of the business decision.
GitLab's own architecture workflow is a useful example of the process around the document. It calls for stakeholder consultation, identifies who has the final decision, and distinguishes people who should be consulted from people who can block a proposal. Those are governance questions. A file in a repository can be part of a serious answer to them.
There is also a candid example in the US Department of Health and Human Services' Simpler Grants architecture decision. The project chose repository ADRs because they travel with the code, fit the issue and pull-request workflow, and retain changes in commit history. It also recorded a possible difficulty for nontechnical contributors unfamiliar with Markdown or GitHub. That is one project's stated trade-off. It gives a buyer something specific to test, rather than a reason to dismiss the tool.
I would start that test with the people who actually need to make the decision. Give the engineer, the business approver and the risk or operations reviewer the access you intend them to have. Ask each to find the proposal, understand the alternatives, challenge the reasoning and carry out their part of the approval. Watch where they need someone else to translate, copy information between places or act on their behalf. You may find that the repository workflow works well for everyone. You may find that some of the business decision is being settled somewhere else.
Be specific about what an approval means. A reviewer might be confirming that a technical approach is sound. Another person might be accepting a supplier commitment or an operating risk. The process needs to make those responsibilities clear and collect the approvals it actually requires. Then change something material in the proposal and check what happens. Which approval is still valid? Who needs to look again? Can someone later retrieve the version they approved and the reason for accepting it? These are questions I would ask of any decision system, including Traceway.
Finding the record later deserves the same attention as writing it. Ask someone outside the delivery team to recover the decision from the business question they have, without knowing a repository name or who wrote the ADR. Then have them follow it to the affected work. A shared documentation repository, an index or a published view may solve that need. The point is to test the route your organisation will use, with its actual access rules, rather than assume the record is useful to everyone because it is available to the team that created it.
I built Traceway for decisions that need that wider business participation, with the rationale, alternatives, accountable approval and resulting work kept together. Trace, the native AI in Traceway, is part of that experience: people can work conversationally to draft and refine a decision, then review it and take it through human approval. The conversation connects to a shared record and to the strategy and work around it. The AI does not take the authority to decide from the people responsible.
An engineering team can keep its ADRs where they are useful. A business decision record can sit alongside them, provided the connection is clear and somebody owns keeping it accurate. When a supplier changes, a policy is revisited or the person who made the call leaves, the people responsible for the next decision should be able to recover what was agreed and why. If this is a question your team is working through, we can discuss it in a demo.