GitHub Well-Architected Framework: what you need to know and use it

Or how we can use it as a consultant to enhance productivity, security posture and adopt best practices for our clients.

Original Post en Medium : Link

On LinkedIn, I saw an interesting post from April Yoho (as always) talking about today´s subject: GiHub Well-Architected Framework.

When reading this website, very quickly I told to myself: Wow! This looks great! The name looks very similar to Azure Well Architected Framework and it seems we can use it in the same way!

So, this is a post about what you must know around this new framework.

The great power of the five pillars and the associated documentation

What is it about in a few words

In a nutshell, this is a framework containing all the best practices, checklist recommandations, explanations of anti-pattern for everybody that works with GitHub or DevOps practices. Those written documentation can be used for setting up an initial assessment, or to put the right practices right from the start when an organization decides to migrate to GitHub.

This post is not about explaining in detail every detail of that document, but I want to highlight why it is important, how to use it and give some ideas to any stakeholder involved in this kind of project.

We are talking about a framework and just like Scrum (which is NOT a methodology, please don’t do the mistake and see the official definition), the GitHub Well-Architected framework gives you an approach, a culture and a mindset that you can adapt regarding your needs. Keep in mind that this is an ongoing document : so the releases notes will reflect every changes bring by the platform (regarding IA for instance).

Moreover, this document is not only technical, but also a practical one explaining the culture, good practices to implement and several checklists. I do not recommend implementing every single recommandations, but it gives you the ideas, shows you new targets that you can implement in the long term or it can be a good way to lock back and ask yourself: did we choose the good way?

The four pillars tackled by this framework

This is a quick explanation of the five main pillars that are addressed by the framework (just like Azure has its own five pillars: Reliability, Security, Cost optimization, operational excellence, performance efficiency).

So, the five pillars are:

1 Productivity

It’s all about how to speed the software releases with automation, CI/CD pipelines and therefore, improve the Time-to-Market for the business/clients.

2 Collaboration

It’s about the DevOps tools & culture that every team member must adhere to have an efficient system, robust team, string culture and bring innovation. This pillar talks about pull request, code reviews, project board and other collaborative features provided out of the box in GitHub.

3 Application Security

It’s about securing our data or sensitive information but only: this part talk about compliancy, proactivity, security threats, and ensure that risk management is present on every layer of the development lifecycle. Features like Dependabot, security advisories and code scanning are present here.

4 Governance

It’s about how the organization meets and complies with its own policies (permissions, access control, audit logs). Normally it already comes from the cloud or IT governance and it´s not a new topic.

5 Architecture

It’s a technical pilar about design and how to structure your GitHub development for addressing scalability, reliability and efficiency.

The five pillars of the GitHub Well-Architected Framework

How is this framework structured?

This schema shows you how this document is design in a comprehensive way: you can see the five pillars containing links to the GitHub documentation, a dedicated checklist that you can already use, some scenario’s samples and a dedicated design principles for each of those topics.

Indeed, each pillar has its own Design Principles that bring more details depending on the level of maturity: “Start”, “Mature” or “Advanced”. Like this you can pick the right information depending on where you think you are on journey to the DevOps adoption.

For example, you can implement the good practices of Disaster Recovery (Architecture Design Principle) at a “Mature Level” if you already have a baseline or take a new step about “Transparency” for your team if you think that you already have “good” level.

Common areas are shared, but there are dedicated Design principles on each pillar

My recommendations about this framework

For DevOps consultants or expert that need to perform an assessment

If you are asked to conduct an assessment about DevOps practices, see what is well done, identify areas of improvements or point out the things that are missing or not going well: use this framework as a good blueprint for communicating and present the results. This is an official documentation provided by GitHub and the community, so we can be quite confident. By the way I already use the Azure WAF so here, the philosophy is the same.

The Checklists provided are a great tool to conduct interviews, ensure that every topic was covered, and you didn’t miss anything. You can easily put them on an Excel file and create a Pivot Table measuring where you are and compare the advancements on a timeline basis. Remember that a great goal must be S.M.A.R.T, so Measurable.

For DevOps leaders that want to improve their organisation, release software with higher quality, reduce risks.

Nobody can know everything about a topic such dense as DevOps: it’s a mix of deep technical expertise, good practices, experience, and company culture. Everything is changing so fast; therefore this kind of approach and checklists help people to stay on the edge of good practices and gives you a vision and goals ro reach. Those targets must be shared between every stakeholder involved in the process, from the top (a sponsor like a director for instance), to the dev team member or the network/security/business infrastructure teams.

My recommendation is not aiming to aim an “Advanced” level of each of the Design principles, but instead adapt them depending on your needs, the budget that you have, the opportunities that you can take and the current skills of the people.

Another part is the “Anti Pattern” part : please take a look and you might be surprised. For example, GitHub does not recommend to have several organizations unnecessary because of the complexity and the overhead permissions. I already see many organisations because we have the illusion that it will bring more security boundaries but in fact, it’s a mess and brings confusion when it comes to governance and implementing CICD pipelines.

In a conclusion

I hope to see the next versions of this framework, new tools that might be released (like an Excel file for the Azure review checklist) and the feedback of the community!

Many thanks for having read that article, hope it helps and do not hesitate to leave a comment!