originally posted here: Allow unused keys in workflow yaml files · Issue #1034 · actions/runner · GitHub
I would like to propose that github actions either
- Allows additional non-schema keys in the top level of the workflow yaml file OR
- 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.
