feat(library): add API for adding intended action version in comment (#2118)

krzema12 · web-flow · commit bd933fe44236 · 2025-11-04T08:15:00.000+01:00
Part of #1691. This change adds API to be able to add a comment with an intended action version to the YAML. See an example: ```yaml - id: 'step-0' name: 'Check out' uses: 'actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8' # v5.0.0 ``` This follows the approach that Renovate uses, see https://docs.renovatebot.com/modules/manager/github-actions/#digest-pinning-and-updating. It's also a part of implementing [2025-04-27 Enhancements to referring to actions by commit hash](https://github.com/typesafegithub/design-docs/blob/main/2025-04-27%20Enhancements%20to%20referring%20to%20actions%20by%20commit%20hash.md). This change needs to go as the very first one. It needs to land in a library release, so that the server can generate action bindings using the extended `RegularAction` base class. ABI-wise, `RegularAction` is modified in a backward-compatible way because classes inheriting from it are generated by the bindings server. For `CustomAction`, all that is provided is source-level backward compatibility which is IMO good enough.
diff --git a/github-workflows-kt/api/github-workflows-kt.api b/github-workflows-kt/api/github-workflows-kt.api
@@ -529,20 +529,22 @@ public class io/github/typesafegithub/workflows/domain/actions/Action$Outputs {
 }
 
 public final class io/github/typesafegithub/workflows/domain/actions/CustomAction : io/github/typesafegithub/workflows/domain/actions/RegularAction {
-	public fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;)V
-	public synthetic fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;)V
+	public synthetic fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public fun buildOutputObject (Ljava/lang/String;)Lio/github/typesafegithub/workflows/domain/actions/Action$Outputs;
 	public final fun component1 ()Ljava/lang/String;
 	public final fun component2 ()Ljava/lang/String;
 	public final fun component3 ()Ljava/lang/String;
-	public final fun component4 ()Ljava/util/Map;
-	public final fun copy (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;)Lio/github/typesafegithub/workflows/domain/actions/CustomAction;
-	public static synthetic fun copy$default (Lio/github/typesafegithub/workflows/domain/actions/CustomAction;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)Lio/github/typesafegithub/workflows/domain/actions/CustomAction;
+	public final fun component4 ()Ljava/lang/String;
+	public final fun component5 ()Ljava/util/Map;
+	public final fun copy (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;)Lio/github/typesafegithub/workflows/domain/actions/CustomAction;
+	public static synthetic fun copy$default (Lio/github/typesafegithub/workflows/domain/actions/CustomAction;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/Map;ILjava/lang/Object;)Lio/github/typesafegithub/workflows/domain/actions/CustomAction;
 	public fun equals (Ljava/lang/Object;)Z
 	public fun getActionName ()Ljava/lang/String;
 	public fun getActionOwner ()Ljava/lang/String;
 	public fun getActionVersion ()Ljava/lang/String;
 	public final fun getInputs ()Ljava/util/Map;
+	public fun getIntendedVersion ()Ljava/lang/String;
 	public fun hashCode ()I
 	public fun toString ()Ljava/lang/String;
 	public fun toYamlArguments ()Ljava/util/LinkedHashMap;
