How to run a Kotlin script on GitHub Actions?

Question

I want to run Kotlin scripts in CI without relying on a Gradle project, so I can easily do operations that would be hard to program using shell/bash/batch, and so that I can use libraries if needed.

Having the Kotlin script run only on Ubuntu/Linux is fine, though ideally, there's a way to make it run on Windows and macOS targets as well for platform specific projects.

Answer 1

UPDATE: Kotlin is now pre-installed on GitHub Actions runners, no need to install it beforehand anymore.

First, ensure that you have a proper Kotlin script, ending in .kts, or better, .main.kts as that latter one will be recognized better by the IDE (e.g. IntelliJ IDEA, Android Studio), especially when it comes to autocompletion and type analysis.

Second, ensure that its first line is the shebang pointing to the right place:

#!/usr/bin/env kotlin

That will be helpful to test the script locally before running in CI, as the IDE will show a run button in the gutter, next to the shebang. If you add the execute permission to the file (chmod +x YouScript.main.kts on Linux/macOS), you'll also be able to run it just like any other script, without having to type kotlinc -script before, and that will apply on GitHub Actions as well.

Finally, here's an example manual GitHub Action (aka. workflow file) that will take an input and pass it to your Kotlin script (usable in the args property/parameter) after it installed Kotlin:

name: Run Kotlin script

on:
  workflow_dispatch:
    inputs:
      awesome-input:
        description: 'Awesome parameter'
        default: 'You'
        required: true

jobs:
  awesome-action:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Run Kotlin script
      run: kotlinc -script ./YourScript.main.kts ${{ github.event.inputs.awesome-input }}

Note that if the script has the execute (x) permission, as I told previously, you can remove the kotlinc -script part and it will still run.

Bonus: it is possible to have Kotlin code directly in the workflow file (though I'd not recommend doing it), by using kotlin as a shell. See this YouTrack comment to see how: https://youtrack.jetbrains.com/issue/KT-43534#focus=Comments-27-4640716.0-0

Answer 2

Kotlin runner is now pre-installed on GitHub Actions environments (GitHub issue, YouTube video).
Refer to the GitHub Actions runner images¹ to see all the installed software.

So, you can easily run your .main.kts scripts like this:

name: Example

on:
  push:
    branches:
      - main

jobs:
  example-action:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run the script
        run: kotlin /path/in/repo/to/my-script.main.kts

And here is an example my-script.main.kts file:

@file:JvmName("MyScript")
@file:CompilerOptions("-jvm-target", "11")
@file:Repository("https://repo.maven.apache.org/maven2")
// @file:DependsOn("com.example:library:1.2.3")

import java.io.File

val input = File("README.md") // Assuming you ran checkout before
val output = File("result.txt")
val readmeFirstLine = input.readLines().first()
output.writeText(readmeFirstLine)

There is also a GitHub action called setup-kotlin that lets you install your desired version of Kotlin and also provides some more features. Check out this issue.

...
  - uses: actions/checkout@v3
  - uses: fwilhe2/setup-kotlin@main
    with:
      version: 1.7.0
  - name: Run the script
    run: kotlin /path/in/repo/to/my-script.main.kts

---

1. It was previously called virtual environments