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

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.)