Reading the repo
Opening the box…
Reading the repo
Opening the box…
How to install on macOS
Apply design thinking to build and ship your software securely and at scale with GitHub
Saved setup from 8 h ago
Will it work on macOS?
Also: In the browser ↗
The maintainers included tools/bootstrap. Open it to see how it's meant to be run: tools/bootstrap on GitHub.
Also: tools/setup
CONTRIBUTING.mdWelcome! 👋😄 We're excited to collaborate with you on the GitHub Well-Architected Framework. Please review these contribution guidelines before getting started. Contributions of all types are welcome!
By following these guidelines, you demonstrate respect for the time of the maintainers and community members managing this project. In return, they'll reciprocate that respect when addressing your contributions.
We want to make contributing as easy and transparent as possible, whether you're:
Thank you for contributing! We look forward to working with you. ❤️
Table of Contents
Here's how your contribution flows through from idea to publication:
flowchart LR
A[Step 1<br />Create GitHub Issue] --> B[Step 2<br />Fork & Author]
B --> C[Step 3<br />Build & Test]
C --> D[Step 4<br />Raise Pull Request]
D --> E[Step 5<br />Automated QA]
E --> F[Step 6<br />Community Review]
F --> H[[Step 7<br />GitHub Review]]
H --> I[Step 8<br />Publish]
style A fill:pink,color:#000
style B fill:pink,color:#000
style C fill:pink,color:#000
style D fill:pink,color:#000
style E fill:yellow,color:#000
style F fill:pink,color:#000
style H fill:silver,color:#000
style I fill:yellow,color:#000
Legend:
Start by creating an issue to propose your article idea. This helps us:
Create a content request Issue using our template, which will guide you through:
[!TIP] Browse existing Issues to see if someone else is already working on a similar topic. Collaboration is encouraged!
Once you're ready to start, fork the repository and begin authoring. We strongly recommend using GitHub Codespaces, a preconfigured IDE for the best experience.
[!IMPORTANT] Before creating a Codespace, verify your billing details. See Codespaces pricing information.
tools/setup to install dependencies and build the site)main branchThere are two options for creating a new article.
[!IMPORTANT] Hugo-based authoring workflows are deprecated in this repository. Rely on standard Markdown file creation and editing for article authoring. Hugo remains part of local preview/build behind the repository scripts.
Run:
# For recommendations:
tools/new-content recommendation {PILLAR} {ARTICLE-NAME}
# For scenarios:
tools/new-content scenario {ARTICLE-NAME}
Replace {PILLAR} and {ARTICLE-NAME} with real values.
This command copies archetypes/default.md into the correct destination.
For recommendation articles:
content/library/{PILLAR}/recommendations/{ARTICLE-NAME}.md
For scenario articles:
content/library/scenarios/{ARTICLE-NAME}.md
Add a folder (instead of one markdown file) at that location and bundle the files together. The format is:
content/library/{PILLAR}/recommendations/{ARTICLE-NAME}/index.md
content/library/{PILLAR}/recommendations/{ARTICLE-NAME}/page1.md
content/library/{PILLAR}/recommendations/{ARTICLE-NAME}/assets/image1.png
content/library/{PILLAR}/recommendations/{ARTICLE-NAME}/assets/image2.png
[!WARNING] Do not use
hugo new contentfor new article creation in this repository.
*)Articles must include the required frontmatter fields described in docs/contributing-learn.md. This is critical for the content to be processed and published correctly.
Before submitting your pull request, test your article in the IDE to ensure everything looks correct.
Run predefined tools in your Codespace terminal. To test,
tools/test
To lint markdown and YAML files,
tools/lint
In your Codespace terminal, run:
tools/server
The Codespace will automatically forward the port and display the URL where you can view the site. If you can't find it:

The server watches for changes and automatically reloads as you edit files.
tools/test[!TIP] Commit your changes frequently as you work. This helps you track progress and makes it easier to recover if something goes wrong.
Once you're satisfied with your article, it's time to initiate review.
[!TIP] Give your PR a descriptive title that summarizes your contribution, such as "Add productivity article on GitHub Actions caching strategies"
Once you submit your PR, automated checks will run:
You'll see the status of these checks in your PR. If any fail, review the logs and make necessary corrections.
Your PR will be reviewed by maintainers and community members. This collaborative process helps ensure quality and alignment with the framework.
What to expect:
How to respond:
[!TIP] Reviewers are here to help make your contribution the best it can be. Don't hesitate to ask for clarification or discuss alternative approaches!
Once your PR is approved by the community, GitHub maintainers will perform a final review:
You'll be notified when maintainers begin their review and if any final adjustments are needed.
[!NOTE] This is the final checkpoint before your contribution goes live!
Once approved, your article automatically publishes to GitHub Learn.
What happens:
There are several primary types of contributions to this project:
Contributions typically involve authoring content articles under the /content/ folder. To start writing, we recommend reviewing these essential framework resources:
Inspiration for Content Library articles comes from Azure Architecture Center. See the following example articles for your inspiration: 💡
Contributing code changes to the website includes bug fixes, feature enhancements, and other code-related contributions.
When contributing code, please follow these guidelines:
Other guidance for general housekeeping, like updating our README or related docs.
When proposing housekeeping updates, please keep the following in mind:
To maintain quality and consistency across the framework, we ask that all contributors:
Your article should align with the GitHub Well-Architected Framework's five pillars:
See Framework Overview for details on each pillar.
-) for unordered lists, not asteriskshttps://docs.github.com/enterprise-cloud@latest (unless the guidance is specific to GitHub Enterprise Server)archetypes/default.md):
{{% seeking-further-assistance-details %}}{{% related-links-github-docs %}}Use Hextra callouts to highlight important information:
{{< callout type="info" >}}
This is an informational note.
{{< /callout >}}
Use type for standard callouts (info, warning, error). For custom callouts, use emoji.
[!IMPORTANT] Remember: GitHub Docs is the primary source of truth. Our framework supplements documentation with design thinking and decision-making guidance.
Here are the checklists for code reviewers.
For Content Library submission:
For website code changes:
For documentation updates:
By participating, you are expected to follow the GitHub Community Code of Conduct.
By contributing, you agree that your contributions will be licensed under the MIT License.
Then run bash setup.sh. It stops at the first error and is safe to run again. Servers and tests aren't started; it lists them at the end. Read it first.
Needs Git: xcode-select --install
git clone https://github.com/github/github-well-architected.git cd github-well-architected
Node.js 24
# needs nvm: brew install nvm (or https://github.com/nvm-sh/nvm) nvm install 24
npm ci
npm run dev
Get started contributing to the GitHub Well-Architected Framework in three steps:
Choose a pillar: productivity, collaboration, application-security, governance, or architecture
hugo new content library/{PILLAR}/recommendations/{ARTICLE-NAME}.md
tools/server
Open the site when prompted in Codespaces.
No reports for macOS yet.
GitManual AI Agent reads the 8 key files and writes a step-by-step guide for macOS. Once written, it's saved for everyone.