Bonjour! I just published on article on how Kotli...

# feed

[jmfayard]

Bonjour! I just published on article on how Kotlin scripts powered by #github-actions-kotlin-dsl can rescue the world from the insane type-unsafe YAML programming 😈 that GitHub actions inflicted on us 🙂

https://dev.to/jmfayard/github-actions-a-new-hope-in-yaml-wasteland-1i9c

[Fleshgrinder]

I see a lot of these kind of posts lately, but I cannot stop to wonder why people are willing to buy into this. No matter if YAML or Kotlin Script. Having the workflows in a vendor specific manner results in a lock in, always. The only way to get out of this is by using a proper build system, e.g. Gradle. A workflow should be as simple as defining the event, and triggering Gradle: done. Maybe I'm missing something…

[jmfayard]

@Fleshgrinder to automate things fully it’s Gradle + GitHub Actions (or similar), not Gradle or GitHub Actions

Take this workflow where we want to check if newer versions are available

The task to re-generate the workflow is entirely contained in the Gradle build, and that’s what line 38-44 are doing:

running ./gradlew suggestVersions

GitHub Action gives us
1. a VM to run it (Azure, UbuntuLatest, Java 11) - but it could be multiple OS / java versions / … if for example you have a multiplatform library
2. a way to store environment variables and secrets
3. an event on when we want it to run. It could be a pull request or in this case a Crontab that runs once a week.
4. a way to create an issue like this one automatically depending on what the Gradle task found

[Fleshgrinder]

Of course it's the combo, but once the heavy lifting is done in a build tool those few lines of YAML really don't hurt. I would argue that the additional complexity of an additional library to manage hurts much more.

[Piotr Krzemiński]

Introducing extra complexity (here: the library) is a matter of trade-off - for some it may pay off and give them better developer experience in the long run, and for some it may be surplus. It's your call to choose :)

[Piotr Krzemiński]

It's like shell VS Kotlin Script: I personally use shell scripting for trivial tasks like calling one or two commands. For anything more that contains actual logic, I use Kotlin Script which gives proper type-safety and I can reuse my JVM knowledge.

[jmfayard]

@Fleshgrinder I wish it was only “those few lines of YAML”. If that was the case I would have never care about this library.

But then I invite you to try to learn and memorise GitHub’s YAML documentation. It’s huge and incredibly easy to get wrong.

The virtue of this library is that it puts all this information available in the IDE right in the context where it makes sense.

[Fleshgrinder]

No need to memoize, Ctrl + Space in IntelliJ does it for me based on the backing JSON schemas directly from GitHub. Combining that with Workflow Starters there is not often the need for anyone to actually write these YAML files. Sure, in special cases, but considering that special cases are not the norm anyone would need to make themselves familiar with whatever abstraction is in place to get where they want to get. I fail to see how additional libraries (that require additional maintenance) help here.

The examples given in your blog post quickly fall apart. The auto-completion for an action like CheckoutV3 are only available because somebody actually wrote it. But, what about all the other actions out there where nobody ever wrote a Kotlin class for? What's really needed here is IDE support to automatically fetch the action schema so that the parameters can be auto-completed properly. Same goes for the version, again something the IDE can do much more reliably for any kind of action out there.

Hence, what would be truly worthwhile would be an IDE plugin that understands GitHub actions and can provide inline help for them. Just like the JSON schema can provide it for the GitHub workflow YAML files.

[Vampire]

@Fleshgrinder read these "few lines" and you know why such a lib is necessary and awesome: https://github.com/Vampire/setup-wsl/blob/master/.github/workflows/test.yml

Pure GHA YAML dies not even support anchors so you also have to constantly repeat and change stuff in multiple places, ...

If you don't like it, don't use it. ;-)

[Fleshgrinder]

