Six months ago, a finance team using AI meant one analyst with a clever prompt. Today it means a dozen skills, a close checklist an agent runs, three scripts that pull from the ledger, and a convention file that tells Claude which sign the expenses carry. All of it lives somewhere. Usually on the laptop of the person who wrote it.
Alyona Mysko, who writes The Finance Engineer, put the symptom well when her own team started building: files everywhere, nothing standardized, and automations that left on holiday with their owners. Her answer is the one developers reached twenty years ago. Put the work in a shared repository.
This guide is the finance version of that setup, with a free repo template you can copy at the end: what GitHub gives a finance team, the two-repo structure, what goes in each, how a change reaches production, and the two details most guides skip (a paid-plan feature you need, and the Excel file git cannot read).
Why GitHub and Not a Shared Drive
A shared drive holds the latest file. That is its whole job. It does not tell you what changed between the version that worked in September and the one that broke during the October close, it does not stop anyone from saving over a colleague's work, and it puts the vendor mapping for every subsidiary in the same folder as the skill that reads it.
GitHub adds three things.
| Shared drive | GitHub | |
|---|---|---|
| History | Last version, sometimes a short revision log | Every version of every file, with who changed it and why |
| Control | Anyone with access can overwrite | A change waits in a pull request until someone approves it |
| Separation | Folders, same permissions everywhere | Separate repositories, separate permissions |
The history is what you will use first. A skill that misclassifies accruals on day three of the close is not a crisis when you can open the version from last month, see the two lines that changed, and roll back.
The five words you need
- Repository (repo): a project folder GitHub tracks.
- Branch: your working copy of a change, separate from the shared version.
- Commit: a saved change, with a one-line note on why.
- Pull request (PR): "I changed this, please review it."
- Merge: the approved change joins the shared version.
That is enough vocabulary for a finance team. Nobody needs to learn rebasing.
Step 1: An Organization, Not a Personal Account
Create the repos under a GitHub organization named after the company (acme-finance), not under the CFO's personal account. An organization means the repos belong to the finance function. When someone leaves, their access goes; the work stays.
Fifteen minutes: create the organization, ask each person on the team for their GitHub username, invite them under People.
Step 2: Two Repos, Not One
This is the rule that makes the rest safe.
finance-logic: everything you would reuse at another entity, or at another company. Skills, prompts, agent workflows, the close checklist, reconciliation checks, the convention file. No company data. The whole team can read it.
finance-data: everything specific to this company. Chart-of-accounts mappings, entity settings, vendor rules, exported reports, the output of a run. Access is narrower, and it may differ by entity.
The test for where a file goes is one question: would this file be useful, unchanged, at a different company? If yes, logic. If no, data.
The payoff of the split is not only security. A skill that never sees a hard-coded entity name is a skill you can run on every entity. The moment someone writes if entity == "FR01" inside a skill, the logic has absorbed data, and it stops being reusable.
What goes in the logic repo
finance-logic/
README.md what this repo is, who approves changes
FINANCE.md conventions: currency, units, sign, fiscal year, glossary
skills/
month-end-close/ one folder per skill: instructions, examples, tests
vendor-mapping/
variance-commentary/
checks/ reconciliation and tie-out rules, as plain text or code
prompts/ reviewed prompts the team reuses
CHANGELOG.md one line per merged change, in finance language
Two files deserve a word.
FINANCE.md is the file an agent reads at the start of every session: currency and units, sign convention, fiscal year, what "revenue" means here, how the P&L is structured. Without it, each skill restates the conventions, and they drift apart. FINANCE.md is an open spec for that file; you can also write your own, what matters is that there is exactly one. More on the idea in The FINANCE.md Standard.
CHANGELOG.md is for the controller, not the developer. "Accrual skill now excludes intercompany invoices (approved by M.L., 14/10)" is a line an auditor can read. A commit hash is not.
What goes in the data repo
finance-data/
entities/
fr01/ mappings, settings, vendor rules for this entity
uk01/
runs/ outputs of each close, dated
exports/ reports sent to the board or the sponsor
Never put credentials in either repo: API keys and ledger tokens go in a secret manager or the agent's own configuration, not in a file someone can commit. A .gitignore that refuses .xlsx, .csv and .env files in the logic repo, plus a check on every pull request, turns the rule into a control (both are in the template below).
Step 3: The Review Loop
Every change follows the same path:
- Open a branch for the change.
- Make it (often with Claude Code or another agent doing the writing).
- Run it on last month's data, which you already know the answer to.
- Open a pull request: what changed, why, and the before/after on last month.
- A reviewer approves, or asks for changes.
- Merge, and add the line to the changelog.
Step 3 is the one finance teams skip and the one that matters most. A skill is tested when it reproduces a close you already signed. "It ran without an error" is not a test.
A good pull request description for a finance change has four lines:
- What: the skill or check that changed.
- Why: the problem it fixes, in business terms.
- Proof: the figure it produced on last month, against the figure you signed.
- Risk: which entity or which report it touches.
The paid-plan detail
Here is the part most setup guides leave out. "Nothing goes live without review" only holds if GitHub enforces it, through branch rules and required reviewers. On GitHub Free, those rules apply to public repositories only. Your finance repos are private, so on Free anyone with write access can still merge without approval: the review becomes a convention, not a control.
Enforced review on private repos is a GitHub Team feature, listed at $4 per user per month for the first 12 months on github.com/pricing (checked 12 October 2026). For a finance team of six, that is a rounding error next to the cost of one bad close. If your auditor will ever ask "who approved this change to the close process?", pay for it.
Step 4: The Excel File Git Cannot Read
Sooner or later someone commits the budget workbook to the data repo. Git will happily store it, and every version after it. What git cannot do is tell you what changed.
Git compares text, line by line. A .xlsx file is a zipped bundle of XML: change one assumption and the diff says the binary file changed, full stop. The two things you most want to review in a finance change, which formula moved and which number it moved, are exactly the two things the pull request cannot show. Cell-level diff tools for Excel exist and help at the margin, but the workbook is still the wrong unit of review: a formula pasted as a value looks like a one-cell change.
So the practical rule is:
- Text goes in GitHub: skills, conventions, checks, mappings, prompts. Git was built for it.
- The model lives in a structured, text-based form with its own history and its own diff: variables, formulas and their dependencies, timelines, scenarios. Git-friendly formats exist for that (JSON definitions, plain-text accounting files, a model layer with an API).
- Excel is an export. You generate it for the board, the sponsor, the auditor. You do not review changes inside it.
This is the split Layerz is built on. A Layerz model is a structured spreadsheet: the structure (items, formulas, the links between them) is kept apart from the values, every change is recorded in the model's history, a scenario is a branch, and two versions can be diffed formula by formula. Claude edits it over MCP, so the same agent that runs the skills from your GitHub repo changes the model without retyping it. And it exports to a clean .xlsx whenever someone needs the file. The GitHub repo holds the method; the model holds the numbers and their logic.
You do not need Layerz to follow this guide. You do need an answer to the question "how do we review a change to the model?" that is better than "open both files side by side".
Step 5: Rules Worth Writing Down
Put these in the README of the logic repo, so a new hire reads them on day one.
- No company data in the logic repo. Ever.
- No credentials in any repo.
- One
FINANCE.md. Skills read it, they do not restate it. - Every change goes through a pull request, including the CFO's.
- A change is tested on a month you already closed.
- The reviewer is not the author.
- One skill, one job. A skill that "does the close" is ten skills.
- Changes to the close are frozen during the close.
- The changelog is written for an auditor.
- Models are reviewed in their own diff, not as Excel files.
Who Owns This: the CFO
It is tempting to hand GitHub to IT. Resist it. Every decision in this guide is a finance decision: who may change the close process, which entity's data a skill may read, what counts as tested, which approval an auditor will accept. IT can create the organization and connect single sign-on. The structure, the rules and the review belong to the person who signs the numbers. That is also why the role of finance engineer now appears in finance teams rather than in IT.
Where to Start This Week
- Day 1: create the organization and the two repos. Move the convention file and the three skills people use most into
finance-logic. - Day 2: write the README with the ten rules and the reviewer for each area.
- Day 3: take one skill through the full loop: branch, change, test on last month, pull request, review, merge.
- Day 4: decide on GitHub Team if the repos are private and the review must be enforced.
- Day 5: decide where the model lives, and how a change to it is reviewed.
You do not have to start from an empty repo. Everything in this guide is packaged in finance-team-template, a free GitHub template (MIT): the folder structure, a FINANCE.md to fill, two example skills (month-end close, variance commentary), the tie-out checks, the pull request template, CODEOWNERS, the ten rules, and a GitHub Action that blocks spreadsheets, data exports and secrets from the logic repo. Click "Use this template" and name the copy finance-logic. For the models themselves, finance-models publishes forkable three-statement models (LBO, valuation, project finance, SaaS).
FAQ
Do finance people need to learn git commands? No. GitHub Desktop or the web interface covers branch, commit and pull request. In practice, Claude Code or another agent writes most changes and opens the pull request; the human reviews and approves.
Is a private GitHub repo safe for financial data? Keep company data in a separate repo with narrow access, keep credentials out of every repo, and check your contracts and your auditor's expectations before storing client or employee data there. The logic repo should hold nothing you would mind a contractor reading.
Can we just use SharePoint version history? It records versions of a file. It does not give you a review before the change goes live, and it cannot show what changed inside a workbook either.
What about Excel files we must keep? Store the exports in the data repo, dated, as a record of what was sent. Review changes in the model, not in the exported file.
The Takeaway
A finance team that builds with AI is now a small software team, whether it likes it or not. GitHub gives it history, review and separation for the price of an afternoon and a few dollars per seat. Put the logic in one repo and the data in another, enforce the review on private repos, and keep the model in a form whose changes you can actually read. Excel stays where it belongs: at the end, as the file you send.