Getting started

As an exercise, we'll add a job that prints out Hello world!. Feel free to replace the actual workflow's logic and all names with your own.

1. Install Kotlin as a stand-alone binary, e.g. from Snap Store when on Linux:

   sudo snap install kotlin --classic
   

   Make sure this is the newest version available. Kotlin scripting still has some rough edges, and improvements are introduced with each new Kotlin release. Also make sure that you use Java 11+.
2. Create a new executable file in your repository:

   touch    .github/workflows/hello_world_workflow.main.kts
   chmod +x .github/workflows/hello_world_workflow.main.kts
   

   This location is not a hard requirement, it's just recommended for consistency with enforced location of actual GitHub Actions workflows.
3. Put this content into the previously created file and save it:

   #!/usr/bin/env kotlin
   
   @file:Repository("https://repo.maven.apache.org/maven2/")
   @file:DependsOn("io.github.typesafegithub:github-workflows-kt:3.0.1")
   @file:Repository("https://bindings.krzeminski.it")
   @file:DependsOn("actions:checkout:v4")
   
   import io.github.typesafegithub.workflows.actions.actions.Checkout
   import io.github.typesafegithub.workflows.domain.RunnerType.UbuntuLatest
   import io.github.typesafegithub.workflows.domain.triggers.Push
   import io.github.typesafegithub.workflows.dsl.workflow
   
   workflow(
       name = "Test workflow",
       on = listOf(Push()),
       sourceFile = __FILE__,
   ) {
       job(id = "test_job", runsOn = UbuntuLatest) {
           uses(name = "Check out", action = Checkout())
           run(name = "Print greeting", command = "echo 'Hello world!'")
       }
   }
   

   This way we create a workflow with the DSL provided by this library. The reason it needs source file path is to be able to generate consistency checks, to ensure that both source and target files are in sync. You'll see it in a moment in the generated file.
4. Generate the YAML by calling the above script:

   .github/workflows/hello_world_workflow.main.kts
   

   It can be also executed straight from IntelliJ, by clicking the green ▶️ button next to the shebang. Notice that there's an extra job generated by the library that regenerates the YAML in job's runtime and ensures that it's equal to the YAML committed to the repository.
5. Commit both files, push the changes to GitHub and make sure the workflow is green when ran on GitHub Actions.
6. Last but not least, feel invited to join the Slack channel dedicated to this library. You'll find information about upcoming breaking changes, discussion about new features, and more! If you don't know how to sign up to the Kotlin's Slack space, see here.