Automated Checks for Architecture Center Contributions
When you open a pull request against the SAP Architecture Center repository, a set of automated checks runs automatically. These are GitHub Actions workflows that read your changes and give you fast, friendly feedback, before a human maintainer ever looks at your contribution.
What the checks do for you
Think of the checks as an automated first reviewer. They catch the small, mechanical things (a misspelled product name, a missing front matter field, a dead link) so that you can fix them in seconds and the human reviewer can focus on what really matters: the quality and clarity of your reference architecture.
A few things worth knowing up front:
- The checks are here to help, not to get in your way. Most issues they report take moments to fix, and the feedback points you straight at the file and line.
- You do not need to install anything. Everything runs in GitHub when you push. If you contribute through our no-code Quick Start editor, the same checks still run on the pull request it opens for you.
- A failing check is normal. It simply means something needs a small adjustment. Push a new commit and the checks run again automatically.
New to contributing? Start with the community introduction and the contribution process first, then come back here to understand the checks you'll see on your pull request.
Where results show up
The checks report their findings in three places, so you'll never have to go searching:
- Inline annotations on the Files changed tab: comments pinned to the exact line that needs attention (for example, the spelling and typo checks mark the offending word right where it appears).
- The Checks tab: one entry per check, each with a green tick, a red cross, or a neutral note, plus a detailed log and a per-job summary you can expand.
- One sticky pull request comment titled 🔎 Content check results: a single, continuously-updated comment that gathers the content findings grouped by check. It rebuilds itself every time a check finishes, so it always reflects your latest commit (look for the footer noting the commit it was updated for).
The sticky comment aggregates the content checks that can block a merge (internal links, external links, SEO front matter, front matter properties, reference architecture IDs, Draw.io files, orphan files), and it shows their blocking errors only. Spelling, typos, and grammar are deliberately not repeated in the comment: spelling and typos annotate inline on the Files changed tab, right next to the word in question, and grammar posts its advisory notes on the Checks tab. Non-blocking warnings, such as an SEO length just outside the recommended range, stay inline and in the job summary, not in this comment.
For a full, example-driven walkthrough of what each surface looks like and how to resolve what you find, see Errors & Warnings.
The content checks at a glance
The table below indexes every content check. "Blocking?" tells you whether a failure must be resolved before the pull request can merge. Follow the Learn more link for the detail page on each check.
| Check | What it verifies | Blocking? | Learn more |
|---|---|---|---|
| Spelling | Every word in your Markdown is spelled correctly, using cspell plus the project's custom dictionaries. | Yes | Spelling |
| Typos | Common typos and misspellings, caught by the fast typos checker. | Yes | Typos |
| Grammar | Prose style and grammar, via LanguageTool. Advisory only. | No | Grammar |
| Front Matter Properties | Changed reference architecture pages credit their author, carry a fresh date, and keep the house-style default fields. | Yes | Front Matter Properties |
| SEO Front Matter | The title and description lengths sit in the search-engine-friendly range. | Yes* | SEO Front Matter |
| Reference Architecture IDs | Each reference architecture carries a valid, unique six-character id and a matching slug. | Yes | Reference Architecture IDs |
| Internal Links | No links point to SAP-internal-only hosts that would break for public visitors. | Yes | Internal Links |
| External Links | Links pointing to the public web are reachable, checked with lychee. | Yes | External Links |
| Draw.io Files | Diagram files stay under 1 MB and embed their images (no external references). | Yes | Draw.io Files |
| Orphan Files | Images, diagrams, and other assets you add are actually referenced somewhere. | Yes* | Orphan Files |
Grammar is the only check that never blocks a merge. Treat its notes as a friendly proofreader's second opinion. A couple of checks marked Yes* can also emit non-blocking warnings alongside their blocking errors: SEO Front Matter warns when a length is merely outside the recommended range, and Orphan Files warns when an asset is referenced only outside its own reference architecture folder. See each check's page for the detail.
Custom dictionaries
Technical writing is full of words that no general dictionary knows, such as product names, acronyms, partner brands, and the names of people. So the spell checker is taught the project's vocabulary through four custom dictionaries:
sap : SAP product and solution names
industry : general technology and industry terms
partners : partner and vendor names
people : contributor and author names
If the Spelling check flags a word that is genuinely correct, the fix is usually to add it to the right dictionary rather than to change your text. The dictionaries are plain text files, one word per line, so updating them is easy.
See Custom Dictionaries for exactly which file to edit, how the four dictionaries are organised, and how to add a new term.
Operational workflows
Alongside the content checks, a second group of workflows keeps the site itself healthy: building and deploying the site, scanning for security issues, and verifying open-source license compliance. These run largely in the background and are not something you normally act on as a content contributor, but it's good to know they exist.
See Operational Workflows for a tour of what runs behind the scenes.
Which checks run on my pull request?
Most checks are path-filtered: they only run when files relevant to them change. Edit a Markdown page and you'll see the spelling, typo, link, and front matter checks; touch a .drawio diagram and the Draw.io check runs. The checks run on pull requests targeting the dev (and main) branches, so you only ever see the checks that actually apply to your change, with no distractions.
This keeps feedback focused: a small text fix won't trigger diagram validation, and a diagram-only change won't run the grammar linter. When you're ready to start resolving findings, go to Errors & Warnings for concrete examples.