I am big fan of explaining stuff to five years old because you push your limits as a pedagogue.
5 years old can understand many things you wouldn't expect if you exchange complex words for story telling.
So I'm going to explain my last project, whose main credits go to Piotr KrzemiΕski in both geek and greek editions.
Geek Mythology
If you are a DEV, this is the story we tell you :
typesafegithub/github-workflows-kt is a tool for creating GitHub Actions workflows in a type-safe script, helping you to build robust workflows for your GitHub projects without mistakes, with pleasure, in Kotlin.
You won't go back to YAML!
typesafegithub
/
github-workflows-kt
Authoring GitHub Actions workflows in Kotlin. You won't go back to YAML!
github-workflows-kt is a tool for creating GitHub Actions workflows in a type-safe script, helping you to build robust workflows for your GitHub projects without mistakes, with pleasure, in Kotlin.
You won't go back to YAML!
π‘ Idea
We're often surrounded by YAML configuration. It's a powerful format that provides simple syntax for defining hierarchical data, but it is sometimes used (abused?) to configure complicated scenarios which leads to complicated files that are difficult to write and maintain.
Who among us hasn't accidentally used the wrong indentation, missed a possibility to extract a reusable piece of code or been confused by ambiguous types? The power of a generic-purpose would come in handy in these cases.
We're developing github-workflows-kt to solve these and other problems, so you can create GitHub Workflows with confidence.
β¨ Benefits
- no indentation confusion - Kotlin's syntax doesn't rely on it
- immediate validation - catch bugsβ¦
Greek Mythology
It may sound tricky to explain type safety and YAML to a 5 years old
But those little devils are smart, so let's try.
Dear 5yo,
Typesafe Github Workflows are just like your favorite story from the greek mythology.
Odysseus and its crew, we call them the devs, have worked hard and want to go home.
But while they are heading home, a terror invade their hearts. They hear a seducing song from the sirens on an island called GitHub._
That song is written in a terrifying foreign language that pretend to be a programming language.
π± YAML π±.
The devs in the boat fear that it may be the very last sound they hear before their death.
There is in missing space in that YAML.
That may not sound much to you, but the YAML world is a very unstable world. That missing space changes everything and meances to destroy the whole world around the DEVs.
But Odysseus, just like my project, smartly put wax in the devs's ears, so they don't have to hear any of that scary YAML stuff, remain unaffected and go home safely.
Odeysseus and my project have to hear the YAML, and we struggle to resist, but in the end we live to tell the tale.
Top comments (7)
Is the idea that you use Kotlin and then that generates the YAML workflow? Also how does it work if you are using dependabot to monitor dependencies? For example, you author workflow in Kotlin. Then generate YAML from the Kotlin. Dependabot then comes along at some point and submits a PR to update the version of one of your actions in the YAML of your workflow. The Kotlin that you started with would still have the old version number of the action before the dependabot update. Is there a way of dealing with that?
Yes.
No, it's a known problem that remains unsolved for now. Here's an issue to track it: github.com/typesafegithub/github-w.... The only thing we can have for now is a consistency check in CI to ensure that the Kotlin script and the YAML are in sync, then the automated PR from Dependabot/Renovate won't be automatically merged, giving you a chance to adjust manually. I currently use this technique, and in practice (with my workflows) it's good enough, but I'm open to solving this problem the proper way.
Thanks. I noticed there is a list of supported actions. I maintain a few actions. What's involved to add support for an action?
We have a generator that automates 90% of the work of adding an action from the
action.ymlfile that you already have.What you need to do is to tell us the types of your parameters using a second YAML file
action-types.yml.See here :
github.com/typesafegithub/github-a...
You need to follow semantic versioning and have a major tag that points to the latest release
typesafegithub.github.io/github-wo...
If you are good to go, have a look at CONTRIBUTING.md
It looks straightforward enough. I have 2 more questions.
The contributing instructions indicate:
What commit hash is this looking for? The commit that the current major tag points to? Or something else?
My second question concerns location of
action-types.yml. Is there a preference for whether to simply host it in the action's repo? Or in the repo of github-workflows-kt? It looks like most are in the latter. But I'd think in the action's own repo would be preferred. E.g. less likely to forget about updating it with a new input, etc if it was in the action's repo.I don't know the details of commit-hash to be honest.
We started adding types in our repo because we couldn't just force all action owners on GitHub to do what we want :)
But indeed the type information is best maintained in your own repos so that they evolve together.
Thanks.