@Vampire don't. I was asking a serious question and not saying that nobody should be using it. Your example is absolutely terrible, and I would directly see many ways to make it much simpler, but would be very curious how the Kotlin DSL would help here. All it would do is encourage even more people to put their entire logic into the workflow files, instead of using maintainable and testable build tools (this includes even simple things like Bash, Make, PowerShell, …) to do the job. Also, using the most terrible workflow file that is written in a rather idiosyncratic YAML style cannot be a counter argument after I clearly stated that there are special situations that need special care. But, it just makes me wonder more how terrible this would look like with a custom Kotlin DSL versus a few scripts that output the matrix builds needed and replace all the inline code with proper scripts so that the YAML actually is reduced to only a couple (although in this special case still advanced) lines.

[Vampire]

If you really think it is terrible and see many ways to improve, you're very welcome to send a PR my way. There is imho no unnecessary logic in my workflow, but I'm always open for improvement suggestions.

[Fleshgrinder]

Well, the selling point of the Kotlin DSL for GHA workflows is that YAML is a terrible programming language, and this is very true. My point is that GHA workflows are not a programming environment in the first place, and that programming is better done in such an environment. Modern build tools provide this (e.g. Gradle), but for special cases (like yours) it can easily be built with a little bit of scripting (e.g. Bash). The workflow YAMLs should be reduced to their absolute minimum. The solution should not be to improve the GHA workflows programming environment, because it simply is none.

I can give you pointers and ideas if you want, but I do not have the time to contribute to projects where I have absolutely no stake in. Sorry.

[Vampire]

You are also welcome to share ideas of course

[Vampire]

But actually yes, it is not a programming language and also the project here is not programming. It is a DSL to conveniently write workflow files. It is extremely tedious to write even much simpler workflow files, as you always have to look up in the suboptimal GHA documentation which is doing what and what means what, even with IDE help from the JSON schema. You also always have to look at each action's documentation, and also many things are string based and then just have a special meaning in the action when it parses the arguments.

With the DSL you have amazing IDE support with type-safety, and proper online documentation for all supported actions and built-in things and so on.

Of course as it is Kotlin script, you can "abuse" it and put much logic inside it and for my workflow I probably also need it. But it is the same with all DSLs. For example Gradle build scripts should probably be very declarative and not really contain logic, but logic should be put into custom tasks and plugins. But you of course can "abuse" it and put much logic in the build script.

[Fleshgrinder]

The problem with custom actions is exactly what I brought up above as well and where the DSL is not going to help. Custom actions are exactly what plugins are in Gradle. That's where the logic should go. They then use whatever proper programming language they want. Custom actions, much like custom Gradle plugins, have a proper API definition. Now if the IDE would just fetch them it could provide the desired autocompletion and inline documentation as well as information on optional and required arguments. Obviously the type system is limited, that would be a task for GitHub to resolve.

But, again, the Kotlin DSL isn't going to helps with any of this. It provides inline docs for standard elements, exactly like the JSON schema. Given the argument that inline documentation isn't sufficient it applies to both solutions.

[Vampire]

That's not really correct if you look further. ;-)

And good luck making GitHub improve the type system, they don't even manage to provide YAML anchors although many people need them and request them. :-)

[Fleshgrinder]

We all know that GitHub isn't listening much to the community.

[jmfayard]

@Fleshgrinder interesting discussion, thanks you

The examples given in your blog post quickly fall apart. The auto-completion for an action like CheckoutV3 are only available because somebody actually wrote it. But, what about all the other actions out there where nobody ever wrote a Kotlin class for?

The thing is that pretty much everything is automated. We add the coordinates of the action in our wrapper generator and Kotlinpoet generates it all. And later GitHub Actions runs regularly to check if there are new parameters or newer versions.

So it’s pretty much what you hope for (the IDE fetching the action to see what’s available).

The difference is that instead of GitHub inventing a new subpar programming language and expecting JetBrains and the others IDE to build decent tooling for it, we leverage the excellent tooling that already exists for Kotlin

[jmfayard]

Also regarding Vampire’s complex YAML workflow, I would say the worse part, for no fault of his own, is all those terrible GitHub expressions {{some.horrible.type.unsafe.magic}}

We just released type-safe expressions and I think they are pretty cool:
https://krzema12.github.io/github-actions-kotlin-dsl/user-guide/type-safe-expressions/

[jmfayard]

And doing more in Gradle is a good idea, but you would need to duplicate lots of GitHub Actions as Gradle Plugins to make it really work