@@ -601,9 +603,12 @@ public abstract class io/github/typesafegithub/workflows/domain/actions/LocalAct
 
 public abstract class io/github/typesafegithub/workflows/domain/actions/RegularAction : io/github/typesafegithub/workflows/domain/actions/Action {
 	public fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V
+	public fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V
+	public synthetic fun <init> (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
 	public fun getActionName ()Ljava/lang/String;
 	public fun getActionOwner ()Ljava/lang/String;
 	public fun getActionVersion ()Ljava/lang/String;
+	public fun getIntendedVersion ()Ljava/lang/String;
 	public fun getUsesString ()Ljava/lang/String;
 }
 
diff --git a/github-workflows-kt/src/main/kotlin/io/github/typesafegithub/workflows/domain/actions/Action.kt b/github-workflows-kt/src/main/kotlin/io/github/typesafegithub/workflows/domain/actions/Action.kt
@@ -25,7 +25,19 @@ public abstract class RegularAction<out OUTPUTS : Outputs>(
     public open val actionOwner: String,
     public open val actionName: String,
     public open val actionVersion: String,
+    /**
+     * Can be set if [actionVersion] is set to a commit hash. Then, [intendedVersion] should be set to the version of
+     * the action corresponding to the commit hash. Thanks to this, the intended version will be used in the resulting
+     * workflow's YAML, as a hint for humans and automation tools related to version management.
+     */
+    public open val intendedVersion: String? = null,
 ) : Action<OUTPUTS>() {
+    public constructor(
+        actionOwner: String,
+        actionName: String,
+        actionVersion: String,
+    ) : this(actionOwner = actionOwner, actionName = actionName, actionVersion = actionVersion, intendedVersion = null)
+
     override val usesString: String
         get() = "$actionOwner/$actionName@$actionVersion"
 }
diff --git a/github-workflows-kt/src/main/kotlin/io/github/typesafegithub/workflows/domain/actions/CustomAction.kt b/github-workflows-kt/src/main/kotlin/io/github/typesafegithub/workflows/domain/actions/CustomAction.kt
@@ -12,6 +12,7 @@ public data class CustomAction(
     override val actionOwner: String,
     override val actionName: String,
     override val actionVersion: String,
+    override val intendedVersion: String? = null,
     public val inputs: Map<String, String> = emptyMap(),
 ) : RegularAction<Outputs>(actionOwner, actionName, actionVersion) {
     override fun toYamlArguments(): LinkedHashMap<String, String> = LinkedHashMap(inputs)
diff --git a/github-workflows-kt/src/main/kotlin/io/github/typesafegithub/workflows/yaml/ObjectToYaml.kt b/github-workflows-kt/src/main/kotlin/io/github/typesafegithub/workflows/yaml/ObjectToYaml.kt
@@ -2,9 +2,12 @@ package io.github.typesafegithub.workflows.yaml
 
 import it.krzeminski.snakeyaml.engine.kmp.api.DumpSettings
 import it.krzeminski.snakeyaml.engine.kmp.api.StreamDataWriter
+import it.krzeminski.snakeyaml.engine.kmp.comments.CommentType
+import it.krzeminski.snakeyaml.engine.kmp.comments.CommentType.IN_LINE
 import it.krzeminski.snakeyaml.engine.kmp.common.FlowStyle
 import it.krzeminski.snakeyaml.engine.kmp.common.ScalarStyle
 import it.krzeminski.snakeyaml.engine.kmp.emitter.Emitter
+import it.krzeminski.snakeyaml.engine.kmp.events.CommentEvent
 import it.krzeminski.snakeyaml.engine.kmp.events.DocumentEndEvent
 import it.krzeminski.snakeyaml.engine.kmp.events.DocumentStartEvent
 import it.krzeminski.snakeyaml.engine.kmp.events.ImplicitTuple
@@ -23,6 +26,7 @@ internal fun Any.toYaml(): String {
             // Otherwise line breaks appear in places that create an incorrect YAML, e.g. in the middle of GitHub
             // expressions.
             width = Int.MAX_VALUE,
+            dumpComments = true,
         )
     val writer =
         object : StringWriter(), StreamDataWriter {
@@ -46,6 +50,10 @@ private fun Any?.elementToYaml(emitter: Emitter) {
         is Map<*, *> -> this.mapToYaml(emitter)
         is List<*> -> this.listToYaml(emitter)
         is String, is Int, is Float, is Double, is Boolean, null -> this.scalarToYaml(emitter)
+        is StringWithComment -> {
+            this.value.scalarToYaml(emitter)
+            (" " + this.comment).commentToYaml(emitter)
+        }
         else -> error("Serializing $this is not supported!")
     }
 }
@@ -96,3 +104,14 @@ private fun Any?.scalarToYaml(emitter: Emitter) {
         ScalarEvent(null, null, ImplicitTuple(true, true), this.toString(), scalarStyle),
     )
 }
+
+private fun String.commentToYaml(emitter: Emitter) {
+    emitter.emit(
+        CommentEvent(
+            commentType = IN_LINE,
+            value = this,
+            startMark = null,
+            endMark = null,
+        ),
+    )
+}
diff --git a/github-workflows-kt/src/main/kotlin/io/github/typesafegithub/workflows/yaml/StepsToYaml.kt b/github-workflows-kt/src/main/kotlin/io/github/typesafegithub/workflows/yaml/StepsToYaml.kt
@@ -12,6 +12,7 @@ import io.github.typesafegithub.workflows.domain.Shell.Pwsh
 import io.github.typesafegithub.workflows.domain.Shell.Python
 import io.github.typesafegithub.workflows.domain.Shell.Sh
 import io.github.typesafegithub.workflows.domain.Step
+import io.github.typesafegithub.workflows.domain.actions.RegularAction
 
 internal fun List<Step<*>>.stepsToYaml(): List<Map<String, Any?>> = this.map { it.toYaml() }
 
@@ -28,7 +29,14 @@ private fun ActionStep<*>.toYaml(): Map<String, Any?> =
         "name" to name,
         "continue-on-error" to continueOnError,
         "timeout-minutes" to timeoutMinutes,
-        "uses" to action.usesString,
+        "uses" to
+            this.action.let {
+                if (it is RegularAction && it.intendedVersion != null) {
+                    StringWithComment(it.usesString, it.intendedVersion!!)
+                } else {
+                    it.usesString
+                }
+            },
         "with" to action.toYamlArguments().ifEmpty { null },
         "env" to env.ifEmpty { null },
         "if" to condition,
diff --git a/github-workflows-kt/src/main/kotlin/io/github/typesafegithub/workflows/yaml/StringWithComment.kt b/github-workflows-kt/src/main/kotlin/io/github/typesafegithub/workflows/yaml/StringWithComment.kt
@@ -0,0 +1,6 @@
+package io.github.typesafegithub.workflows.yaml
+
+internal data class StringWithComment(
+    val value: String,
+    val comment: String,
+)
diff --git a/github-workflows-kt/src/test/kotlin/io/github/typesafegithub/workflows/IntegrationTest.kt b/github-workflows-kt/src/test/kotlin/io/github/typesafegithub/workflows/IntegrationTest.kt
@@ -6,6 +6,9 @@ import io.github.typesafegithub.workflows.actions.endbug.AddAndCommit
 import io.github.typesafegithub.workflows.annotations.ExperimentalKotlinLogicStep
 import io.github.typesafegithub.workflows.domain.Concurrency
 import io.github.typesafegithub.workflows.domain.RunnerType
+import io.github.typesafegithub.workflows.domain.actions.Action
+import io.github.typesafegithub.workflows.domain.actions.Action.Outputs
+import io.github.typesafegithub.workflows.domain.actions.RegularAction
 import io.github.typesafegithub.workflows.domain.triggers.Push
 import io.github.typesafegithub.workflows.dsl.expressions.expr
 import io.github.typesafegithub.workflows.dsl.workflow
@@ -912,4 +915,57 @@ class IntegrationTest :
                 """.trimIndent()
             targetTempFile.exists() shouldBe false
         }
+
+        test("action version with comment") {
+            // when
+            workflow(
+                name = "Test workflow",
+                on = listOf(Push()),
+                sourceFile = sourceTempFile,
+                consistencyCheckJobConfig = Disabled,
+            ) {
+                job(
+                    id = "test_job",
+                    runsOn = RunnerType.UbuntuLatest,
+                ) {
+                    uses(
+                        name = "Check out",
+                        action =
+                            object : RegularAction<Outputs>(
+                                actionOwner = "actions",
+                                actionName = "checkout",
+                                actionVersion = "08c6903cd8c0fde910a37f88322edcfb5dd907a8",
+                                intendedVersion = "v5.0.0",
+                            ) {
+                                override fun toYamlArguments(): LinkedHashMap<String, String> =
+                                    linkedMapOf("path" to "my-repo")
+
+                                override fun buildOutputObject(stepId: String): Outputs = Outputs(stepId)
+                            },
+                    )
+                }
+            }
+
+            // then
+            targetTempFile.readText() shouldBe
+                """
+                # This file was generated using Kotlin DSL (.github/workflows/some_workflow.main.kts).
+                # If you want to modify the workflow, please change the Kotlin file and regenerate this YAML file.
+                # Generated with https://github.com/typesafegithub/github-workflows-kt
+
+                name: 'Test workflow'
+                on:
+                  push: {}
+                jobs:
+                  test_job:
+                    runs-on: 'ubuntu-latest'
+                    steps:
+                    - id: 'step-0'
+                      name: 'Check out'
+                      uses: 'actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8' # v5.0.0
+                      with:
+                        path: 'my-repo'
+
+                """.trimIndent()
+        }
     })
diff --git a/github-workflows-kt/src/test/kotlin/io/github/typesafegithub/workflows/yaml/ObjectToYamlTest.kt b/github-workflows-kt/src/test/kotlin/io/github/typesafegithub/workflows/yaml/ObjectToYamlTest.kt
@@ -140,4 +140,24 @@ class ObjectToYamlTest :
 
                 """.trimIndent()
         }
