How Checklists on GitHub and GitLab Can Help Team Collaboration – InApps Technology 2022

GitLab sponsored this post.

This article is the second of a three-part series. Part 1 justifies that human-performed checklists are essentially source code, and according to GitOps principles, belong in git just like any other code required for successfully managing a software stack. Part 3 covers the why and how of using rich desktop editing tools for checklist creation and completion.

Checklist Awareness and Skepticism

There are always those who feel checklists are an unnecessary waste of time because they think they can always remember the basics of the steps involved to complete a task. Many are also not aware of the huge, cross-discipline benefits that can come from their use. If you have not studied checklists in their own right, you may think they are only for exceedingly complex scenarios that simple ones do not benefit. If anyone you know feels this way, I would encourage them to read Atul Gawande’s “The Checklist Manifesto.” The key takeaways include:

• The checklists in question are for highly routinized procedures that everyone should implicitly know and execute automatically.
• The frequency of measured mistake avoidance by using checklists for these standardized procedures is very significant.
• The very professionals who are considered the sharpest in the room (lead surgeons, airplane pilot captains, etc.) were not immune to needing checklists as many had assumed they might be.
•  Most complex activities are tackled by a team — many breakdowns in proper outcomes come from assumptions about what others have done or who has the right to point out problems during a procedure. Checklists resolve this because they ensure communication and give anyone the right to point out missed items.

The “Checklist Manifesto” demonstrates that checklists don’t just prevent faults due to known issues — they also shift the human relational and communication dynamics of the team so that the can consistently produce better outcomes. So, if anyone ever tells you they don’t need a checklist because what they are doing “ain’t brain surgery,” you can let them know real brain surgeons actually use checklists for the easy stuff that also has life-threatening consequences if mistakes are made.

Full Checklist Lifecycle

There is not a standard set of terminology for the checklist lifecycle, so we’ll apply a little of our own and tack it toward DevOps checklists with the terms “Template Checklist” and “Tracking Checklist.” As you’ll see, the important differences between these checklist types has implications for what tooling is used to create and update template checklists versus tooling for processing tracking checklists.

What we will call a “Template Checklist” is where we express the following:

• What needs to be done.
• Required order of step completion and/or parallel step execution allowances.
• How to complete procedures (or pointers to procedures if too long to be contained inline).
• Why a specific approach or order is important (to facilitate procedure adjustments if problems with the standard procedure are experienced).
• Fill-in fields that may need to be tailored before the checklist starts or field engineering tracking checklist completion.
• Optional and context-specific procedure blocks that may only need to be done in certain cases or done differently depending on something like the target environment.

What we will call a “Tracking Checklist” is used to perform the checklist without losing your place.  It is where we track:

• The current real-time completion status of checklist items as the checklist is being processed.
• Who completed the checklist.
• When they completed it.
• What target they completed the checklist against (if there are multiple possibilities).
• Recording of variances compared to expected outputs or results.
• Whether variances were experienced that imply or directly indicate a template checklist update should be considered.

Template Checklists frequently need preparatory customization to be used as a Tracking Checklist. For example, the same template might be used to push changes to one of five environments because the process is identical except for a few bits of variable data, such as where the environment is located and the configuration details of that environment. These may be as simple as completing a table of details at the top, or may require more elaborate edits throughout. The preparation stage can also be important to the approval process — anyone whose pre-approval is required will want to see the specific details in a Prepared Tracking Checklist before giving the okay. Finally, Completed Tracking Checklists are an official record of the change event and generally need to be retained for audits and process-improvement studies.

The entire checklist lifecycle allows for continuous collaborative feedback against the Template Checklist. The value of a checklist is greatly enhanced as it aggregates more and more knowledge of what to do under various circumstances. If exception processes or infrequently executed sections get large, it may be necessary to break them out into their own sub-checklist template that it only invoked when needed.

Plain Markdown

If you are doing documentation of any type that is destined for Git, Markdown is, of course, the format of choice. The solution presented here focuses on flavorless, standard Markdown so as to be the most applicable to the most rendering environments as possible. The one small departure is the use of the SPAN or MARK html tag to add a color background to stamps when the rendering engine supports CSS. However, not only is this simply ignored in environments that don’t render CSS, the markings that use it also have standard markdown formatting to make them stand out sufficiently.

Tracking Checklist Tools and Storage

In Part 1 of this series, the concept of a “Master” checklist was discussed in passing. Due to the features of GitLab and GitHub, you may elect to treat storage of Template Checklists differently from Tracking Checklists.

Checklist Interactivity on GitLab and GitHub

The two major source-control systems support checkbox interactivity in specific item types of the system. These item types consist of Issues, Comments and Pull/Merge requests.  Interactivity means you can directly click to check and uncheck checkboxes without having to first put the item in full “edit” mode. This makes checklist execution via the web site seem much more natural.

Since code should only be changed by a code review process, neither GitLab nor GitHub support checkbox interactivity in source code files.

This interactivity has a positive implication for real-time collaboration on checklist execution in that status updates to the checklist are realtime and do not require a commit-push cycle to update status. There is also no risk of merge conflicts if multiple individuals are updating the same checklist. Issues also have the advantage of tracking overall work visibility and completion and are regularly used for auditing completed work.

The interactivity allows non-coders to be a part of collaborative completion of checklists formatted in “markdown” — which is a standard markup language. This means they do not have to replicate repositories, configure editors, learn markdown syntax, learn how to commit and push code, etc.  Even with the available online editors, users have to learn markdown and have to close out individual checkbox edits quickly if more than one user is processing or viewing a checklist at once.

