Click here to Skip to main content
15,861,125 members
Articles / DevOps
Technical Blog

Storing DevOps Documentation in Git and Managing CAB Approvals with Pull Requests

Rate me:
Please Sign up or sign in to vote.
3.00/5 (1 vote)
24 Nov 2020CPOL2 min read 3.8K  
How to store Devops documentation in GIT and manage CAD approvals with pull requests
In this article, I will show you how to use Azure DevOps to manage work items. First, we will look at the problems that we need to address. Then, we will look at the solution and the new document creation process. We will also see a diagram and the results.

Often in a large enterprises, you will need to submit changes to a CAB (Change Advisory Board) before getting approval to make any changes to your infrastructure. But managing versions of your diagrams and documents / infrastructure code / what has actually been deployed can be difficult..

Documentation is often stored in a separate document store (like Sharepoint).

I’m using Azure DevOps to manage work items here, but you can insert your own (Jira, Github Issues).

Our Plan Today

  1. Problems to address
  2. Solution
  3. New document creation process
  4. Diagram
  5. Results

1. Problems to Address

  1. Separating documents from infrastructure code often causes documents to be out of date as they’re not always up to date in Sharepoint.
  2. Decisions of when/why changes were implemented is hard to keep track of.

2. Solution

  1. Store documents within Git (Source Control), directly with infrastructure code.
  2. Utilise Pull Requests in Azure DevOps for CAB approval of document changes (and track any changes that have been requested to the documents).

3. New Document Creation Process

  • Each application folder has a docs folder (with LLDs, HLDs, Visio diagrams, etc.)
  • An Engineer will have a Story in Azure DevOps to do the analysis and design work and create the document
  • They will create a branch to make the changes to the documents in that folder, commit the branch and submit a Pull Request when they are complete.
  • When a Pull Request is requested to master, a release pipeline copies the docs folder to the folder in Sharepoint.
  • The PR is assigned to a CAB member for CAB.
  • They then take this to CAB, and can view the documents in Sharepoint or in the repository.
  • If approved, this is merged into master, and the new story can be created for the next sprint to do the implementation.
  • If denied, the CAB can create bugs against the Pull Request in Azure DevOps, those can be assigned to the engineer who can make the changes and the docs folder will be copied again to the Sharepoint folder.

4. Diagram

@startuml

partition Engineer { "Engineer makes changes to documents" –> "Engineer commits 
                      changes to branch" }

partition "CI Server" { "Engineer commits changes to branch" –> "Documents automatically 
                         copied to SharePoint folder" }

(*) –> "Change Request"

partition Engineer { "Change Request" –> "Engineer creates HLD document" –> "New branch 
                      created in Git called feature/<story_id>" --> "Documents saved 
                      into Git (directly with infrastructure code)" --> "Engineer Submits 
                      PULL REQUEST. Assigning CAB member for CAB approval" --> "Documents 
                      automatically copied to SharePoint folder" }

partition "CAB Approval" #CCCCEE { "Documents automatically copied to 
           SharePoint folder" -right-> "CAB Meeting to review documents and 
           decide if to approve or deny" }

partition "CAB Approval" #CCCCEE { "CAB Meeting to review documents and 
           decide if to approve or deny" –> "Pull Request Approved?" -left-> if "" 
           then -down->[Approved] "Documents merged into master branch in Git" 
           else -up-> [Changes required] "Bugs created in the PR for changes needed" 
           -up-> "Engineer makes changes to documents" else -right-> 
           [Denied] "Pull Request Denied. Work not going ahead, 
           documents removed from Sharepoint?" endif

} @enduml

5. Effects

  • Versioned documents and code are stored together at the same time.
  • Any time code is changed, you will see if documentation hasn’t been updated and also know what actually changed.
  • Part of the Pull Request process for committing code, can be to ensure documentation has been updated if needed.
  • All conversations around the document changes will be visible inside the Pull Request. Comments can be seen / discussed inside the Pull Request, and bugs created and assigned for any changes needed. (This will show us approved date, and will see the who/when decisions were made to make changes.)

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


Written By
Architect
United Kingdom United Kingdom
I have been working in software development for over 16 years, during that time I have worn many hats.

I have worked as a Software Engineer, Architect, Agile Coach and Trainer. I’ve created teams, I’ve lead teams, but my main goal is to help teams build great software and enjoy the process.

I help a whole range of businesses – from startups with just an idea who want to build a team to take that idea into reality and FTSE 100 businesses who need to optimise existing teams – I train, mentor and coach them to success.

If you happen to know of anybody who could benefit from results like this, then please go to my contact page and get in touch.

Owen Davies

Comments and Discussions

 
-- There are no messages in this forum --