hello all - I'm looking for a way to use github-workflows-kt as a standalone GH workflow YAML builde...

# github-workflows-kt

[Damien O'Hara]

hello all - I'm looking for a way to use github-workflows-kt as a standalone GH workflow YAML builder without Kotlin script or any of the file handling/checking aspects. is this an intended/supported use-case? my current approach is to pass in a fake file path for sourceFile and call toYaml with addConsistencyCheck = false. example:

val wf = workflow(
    name = "test",
    on = listOf(Push()),
    sourceFile = Path("not-a-real-file")
) {
    job("test", runsOn = RunnerType.UbuntuLatest) {
        run(command = "echo 'Hello!'")
    }
}

val yaml = wf.toYaml(addConsistencyCheck = false)

println(yaml)

[Piotr Krzemiński]

Hi Damien! what do you mean by “a standalone GH workflow YAML builder without Kotlin script”? Where do you put the Kotlin code that defines the workflow? Is it like: you generate the YAML and forget about the Kotlin code or keep it outside of the repo?

[Damien O'Hara]

I'm working on a documentation generator that handles file generation, syncing and checking. at the moment I use it for generating markdown files but I'm experimenting to see if I can use it for Github workflows too. I was hoping to use github-workflows-kt to handle the generation of YAML text and then handle the file side of things separately

[Damien O'Hara]

I'm experimenting on a branch at the moment but you can see a rough WIP of what I mean here:

example check.yml file generation:
1. https://github.com/mfwgenerics/markout/blob/a92bdd8/readme/src/main/kotlin/Main.kt#L11-L16
2. https://github.com/mfwgenerics/markout/blob/a92bdd8/readme/src/main/kotlin/workflows/Check.kt
here is the wrapper I'm using `github-workflows-kt`:
1. https://github.com/mfwgenerics/markout/blob/a3624b9/markout-github-workflows-kt/src/main/kotlin/io/koalaql/markout/Workflows.kt

[Piotr Krzemiński]

I’ve actually always wanted to keep some order regarding the workflows, i.e. encourage keeping them next to the YAMLs. However, what you mention was touched when discussing support for writing the workflows from Gradle (cannot find the thread right now). Let me take a look at your code later this week, or let someone digest this use case

[Piotr Krzemiński]

so from what I see, you intend to keep source for docs and now the GitHub workflows in a single place/using a single top-level DSL?

[Piotr Krzemiński]

in general I’m open to making github-workflows-kt a stand-alone library that, once configured properly, doesn’t need git or the source file argument to work properly

[Piotr Krzemiński]

let’s have a feature request for it and describe the details there

[Piotr Krzemiński]

from quick thoughts:
• make sourceFile optional
• add a way to opt out from using git to figure out the repository root (used to be able to call the Kotlin script from any directory within the repository)

[Damien O'Hara]

yes, that would be perfect for my use case! I wonder also whether the presence/absence of the consistency check should be configured entirely at the Workflow level rather than the `toYaml`call. at any rate, optional sourceFile to opt out of features that require it would be sufficient for me

[Piotr Krzemiński]

that’s a good point, about moving the consistency check argument to toYaml - feel free to cut a ticket for it as well!

[Damien O'Hara]

great. are you happy for me to open both of these in Github issues?

[Piotr Krzemiński]

yes please 🙏

[Damien O'Hara]

I've just opened a ticket here: https://github.com/krzema12/github-workflows-kt/issues/656. thanks for the quick replies today!

[Piotr Krzemiński]

@Damien O'Hara thanks! I’m eager to implement it sooner than later, but if you want to tackle it and contribute to the project, you could have it released as soon as this Friday (usual biweekly releases). Just let me know, any answer is fine

[Damien O'Hara]

sounds good. I'll work on a PR this week and let you know how I go

[Damien O'Hara]

PR is waiting here: https://github.com/krzema12/github-workflows-kt/pull/657

[Piotr Krzemiński]

thanks, I’ll review it somehow later this week

[Piotr Krzemiński]

@Damien O'Hara merged, thanks! merged feel free to make the follow-up change with a custom preamble

[Piotr Krzemiński]

I thought about customizing only the part with the instruction what to do to regenerate the YAML, so instead of change the Kotlin source and regenerate this YAML file we can render the provided string under e.g. yamlModificationHint argument and default to what we have now. Does it make sense to you?

[Damien O'Hara]

thanks for the speedy merge. re: custom preamble. I think for cases where file generation is being handled externally it would make sense to allow full control of the preamble, including the option of no preamble. this flexibility would promote full separation of concerns

[Piotr Krzemiński]

got it, I’m fine with this - we could make the preamble customizable as well for writeToFile() for consistency

[Piotr Krzemiński]

I’ve seen people putting some copyright clauses, it would help with this use case as well

[Damien O'Hara]

good idea. if you're happy with that approach I could work on the PR tomorrow

[Piotr Krzemiński]

awesome! 🙂 here’s a separate issue for it: https://github.com/krzema12/github-workflows-kt/issues/660 so that we don't block the Friday's release on it

[Damien O'Hara]

I've just made a draft PR here: https://github.com/krzema12/github-workflows-kt/pull/667

[Piotr Krzemiński]

cool, let me know when it's ready to review (I assume draft can still change)

[Damien O'Hara]

was feeling indecisive - I've marked it ready now

[Piotr Krzemiński]

looks good, thanks! 🙇