Contributing to Well-Architected Labs


  • Nathan Besh. Cost-Lead, Well-Architected, AWS
  • Alee Whitman, Commercial Architect (AWS OPTICS)


The Well-Architected labs are open source and we welcome feedback and contributions from the community.

Please read through this document before submitting any issues or pull requests to ensure we have all the necessary information to effectively respond to your bug report or contribution.

If there are errors or you wish to make improvements to the labs, you can perform a pull request. To create a pull request, follow the steps below.

Reporting Bugs/Feature Request

We welcome you to use the GitHub issue tracker to report bugs or suggest features.

When filing an issue, please check existing open or recently closed issues to make sure somebody else hasn’t already reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:

  • A label with the Well-Architected framework pillar (i.e. COST)
  • A reproducible test case or series of steps
  • The version of our code being used
  • Any modifications you’ve made relevant to the bug
  • Anything unusual about your environment or deployment

Contributing via Pull Requests

Process for updating any existing labs or creating a new lab


  • You check existing open, and recently merged, pull requests to make sure someone else hasn’t addressed the problem already.
  • You open an issue to discuss any significant work or new lab ideas - we would hate for your time to be wasted.
  • GitHub account
  • Git setup locally on your PC
  • Install Hugo

Create a fork

You will create a fork to work on, make the edits and then submit it to be merged back into production. A local fork will be your local copy of the Well-Architected Labs repository.

  1. Go to the production Well-Architected Labs repository
  2. On the right side of the page, click on the Fork icon Images/fork.png
  3. Select your GitHub account to fork to Images/fork2.png
  4. You will then have a remote repository of /aws-well-architected-labs Images/directory.png This is effectively your own version of the labs, stored on GitHub

Create a local repository from the fork

You will create a local copy of the fork to work on, and make the required edits, his allows you to work locally and view the changes.

  1. Create a directory on your PC to hold the local repository
  2. Change to that directory or navigate to that directory and right click and select Git Bash Here Images/git.png
  3. Replace the repository name (username)/aws-well-architected-labs below with your repository name, and clone it: git clone
  • It will download the repository Images/git2.png
  • You now have your local copy setup & have your own GitHub repository to push to

Make changes or create new content

Note: Modify the source. Please focus on the specific change you are contributing. If you make modifications to multiple labs please submit a separate request for each lab.

Make changes on an existing lab

Click here for the steps to make changes on an existing lab

Create a new lab

Click here for the process to create a new lab

Verify your edits and/or additions

After making the changes or additions test and verify locally

  • Navigate back to the aws-well-architected-labs parent folder

  • Serve the content locally:

     hugo serve -D
  • Open a browser and navigate to http://localhost:1313/

  • Verify the change you made was correct and there were no problems introduced

Push your changes to the remote repository:

Push your changes to GitHub, so that they are stored and backed up by GitHub. Use the following commands:

    git add -A
    git commit -m "your comment here"
    git push

Images/gitcommit.png All your changes will be in the remote repository in GitHub, which can now be merged into the Well-Architected Labs repository.

Additional Validation Step for New Labs

  • New labs require an additional validation step of two peer reviews. Please have two peers review your lab step by step to confirm it is working as expected prior to submitting a pull request.

Perform a pull request

All the changes are now in your remote repository, let’s do a pull request to merge it into the public Well-Architected Labs repository:

  1. Go to the your GitHub Well-Architected Labs remote repository
    • Make sure you update with your username
  2. Click Pull Request Images/pull.png
  3. Click compare across forks
  4. Select your fork on the right side as head repository Images/pull2.png
  5. Review the changes, and click Create pull request
  6. Edit the info (this is public – be careful and add a brief description of the edit or addition)
    • Make sure to add the label of the Well-Architected Pillar (i.e. COST) Images/pull3.png
  7. Click Create pull request

GitHub provides additional document on forking a repository and creating a pull request .

Thank you for your contribution. The Well-Architected team will receive a notification of the pull request, we will review and commit the change or reach out with any questions.


Clean up your local and remote repositories, delete them if there is not additional work.

  • Go to your remote repository, modify the link:
  • Click Settings
  • Scroll down under Danger Zone and click Delete this repository
  • Confirm & click delete
  • Clean up your local repository by deleting the directory created previously

Code of Conduct

This project has adopted the Amazon Open Source Code of Conduct . For more information see the Code of Conduct FAQ or contact with any additional questions or comments.

Security issue notifications

If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page . Please do not create a public GitHub issue.


See the LICENSE file for our project’s licensing. We will ask you to confirm the licensing of your contribution.

We may ask you to sign a Contributor License Agreement (CLA) for larger changes.