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:

  • [KTIJ-14580] Imported script are not supported for scripts outside of a source root
    It's possible to partially mitigate it by adding dependencies from the imported files directly in the top-level script.

  • [KTIJ-16532] Scripting: dependencies do not open source files
    There are several workarounds: browse the code in GitHub, add a dependency on the library in your main project which will let you browse the source code in the IDE, or maybe it's enough to use the rendered API docs.

  • [KTIJ-31203] main.kts script handler uses stale @Repository value to resolve dependencies
    When changing @Repository values, close the IntelliJ project and re-open it. If IntelliJ already resolved the dependency from the old repository, you might need to delete it from the Maven Local cache repository and after that restart the whole IDE as IntelliJ might not see the recreated file even after executing the workflow script and the file was recreated in the Maven Local cache repository. (also see next points)

  • A new release of an action added some input, but I don't see it in the IDE
    If you depend on a major version of an action like v1 and the action adds backwards compatible changes in a new release that adds inputs, the generated v1 bindings are already present in your Maven Local cache repository and you do not get a new binding generated that includes the new inputs. To work-around this, delete the cache binding from your Maven Local cache repository, which typically is located at ~/.m2/respository/. After that, executing or syncing the workflow script will re-request a fresh binding from the binding server that will include the up-to-date state of the action.

  • [KTIJ-31214] Deleting a dependency jar from Maven Local and recreating it leaves *.main.kts script with unresolved symbols until IDE is restarted
    After following the previous step and deleting a dependency from the Maven Local cache repository to get it updated, IntelliJ will not re-resolve the dependency and even doing so in another way like actually executing the workflow script, IntelliJ still treats the classes as unresolved symbols. To get to a usable state again, you need to restart the whole IDE, just closing and re-opening the project is not sufficient.