+
+        it("correctly serializes string with comment") {
+            // given
+            val objectToSerialize =
+                mapOf(
+                    "foo" to "bar",
+                    "baz" to StringWithComment("goo", "cool-comment"),
+                )
+
+            // when
+            val yaml = objectToSerialize.toYaml()
+
+            // then
+            yaml shouldBe
+                """
+                foo: 'bar'
+                baz: 'goo' # cool-comment
+
+                """.trimIndent()
+        }
     })
diff --git a/github-workflows-kt/src/test/kotlin/io/github/typesafegithub/workflows/yaml/StepsToYamlTest.kt b/github-workflows-kt/src/test/kotlin/io/github/typesafegithub/workflows/yaml/StepsToYamlTest.kt
@@ -8,7 +8,9 @@ import io.github.typesafegithub.workflows.actions.actions.UploadArtifact
 import io.github.typesafegithub.workflows.domain.ActionStep
 import io.github.typesafegithub.workflows.domain.CommandStep
 import io.github.typesafegithub.workflows.domain.Shell
+import io.github.typesafegithub.workflows.domain.actions.Action
 import io.github.typesafegithub.workflows.domain.actions.CustomAction
+import io.github.typesafegithub.workflows.domain.actions.RegularAction
 import io.kotest.core.spec.style.DescribeSpec
 import io.kotest.matchers.shouldBe
 
@@ -460,5 +462,40 @@ class StepsToYamlTest :
                         ),
                     )
             }
+
+            it("renders with comment") {
+                // given
+                val steps =
+                    listOf(
+                        ActionStep(
+                            id = "someId",
+                            action =
+                                object : RegularAction<Action.Outputs>(
+                                    actionOwner = "some-owner",
+                                    actionName = "some-name",
+                                    actionVersion = "some-commit-hash",
+                                    intendedVersion = "some-version",
+                                ) {
+                                    override fun toYamlArguments(): LinkedHashMap<String, String> =
+                                        linkedMapOf("foo" to "bar")
+
+                                    override fun buildOutputObject(stepId: String): Outputs = Outputs(stepId)
+                                },
+                        ),
+                    )
+
+                // when
+                val yaml = steps.stepsToYaml()
+
+                // then
+                yaml shouldBe
+                    listOf(
+                        mapOf(
+                            "id" to "someId",
+                            "uses" to StringWithComment("some-owner/some-name@some-commit-hash", "some-version"),
+                            "with" to mapOf("foo" to "bar"),
+                        ),
+                    )
+            }
         }
     })
