GHA skip-checks:true recomendation and behaviour not consistent with git-commit --trailer behaviour

[dlmiles]

Code of Conduct

• [X] I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://github.com/github/docs/blob/main/content/actions/managing-workflow-runs/skipping-workflow-runs.md?plain=1#L29

This concern the use of skip-checks: true inserted into the end of a commit message to inhibit GHA workflows.

What part(s) of the article would you like to see updated?

It is not (easily) possible to insert "TWO blank lines" as the git commit command automatically reformats the message based on de-facto rules. This will remove the double blank lines and replace it with a single blank line, before adding the message to git.

Please try your own instructions to confirm this automatic reformat and please investigate to confirm no obvious git option to inhibit this behaviour exist. If there is such an option, you should document it is needed to achieve the goal of the github documentation.

Furthermore there is an option to use git commit --trailer skip-checks:true which has a default behaviour (that also does not insert TWO blank lines, before the trailer).

So the 3 actions this issue is seeking to resolve:

• GHA modified to accept a SINGLE blank line and allow multiple key=value and key:value items to be specified in the last paragraph of the git commit message. Above/below the ones GHA is looking for. The documentation indicates/implies it must be in isolation at the end, but this does not inter-operate with other mechanisms doing the same.
• The documentation to be updated to remove the TWO blank lines rule and describe it as ONE blank line.
• The documentation to provide an example command line demonstrating the --trailer feature to git-commit.

Now if GHA must really have its TWO blank lines, then maybe it could test and document how to achieve this, simple sounding action in a commit message in common environments. Lets say "Linux Command Line" and "Windows Desktop" and "MacOS Desktop".

GHA should also explain how this might interact and work with other mechanisms using trailers, as I understand it, it should be possible to tail with:

Message Summary Line

Message Details Paragraph 1

Message Details Paragraph 2

Sign-Off: My Name <[email protected]>
Another-Special-Thing: option123
key=value
skip-checks:true
My-Key=MyValue

The GHA mechanism should also work in a situation like the above. Since it follows the rules that:

• Trailing blank lines are removed, to expose the last paragraph block
• Last paragraph is parsed for Key:Value or key=value format information, with spaces allow around the '=' and ':' that are disregarded. Although maybe no space is allowed before ':' as that does not seem common usage.
• It allows other items to be both before and after the skip-checks item.
• The content is entirely in the last paragraph block of the commit log message.

Following these rules should ensure scope of interoperability with other mechanisms also working like this.

Additional information

$ git --version git version 2.39.1 $ grep PRETTY /etc/os-release PRETTY_NAME="CentOS Stream 8"

[welcome[bot]]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[cmwilson21]

@dlmiles Thanks so much for opening an issue! We appreciate all the extra context. ✨

GHA modified to accept a SINGLE blank line and allow multiple key=value and key:value items to be specified in the last paragraph of the git commit message.

For this bit in particular, the best place to leave this sort of feedback is with the product team in https://github.com/orgs/community/discussions 👍

I'll triage this for the team to take a look :eyes:

[guntrip]

Hi @dlmiles, thanks for opening this! We've chatted with our Git and Actions teams and I think we have a solution now that we can document.

It is not (easily) possible to insert "TWO blank lines" as the git commit command automatically reformats the message based on de-facto rules. This will remove the double blank lines and replace it with a single blank line, before adding the message to git.

This is true! The default --cleanup behaviour for git commit will remove consecutive newlines. We can change that behaviour with --cleanup=verbatim. For example:

git commit --cleanup=verbatim  -m "Update README


skip-checks: true"

GHA should also explain how this might interact and work with other mechanisms using trailers

You can include skip-checks: true in the trailers but it should be the last item and doesn't need extra new lines.

---

Moving forward, we can make two changes to the "Skipping workflow runs" article (source here):

• Modify "Alternatively, you can end the commit message with two empty lines followed by either" to describe these as trailers and make it clear that skip-checks should be last. Something like:

  Alternatively, you can add a skip-checks trailer to your commit message . The trailers section should be included at the end of your commit message and be proceeded by two empty lines. If you already have other trailers in your commit message, skip-checks should be last. You can use either of the following:

• Beneath the list that contains skip-checks: true and skip-checks:true, add a short sentence explaining that Git's default behaviour will remove consecutive newlines and that we'd recommend including the --cleanup=verbatim option.

You or anyone else is welcome to open a PR for this! 😸