Skip to content

github-well-architected

CI for PR CI for GitHub Review CodeQL

GH-WAF-Banner

Welcome

This repository maintains the static site for the GitHub Well-Architected Framework and its Content Library. The site provides opinionated, community-driven guidance for adopting and deploying the GitHub platform effectively.

Quick links:

🎬 Watch the Teaser video

Quick start

Get started contributing to the GitHub Well-Architected Framework in three steps:

1. Start with GitHub Codespaces

Open in GitHub Codespaces

2. Create a new article

Choose a pillar: productivity, collaboration, application-security, governance, or architecture

hugo new content library/{PILLAR}/recommendations/{ARTICLE-NAME}.md

3. View the site

tools/server

Open the site when prompted in Codespaces.

Documentation

For public information about the framework, see the docs/README and directory:

  • Framework Overview: Mission, vision, objectives, pillars, and design principles
  • Taxonomies: Complete reference for categorizing Content Library articles

Development

We recommend using GitHub Codespaces for the seamless contribution experience. If you prefer to set up your environment locally, follow the instructions below.

Prerequisites

Before you can run this project locally, you need:

Setup

Clone this repository (if using HTTPS):

git clone https://github.com/github/github-well-architected.git

Initialize your workspace:

tools/setup

Running locally

To run the site locally, use the following command:

export SITE_URL=http://localhost:1313/
tools/server

This script starts the Hugo development server and automatically opens the site in your default browser at http://localhost:1313/.

  • The server watches for changes and reloads the site automatically.
  • If you need to specify a different port, set the PORT environment variable before running the script:
PORT=8080 tools/server
  • For troubleshooting, check the terminal output for errors or logs.

Testing

Set the site URL for tests:

export SITE_URL=http://localhost:1313/

Run all tests:

tools/test

Run only functional tests:

tools/test --functional

Run linter:

tools/lint

Review test output for errors and address any failures before submitting changes.

For more detailed development instructions, including GitHub Codespaces setup, see the Contributing Guide.

License

This project is licensed under the terms of the MIT open source license. Please refer to the LICENSE file for the full terms.

Special thanks

Thanks to these wonderful contributors, as well as authors in Issues and Discussions for their contributions to the success of the GitHub Well-Architected Framework.

Contributors