When it comes to auditability of checkboxes in Issues, GitLab has a distinguishing feature in that it adds a comment to the issue discussion log that tracks what actions are taken on checkboxes (check or uncheck), who took the action and at what time the action occurred. This can be a massive help for general auditability. If checkboxes are carefully checked exactly when actions or wait states are completed, it can also help provide metrics for how long specific parts of the process take. Elapsed time information can help when attempting to optimize slow automation processes and/or slow human-performed steps. It is a further help on checklists that are executed by more than one person at a time as you can know who completed which steps.

Template Checklist Tools and Storage

Since changes to template checklists should most likely be reviewed by more than the individual making the changes, they should be stored directly in git so that changes can be subject to collaboration and review requirements the same way machine code is managed.

How you intend to keep completed checklist records may affect where you store the masters. If completed checklists are considered permanent records by remaining in completed issues and pull/merge requests, you should keep in mind they are not part of the git records of the project and won’t transfer if you move the git file system. If “historic records” are part of your GitOps discipline, then you may want at least a copy of the completed checklists in a source code folder. However, if the working checklists are stored in Git, they are not interactive on the Web, which makes them less functional — especially for real-time collaboration.

Here are some storage options to consider for completed tracking checklists (template checklists will always be somewhere in source):

1. Only in source code.
2. Only in completed Issues and pull/merge requests.
3. Both as an Issue or pull/merge request with a copy into git for record-keeping sake.

The third option of storing the checklist in both places allows easy discoverability and real-time collaboration on execution. It also allows you to be selective about which checklists become a permanent record — perhaps only “Promote to Production Checklist” needs to be kept rather than all the pre-prod environment checklists as well?

Template Storage in Github and Gitlab

The reason that completed checklist storage matters when considering storage of template checklists is that both GitLab and Github support placing markdown files in special locations in the git file system that make them into templates. This allows them to both be under collaborative source control, but also function as easy to discover templates for Issues and pull/merge requests in the web UI of each system. These are also the same subsystems that support interactive checklist usage. So you can imagine having template checklist templates like “Release Preparation Checklist”, “Promote to Staging Checklist” that are easily selectable when creating Issues or pull/merge requests and that require collaborative review in order to update.

Here are the special subfolder locations that enable markdown documents to be template — although some alternate locations are also possible. These specific locations in each product allow for multiple templates for each supported type and are also hidden when making local repository clones.

GitLab:

• .gitlab/issue_templates/
• .gitlab/merge_request_templates/

Github:

• .github/ISSUE_TEMPLATE/
• .github/PULL_REQUEST_TEMPLATE/

Pull/Merge Requests for Preparing Checklists

While GitLab and GitHub support checklist processing in both issues and pull/merge requests, both systems only support approvals on merger/pull requests. You may want to consider the merging of something benign, such as a token text file update, as a method of providing approvals for the checklist preparation. The resulting prepared checklist could then be inserted into an issue or a real merge request.

Pull/Merge Requests Approvals for Official Gating of Checklist Completion

GitHub and GitLab both support the concept of creating approval workflows for pull/merge requests, which enable checklist completion to be a much stronger control when the pull/merge request consists of a checklist that must be completed. Due to its embrace of GitOps, GitLab is notably more feature-rich in this area. Since GitLab also manages environment deployments, merge requests play a key role, not only in code review and signoff but also in deployment review and signoff. Multiple merge approval rules, electronic signatures, builds for merge commits and over ten other controls are available in various editions of GitLab.

GitHub Nuances

GitHub templates must have YAML front matter added to the beginning of the document in order to appear as a selectable template when creating issues. The following repositories contain examples of merge requests and issue templates in the above locations as well as in-progress checklists as an issue and merge request.

GitHub currently does not have a selector for multiple pull request templates, you must use http query parameters to select one even in the GUI.

GitLab only requires that the files be placed in the appropriate folder and then they will be available in the template selector in the web UI. This also means the user only has the title by which to initially judge the suitability of a template — file naming that clearly expresses and distinguishes the purpose of each template is necessary.

Creating Placeholder Tokens for Information Insertion

A great way to indicate the need to insert specific data in a checklist is to use a code fence with  a unique, standardized token like this: _REPLACE_WITH_ (some text) This gives multiple advantages over your own custom solution to indicating where to record result information:

• Code fences are already supported with unique highlighting (usually inverse) in most markdown editors and rendering engines.
• They can be placed within the context of almost any other markdown (tables, bullets, blockquotes, etc).
• The use of a replacement token can be directly used by humans or an editor’s search and replace functionality or used by automation (like CopyQ).
• The replacement token method can be used for rapid checklist preparation of information that repeats throughout the checklist, such as searching and replacing all occurrences of ‘_REPLACE_WITH_ X.Y’ to the actual changeset version number in one or more checklists in one operation.
• In addition to checklist preparation, the replacement token method works equally well for values that will be completed during execution of the checklist, such as _REPLACE_WITH_ screenshot-of-messages-log.

Sample Repositories

These sample repositories include templates as well as in-progress issues and merge requests containing partially complete checklists to help you see how issue and pull/merge request templates work and how interactive checkboxes work:

https://gitlab.com/darwinjs-ideas/GitOpsforHumanProcessedChecklists

https://github.com/darwinjs/GitOpsforHumanProcessedChecklists

Sometimes You Need Even More

This article and the sample repositories give a fairly comprehensive view of what is possible with the templates and interactive checklist support built into the most common git collaboration systems. Our final article in this series will look at multiplatform desktop utilities for a much richer markdown editing experience and the ability to insert standardized markdown formatted snippets during Template Checklist creation or Tracking Checklist completion.

For more case study discussions on infrastructure best practices, attend GitLab Commit San Francisco Jan. 14. GitLab’s user event will showcase the power of DevOps in action through strategy and technology discussions, lessons learned, behind-the-scenes looks at the development lifecycle, and more.

Feature image via Pixabay.