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.

#2

This might be something to bring up using the GitHub feedback form: Share feedback - GitHub Support

However, I’d worry about people missing typos and being confused why their workflows don’t work as expected if arbitrary keys were accepted. :sweat_smile:

Join us in a 10-day Community clean-up
#3

Thanks @airtower-luna, I sent in a request. :slight_smile:

I amended my initial request to only allow for the special __doc__, __heredoc__, or doc special key.

For reference this is what I sent:

Originally I posted a request to allow github action YAML files to include unused keys.

The reasoning is that I like to include a key __doc__ where I write some longer-form heredoc style documentation. Having to prefix every line with a # is a pain (especially if there is code in there meant to be copy / pasted into a terminal), so I like to abuse yaml syntax somewhat and assign the __doc__ key to a multi-line string, where I write my documentation.

I originally posted more details about this here:

Allow unused keys in workflow yaml files

However, airtower-luna responded that they would worry about people making typos in the real keys, so I’d like to amend the original request to only allow a very specific extra key designed to be used for heredoc-style documentation. I would recommend calling this key: __doc__ or __heredoc__, borrowing from Python’s special dunder attributes. However I can also see that maybe Python duner attributes might be understandable (although I couldn’t imagine why!), so maybe just allow the special key doc to be specified in the YAML file?

It is already valid yaml syntax, all that needs to happen is for github actions to not error when it sees it, and subsequently ignore it.