ARCHITECTURE CASE STUDY · ANONYMISED

Publishing repo docs to SharePoint automatically

I built a tool that copies each repo's documentation to our department's SharePoint site. Docs are written and reviewed in the repo. When they change on the main branch, SharePoint is updated automatically.

MY ROLE
Architect and developer
SCOPE
One shared tool · one workflow file per repo
STACK
Node.js, GitHub Actions, Microsoft Graph API, Entra ID, SharePoint
STATUS
In production

The problem

Each repo keeps its documentation in a docs/ folder. The department also needed all of that documentation in one place on its SharePoint site, without keeping two copies up to date by hand.

The design

On every push to main, the tool compares the repo's docs with SharePoint and changes only what's different.

before any delete
Other repossame workflow file
Repo docsdocs/ folder · .md files
GitHub Actionruns on push to main
Doc publishercompare & sync
SharePointsame folders as the repo
Staffall docs in one place
Safety checksdelete limit · folder owner
  1. Repo docsdocs/ folder · .md files
  2. GitHub Actionruns on push to main
    • Other repos · same workflow file
  3. Doc publishercompare & sync
    • Safety checks · delete limit · folder owner
  4. SharePointsame folders as the repo
  5. Staffall docs in one place

Key decisions

  1. Compare the whole folder every run

    Each run checks every doc, not only the files in the last push. A failed run is caught up by the next one, and a second run in a row changes nothing.

  2. The repo is the source of truth

    Docs are edited in GitHub. If someone edits a doc directly in SharePoint, the next run puts the repo's version back.

  3. Safety checks before deleting

    The tool only touches .md files in its own folder. It stops if it doesn't find any docs, if one run would delete more than five files, or if the folder belongs to another repo.

  4. Secure sign-in

    GitHub signs in to Microsoft Entra with a short-lived token (OIDC) that is created for each run. Entra only trusts the main branch of each listed repo, and the app can only write to one SharePoint site.

Outcome

  • All documentation is in one place on SharePoint, with the same folder structure as the repos.
  • Docs are reviewed in pull requests like code, and SharePoint is updated automatically.
  • A new repo is added with one workflow file.

WHAT I'M LEARNING

How it could look on Azure

Next steps I'd look at with Azure, based on what I'm studying.

Current setup and the Azure service it could map to
TodayOn Azure
Run results in the GitHub Actions logFailed runs raise an Azure Monitor alert
Client secret for local test runsLocal runs use the developer's own Entra sign-in