Allow unused keys in workflow yaml files

Code to Cloud GitHub Actions
#1

originally posted here: Allow unused keys in workflow yaml files · Issue #1034 · actions/runner · GitHub

I would like to propose that github actions either

  1. Allows additional non-schema keys in the top level of the workflow yaml file OR
  2. Create a special key (I would suggest __doc__) in the schema that can be used for documentation.

Modivation:

When I’m writing code I like to take notes, especially if I am learning something new (like github actions). When working with other CI services I’ve followed a pattern where I make a top level key called __doc__, which I specify as a multi-line string so I can effectively write notes in my yaml file. For example:

__doc__: |
    # How to run locally
    cd $HOME/code
    git clone https://github.com/nektos/act.git $HOME/code/act
    cd $HOME/code/act
    chmod +x install.sh
    ./install.sh -b $HOME/.local/opt/act
    cd $HOME/code/line_profiler
    $HOME/.local/opt/act/act

Because __doc__ is unused by CI services, it has no effect on the code itself. This seemed to work fine when I used GitHub - nektos/act: Run your GitHub Actions locally 🚀 to run a workflow locally. But when I pushed to github it seems the schema validation is more strict. I had to comment out my __doc__.

I could use single line comments for my notes, but multi-line comments are so much easier to deal with because prefixes never need to be added or stripped.