Skip to content

FAQ

Why do we need the consistency check job?

Each YAML workflow generated by this library by default contains a job that reruns the Kotlin script where the workflow is defined, and ensures that the YAML file stored in the repository matches what is generated in the job.

The only valid definition of a GitHub Actions workflow is the YAML-based file. GitHub understand only this representation. In order to provide an alternative representation (here: using Kotlin scripting), we need to have a way of ensuring that whatever is described in the Kotlin scripts matches what is stored in the YAMLs. Otherwise, reading the Kotlin scripts wouldn't reflect what the workflows actually do. The only way of ensuring that e.g. no outdated YAML is run is to check the consistency before the workflow's main logic runs. The consistency check job performs the check directly before the main logic runs, and it's possible to perform this check on demand which is useful e.g. for workflows that aren't triggered in PRs. Adding the consistency check job to the YAML can be disabled, but it's not recommended if correctness is your priority, and should be done if you're sure what you're doing.

We realize that this extra runtime step adds certain overhead to the workflows, and that in fact the users of the library compromise their workflows' performance and sometimes sacrifice money (Actions credits) to get more type-safe workflows. We're working on making the situation better, but for now this is the price you need to pay to describe GitHub Actions workflows.

We've requested support for alternative ways of defining the workflows, not only in YAML: https://github.com/orgs/community/discussions/15904. However, we only got this answer saying YAML won't go anywhere soon and there are no plans of providing an alternative way.

Why do we need github-actions-typing? Shouldn't it be done by GitHub?

Yes, ideally it should. We've tried contacting GitHub and encouraging them to either introduce this mechanism as a first-party thing, or acknowledge this third-party tool to be recommended by GitHub.

See:

Kotlin scripts work as if changes in the imported files weren't applied. Why?

It's a known bug in the Kotlin compiler. In short, only changes in the top-level script trigger recompilation, and changes in the imported scripts make the Kotlin compiler reuse the cached JAR.

You can work around it in two ways:

  • remove the cache whenever needed, before rerunning the modified script. See this comment to learn where the cache is stored on popular operating systems,
  • disable caching by setting KOTLIN_MAIN_KTS_COMPILED_SCRIPTS_CACHE_DIR to an empty value.

Here's a ticket on the JetBrains side: [KT-42101] Scripts: @file:Import() in kotlin-main-kts uses a stale cache.

I'm getting an unexpected change in the resulting YAML, in the path to the script in the consistency check job. Why?

You're most likely affected by another bug related to stale cache. See the previous FAQ item for workarounds.

Here's a ticket on the JetBrains side: [KT-64367] Script: stale cache used if FILE is different

I'm having problems editing the Kotlin-based workflows in IntelliJ. Why?

Depending on the complexity of your workflows, you may stumble upon some rough edges in how IntelliJ supports Kotlin scripting. It's lagging behind the support provided by Kotlin itself.

Here's a list of tickets on the JetBrains side, along with proposed workarounds: