Documentation for "macros" (?) like $default-branch and $registry-url in Actions

[nguyenalex836]

Discussed in https://github.com/github/docs/discussions/5071

^{Originally posted by steven-wolfman April 4, 2021}
I'm CS faculty brushing up on GitHub (among other things) during sabbatical. I'm presently learning the syntax for GitHub Actions workflows, which is generally well-documented. Thanks!!

However, I noticed a bit of syntax I cannot find documentation for in the Node.js starter workflow and the npm/GitHub packages starter workflow. Each of these uses what looks like bash parameter substitution syntax outside of a run command and without the {{ ... }} syntax. The former as $default-branch and the latter as $registry-url(npm).

The closest I've found to documentation of this syntax is GitHub blog post on renaming master to main (which, yay!) that refers to this as a macro.

Is this syntax or the full set of macros documented somewhere?

Thanks!

Steve

P.S. If you're curious, you can look at the notes I'm taking on GitHub Actions, among other things. The link is to the branch with these notes, not yet integrated into what I guess I can refer to as $default-branch 😁

Comments ----------------------------------------------------------------------------------------------------

lucascosti
on Apr 5, 2021
👋 steven-wolfman Thanks for the feedback! 💛

For $default-branch: that's a special placeholder for workflow templates which gets automatically replaced with a repository's default branch when a new workflow is created from the template. Docs for that are here: https://docs.github.com/en/actions/learn-github-actions/sharing-workflows-with-your-organization#creating-a-workflow-template

The official actions/starter-workflows repository contains workflow templates, but you can also create templates within a GitHub organization. If you are creating workflows from scratch (i.e. not a template), you'll need to use the actual name of the default branch for your repository.

For $registry-url: I'm not 100% sure, but I think it's a similar thing for the NPM registry your org uses.

tldr: they are placeholders that only apply to workflow templates, and are replaced with actual values when new workflows are created from the template. 🙂

2 replies
steven-wolfman
steven-wolfman
on Apr 6, 2021
Author
Ah, I see. So, none of the $... syntax except the well-document ${{ ... }} expressions should be used in a standard workflow document. That also means that the starter workflows themselves are great examples to work from expect where they use template-specific features.

Thanks!

As a recommendation for GitHub docs, I'd still say it would be great to have the template-specific $... syntax clearly documented somewhere. Separately, I wonder of best practice for starter workflows might include some kind of explicit documentation of template-specific syntax, since I imagine others will also use them as examples from which to build their own workflows.

steven-wolfman
steven-wolfman
on Apr 6, 2021
Author
Quick update: I'm working on a PR to correct some places where the docs use $default-branch where it should probably be main instead. See #5104.

I don't think I can help with documenting the template-specific syntax (since I don't know what it is or where to even find code implementing it!). I'm not quite sure how to handle the template-specific syntax in starter workflows. Maybe a comment? Although that will look strange if the template syntax IS used in instantiation (i.e., disappears). (I guess the template syntax could trigger stripping certain types of comments?? Seems.. complicated.)