Checkl

The problem

The problem you have some procedures, non automated or partially automated that needs to re run on multiple environments by different people.

The content of the procedure :

• in markdown quiet easy to write with some "code blocks"
• to reduce errors it's great if the content is "personnalised/instantiated" with some pre filled commands or urls
• based on some values show hide some sections of the markdown (if source version is greater than x.y.z, current hosting is on heroku/aws/vps, current dns provider is gandi/ovh/aws/...)
• embed some infrastructure diagram or flow chart via mermaid or plantum like here

The solution

Ok stop the blabla show me one

• the initial procedure is written as a gist (public or secret) or as markdown in a repo, now let's say it's an upgrade procedure of server that implies some automation but also coordination of the tests

• now show me procedure

  • the "source" template is here
  • to upgrade from 2.20 to 2.37 for a given server : here it is
  • to upgrade from 2.30 to 2.37 for a given server : here it is
  • to upgrade from 2.31 to 2.37 for a given server : here it is

• other example : your monitoring check send you a link to a procedure with url, contact infos,...

How to use

Build and url, send it to your colleagues.

So you can provide the following query params

• gist with the url or id of the gist OR markdown with url to a repo (public or private repo on github)
• params.PARAM_NAME with value to substitute in the markdown : {{PARAM_NAME}}
• the markdown can contains some sort of logic like below

{{#if (or 
        (eq section1 "foo")
        (ne section2 "bar"))}}
my markdown content
{{/if}}


{{#if (gte "2.28" startVersion)}}
# from 2.28 to 2.29

... other content

{{/if}}

• embed some mermaid or PlantUML diagrams as code block

```mermaid
graph LR
    A[Square Rect] -- Link text --> B((Circle))
    A --> C(Round Rect)
    B --> D{Rhombus}
    C --> D
```

More

Roadmap

• Table of content and navigation
• add params in url for markdown in repository (only available for gist)
• add support for private repo ( let's hope I'll don't need a backend)
• add mermaid and plantuml support
• add support for live editing for mermaid/plantuml
• Make the code way much nicer (nearly in a single file)
• offer a better editor than a textarea and allow to save to github
• add some localstorage to store your latest checklist ?

Research

• Runbooks : https://twitter.com/mestachs/status/1416370635333382144?s=20
• https://about.gitlab.com/handbook/engineering/security/security-engineering-and-research/application-security/runbooks/threat-modeling.html
• https://about.gitlab.com/handbook/about/on-call/