gitops-argparser

README

gitops-argparser

This project provides a simple utility that can be used in gitops driven CI/CD processes which support setting variables via echoing and/or writing specific syntaxes to STDOUT. The utility was created to support the idea of defining and enforcing custom CI/CD arguments that developers can decorate within git commit messages which would then be used to alter default CI/CD behavior.

gitops-argparser permits you to define your available arguments, expected types, default values etc in a YAML file, and then be invoked with any set of those arguments, and it will emit custom output using a golang template with Sprig functions support.

Azure DevOps example

Azure DevOps pipelines supports Logging Commands which detect various commands in STDOUT and then take further action based on those commands in a pipeline; one of which is ##vso[task.setvariable variable=varname]varvalue

Lets define our supported commit message arguments

Create a file called config.yaml, the location of this file defaults to the local dir but can be overriden with the ENV var: COMMIT_MSG_ARGPARSER_CONFIG_FILE

arguments:
  - long: arg1
    dataType: string
    help: This is argument number one
    defaultValue: arg1default
  - long: arg2
    dataType: string
    help: This is argument number two
    defaultValue: "hi"
  - long: arg3
    dataType: int
    help: This is argument number three
    defaultValue: 2
  - long: arg4
    dataType: bool
    help: This is argument number four
    defaultValue: true

Lets define how we will handle the args in a template

Create a file called output.tmpl. This is a golang text/template with Sprig functions support. The location of this file defaults to the local dir but can be overriden with the ENV var: COMMIT_MSG_ARGPARSER_OUTPUT_TMPL_FILE

{{ range $arg := .Arguments }}
##vso[task.setvariable variable={{$arg.Name}}]{{$arg.Value}}
{{ end }}

Lets run it manually to simulate a commit message being processed

> ./gitops-argparser some raw commit message value -arg1 arg1value -arg2 arg2val -arg3 9999 -arg4=true

{"level":"debug","msg":"loadArgumentsConf(): reading argparser arguments conf from: config.yaml","time":"2019-11-12T13:59:09-05:00"}
{"level":"debug","msg":"loadOutputTemplateFile(): reading argparser output template from: output.tmpl","time":"2019-11-12T13:59:09-05:00"}

##vso[task.setvariable variable=arg1]arg1value

##vso[task.setvariable variable=arg2]arg2val

##vso[task.setvariable variable=arg3]9999

##vso[task.setvariable variable=arg4]true

We can see it validates the arguments and converts them to Azure log commands which will set variables in a pipeline.

If you call it with nothing you get the defaults:

> ./gitops-argparser 

{"level":"debug","msg":"loadArgumentsConf(): reading argparser arguments conf from: config.yaml","time":"2019-11-12T13:59:20-05:00"}
{"level":"debug","msg":"loadOutputTemplateFile(): reading argparser output template from: output.tmpl","time":"2019-11-12T13:59:20-05:00"}

##vso[task.setvariable variable=arg1]arg1default

##vso[task.setvariable variable=arg2]hi

##vso[task.setvariable variable=arg3]2

##vso[task.setvariable variable=arg4]true

Hook it up in an Azure pipeline task

Process a normal a commit message:

...

- task: Bash@3
    displayName: Parse commit message args
    targetType: 'Inline'
    script: ./gitops-argparser $(Build.SourceVersionMessage)

- task: Bash@3
    displayName: Print pipeline vars from commit message args
    targetType: 'Inline'
    script: | 
        echo $(arg1)
        echo $(arg2)
        echo $(arg3)
        echo $(arg4)

Process an annotated tag message:

...

- task: Bash@3
    displayName: Parse commit message args
    targetType: 'Inline'
    script: |
      export GIT_TAG_MSG=`git tag -l --format='%(contents:lines=1)' $(Build.SourceBranchName)`
      echo "GIT_TAG_MSG=$GIT_TAG_MSG"
      ./gitops-argparser $GIT_TAG_MSG

- task: Bash@3
    displayName: Print pipeline vars from commit message args
    targetType: 'Inline'
    script: | 
        echo $(arg1)
        echo $(arg2)
        echo $(arg3)
        echo $(arg4)

Important behavior notes

Parsing starts at the first token after the command that begins with a dash/hypen - character

# OK: gets all args
./gitops-argparser whatever text -arg1 x -arg2 y

# OK: gets all args
./gitops-argparser whatever text -arg1 x -arg2 y some trailing text

# NOT OK: stops parsing on first NON argument (only captures -arg1)
./gitops-argparser whatever text -arg1 x other-non-quoted-text -arg2 y some trailing text

Also note golangs flag documentation; in particular how bool arguments are interpreted. Its important you set them w/ -arg=[boolvalue] syntax as -arg [boolvalue] does not work w/ them.