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.
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
__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
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.