chore: rename githubToken to githubAuthToken (#1868)

Part of
#1854.

A "GitHub token" is, I think, a reserved name for a special kind of
token. With this change we'd like to express that the code can work with
various kinds of token that can be used to call GitHub's API, not
necessarily what is available under `GITHUB_TOKEN` and created by
GitHub, or not necessarily a Personal Access Token. In particulr, we're
working on switching to authenticating with a custom GitHub app where
we'll have Applicaiton Installation Token.

Author: krzema12

action-updates-checker/src/main/kotlin/io/github/typesafegithub/workflows/updates/Reporting.kt

@@ -2,7 +2,7 @@ package io.github.typesafegithub.workflows.updates
 
 import io.github.typesafegithub.workflows.domain.Workflow
 import io.github.typesafegithub.workflows.shared.internal.findGitRoot
-import io.github.typesafegithub.workflows.shared.internal.getGithubTokenOrNull
+import io.github.typesafegithub.workflows.shared.internal.getGithubAuthTokenOrNull
 import kotlinx.coroutines.flow.onEach
 import kotlinx.coroutines.flow.onEmpty
 import kotlinx.coroutines.flow.toList
@@ -14,33 +14,32 @@ import kotlin.io.path.relativeTo
 
 /**
  * will report all available updates in the terminal output and the github step summary
- * looks up the github token from env `GITHUB_TOKEN` by default
- * when no github token is present, reporting will be skipped
+ * when no github auth token is present, reporting will be skipped
  *
  * @param reportWhenTokenUnset enable to use github api without a token
- * @param githubToken if not set, will try to load from the environment variable `GITHUB_TOKEN`
+ * @param githubAuthToken if not set, will try to use one configured in the environment
  */
 public fun Workflow.reportAvailableUpdates(
     reportWhenTokenUnset: Boolean = false,
-    githubToken: String? = null,
+    githubAuthToken: String? = null,
 ): Unit =
     runBlocking {
         if (System.getenv("GHWKT_RUN_STEP") == null) {
             reportAvailableUpdatesInternal(
                 reportWhenTokenUnset = reportWhenTokenUnset,
-                githubToken = githubToken,
+                githubAuthToken = githubAuthToken,
             )
         }
     }
 
 internal suspend fun Workflow.reportAvailableUpdatesInternal(
     reportWhenTokenUnset: Boolean = false,
-    githubToken: String? = null,
+    githubAuthToken: String? = null,
     stepSummary: GithubStepSummary? = GithubStepSummary.fromEnv(),
 ) {
     availableVersionsForEachAction(
         reportWhenTokenUnset = reportWhenTokenUnset,
-        githubToken = githubToken ?: getGithubTokenOrNull(),
+        githubAuthToken = githubAuthToken ?: getGithubAuthTokenOrNull(),
     ).onEach { regularActionVersions ->
         val usesString =
             with(regularActionVersions.action) {

action-updates-checker/src/main/kotlin/io/github/typesafegithub/workflows/updates/Utils.kt

@@ -5,7 +5,7 @@ import io.github.typesafegithub.workflows.domain.ActionStep
 import io.github.typesafegithub.workflows.domain.Workflow
 import io.github.typesafegithub.workflows.domain.actions.RegularAction
 import io.github.typesafegithub.workflows.shared.internal.fetchAvailableVersions
-import io.github.typesafegithub.workflows.shared.internal.getGithubTokenOrNull
+import io.github.typesafegithub.workflows.shared.internal.getGithubAuthTokenOrNull
 import io.github.typesafegithub.workflows.shared.internal.model.Version
 import io.github.typesafegithub.workflows.updates.model.RegularActionVersions
 import kotlinx.coroutines.flow.Flow
@@ -17,9 +17,9 @@ import kotlin.io.path.readText
 
 internal suspend fun Workflow.availableVersionsForEachAction(
     reportWhenTokenUnset: Boolean = true,
-    githubToken: String? = getGithubTokenOrNull(),
+    githubAuthToken: String? = getGithubAuthTokenOrNull(),
 ): Flow<RegularActionVersions> {
-    if (githubToken == null && !reportWhenTokenUnset) {
+    if (githubAuthToken == null && !reportWhenTokenUnset) {
         githubWarning("github token is required, but not set, skipping api calls")
         return emptyFlow()
     }
@@ -28,7 +28,7 @@ internal suspend fun Workflow.availableVersionsForEachAction(
         groupedSteps.forEach { (action, steps) ->
             val availableVersions =
                 action.fetchAvailableVersionsOrWarn(
-                    githubToken = githubToken,
+                    githubAuthToken = githubAuthToken,
                 )
             val currentVersion = Version(action.actionVersion)
             if (availableVersions != null) {
@@ -49,12 +49,12 @@ internal suspend fun Workflow.availableVersionsForEachAction(
     }
 }
 
-internal suspend fun RegularAction<*>.fetchAvailableVersionsOrWarn(githubToken: String?): List<Version>? =
+internal suspend fun RegularAction<*>.fetchAvailableVersionsOrWarn(githubAuthToken: String?): List<Version>? =
     try {
         fetchAvailableVersions(
             owner = actionOwner,
             name = actionName.substringBefore('/'),
-            githubToken = githubToken,
+            githubAuthToken = githubAuthToken,
         ).getOrElse {
             throw Exception(it)
         }

action-updates-checker/src/test/kotlin/io/github/typesafegithub/workflows/updates/ReportingTest.kt

@@ -5,7 +5,7 @@ import io.github.typesafegithub.workflows.domain.Workflow
 import io.github.typesafegithub.workflows.domain.actions.CustomAction
 import io.github.typesafegithub.workflows.domain.triggers.Push
 import io.github.typesafegithub.workflows.dsl.workflow
-import io.github.typesafegithub.workflows.shared.internal.getGithubTokenOrNull
+import io.github.typesafegithub.workflows.shared.internal.getGithubAuthTokenOrNull
 import io.kotest.common.ExperimentalKotest
 import io.kotest.core.spec.style.FunSpec
 import io.kotest.engine.spec.tempdir
@@ -19,7 +19,7 @@ import kotlinx.coroutines.runBlocking
 class ReportingTest :
     FunSpec(
         {
-            val token = getGithubTokenOrNull()
+            val token = getGithubAuthTokenOrNull()
             context("tests using github token").config(enabled = token != null) {
                 val gitRootDir =
                     tempdir()
@@ -107,7 +107,7 @@ class ReportingTest :
                         runBlocking {
                             it.availableVersionsForEachAction(
                                 reportWhenTokenUnset = false,
-                                githubToken = null,
+                                githubAuthToken = null,
                             )
                         }
                     }.toList()

jit-binding-server/src/main/kotlin/io/github/typesafegithub/workflows/jitbindingserver/MetadataRoutes.kt

@@ -1,7 +1,7 @@
 package io.github.typesafegithub.workflows.jitbindingserver
 
 import io.github.typesafegithub.workflows.mavenbinding.buildPackageArtifacts
-import io.github.typesafegithub.workflows.shared.internal.getGithubToken
+import io.github.typesafegithub.workflows.shared.internal.getGithubAuthToken
 import io.ktor.http.HttpStatusCode
 import io.ktor.server.response.respondText
 import io.ktor.server.routing.Route
@@ -26,7 +26,7 @@ private fun Route.metadata(refresh: Boolean = false) {
         val file = call.parameters["file"] ?: return@get call.respondNotFound()
         val actionCoords = call.parameters.extractActionCoords(extractVersion = false)
 
-        val bindingArtifacts = actionCoords.buildPackageArtifacts(githubToken = getGithubToken())
+        val bindingArtifacts = actionCoords.buildPackageArtifacts(githubAuthToken = getGithubAuthToken())
         if (file in bindingArtifacts) {
             when (val artifact = bindingArtifacts[file]) {
                 is String -> call.respondText(text = artifact)

maven-binding-builder/src/main/kotlin/io/github/typesafegithub/workflows/mavenbinding/MavenMetadataBuilding.kt

@@ -12,15 +12,15 @@ import java.time.format.DateTimeFormatter
 private val logger = logger { }
 
 internal suspend fun ActionCoords.buildMavenMetadataFile(
-    githubToken: String,
+    githubAuthToken: String,
     fetchAvailableVersions: suspend (
         owner: String,
         name: String,
-        githubToken: String?,
+        githubAuthToken: String?,
     ) -> Either<String, List<Version>> = ::fetchAvailableVersions,
 ): String? {
     val availableVersions =
-        fetchAvailableVersions(owner, name, githubToken)
+        fetchAvailableVersions(owner, name, githubAuthToken)
             .getOrElse {
                 logger.error { it }
                 emptyList()

maven-binding-builder/src/main/kotlin/io/github/typesafegithub/workflows/mavenbinding/PackageArtifactsBuilding.kt

@@ -2,8 +2,8 @@ package io.github.typesafegithub.workflows.mavenbinding
 
 import io.github.typesafegithub.workflows.actionbindinggenerator.domain.ActionCoords
 
-suspend fun ActionCoords.buildPackageArtifacts(githubToken: String): Map<String, String> {
-    val mavenMetadata = buildMavenMetadataFile(githubToken = githubToken) ?: return emptyMap()
+suspend fun ActionCoords.buildPackageArtifacts(githubAuthToken: String): Map<String, String> {
+    val mavenMetadata = buildMavenMetadataFile(githubAuthToken = githubAuthToken) ?: return emptyMap()
     return mapOf(
         "maven-metadata.xml" to mavenMetadata,
         "maven-metadata.xml.md5" to mavenMetadata.md5Checksum(),

maven-binding-builder/src/test/kotlin/io/github/typesafegithub/workflows/mavenbinding/MavenMetadataBuildingTest.kt

@@ -37,7 +37,7 @@ class MavenMetadataBuildingTest :
 
             val xml =
                 actionCoords.buildMavenMetadataFile(
-                    githubToken = "SOME_TOKEN",
+                    githubAuthToken = "SOME_TOKEN",
                     fetchAvailableVersions = fetchAvailableVersions,
                 )
 
@@ -74,7 +74,7 @@ class MavenMetadataBuildingTest :
 
             val xml =
                 actionCoords.buildMavenMetadataFile(
-                    githubToken = "SOME_TOKEN",
+                    githubAuthToken = "SOME_TOKEN",
                     fetchAvailableVersions = fetchAvailableVersions,
                 )
 
@@ -89,7 +89,7 @@ class MavenMetadataBuildingTest :
 
             val xml =
                 actionCoords.buildMavenMetadataFile(
-                    githubToken = "SOME_TOKEN",
+                    githubAuthToken = "SOME_TOKEN",
                     fetchAvailableVersions = fetchAvailableVersions,
                 )
 
@@ -114,7 +114,7 @@ class MavenMetadataBuildingTest :
 
                 val xml =
                     actionCoords.copy(significantVersion = significantVersion).buildMavenMetadataFile(
-                        githubToken = "SOME_TOKEN",
+                        githubAuthToken = "SOME_TOKEN",
                         fetchAvailableVersions = fetchAvailableVersions,
                     )
 

shared-internal/src/main/kotlin/io/github/typesafegithub/workflows/shared/internal/GithubApi.kt

@@ -21,20 +21,20 @@ import java.time.ZonedDateTime
 suspend fun fetchAvailableVersions(
     owner: String,
     name: String,
-    githubToken: String?,
+    githubAuthToken: String?,
     httpClientEngine: HttpClientEngine = CIO.create(),
 ): Either<String, List<Version>> =
     either {
         val httpClient = buildHttpClient(engine = httpClientEngine)
         return listOf(
             apiTagsUrl(owner = owner, name = name),
             apiBranchesUrl(owner = owner, name = name),
-        ).flatMap { url -> fetchGithubRefs(url, githubToken, httpClient).bind() }
-            .versions(githubToken, httpClient)
+        ).flatMap { url -> fetchGithubRefs(url, githubAuthToken, httpClient).bind() }
+            .versions(githubAuthToken, httpClient)
     }
 
 private fun List<GithubRef>.versions(
-    githubToken: String?,
+    githubAuthToken: String?,
     httpClient: HttpClient,
 ): Either<String, List<Version>> =
     either {
@@ -44,8 +44,8 @@ private fun List<GithubRef>.versions(
                 val response =
                     httpClient
                         .get(urlString = githubRef.`object`.url) {
-                            if (githubToken != null) {
-                                bearerAuth(githubToken)
+                            if (githubAuthToken != null) {
+                                bearerAuth(githubAuthToken)
                             }
                         }
                 val releaseDate =
@@ -61,15 +61,15 @@ private fun List<GithubRef>.versions(
 
 private suspend fun fetchGithubRefs(
     url: String,
-    githubToken: String?,
+    githubAuthToken: String?,
     httpClient: HttpClient,
 ): Either<String, List<GithubRef>> =
     either {
         val response =
             httpClient
                 .get(urlString = url) {
-                    if (githubToken != null) {
-                        bearerAuth(githubToken)
+                    if (githubAuthToken != null) {
+                        bearerAuth(githubAuthToken)
                     }
                 }
         ensure(response.status.isSuccess()) {

shared-internal/src/main/kotlin/io/github/typesafegithub/workflows/shared/internal/GithubUtils.kt

@@ -1,6 +1,12 @@
 package io.github.typesafegithub.workflows.shared.internal
 
-fun getGithubTokenOrNull(): String? =
+/**
+ * Returns a token that should be used to make authorized calls to GitHub,
+ * or null if no token was configured.
+ * The token may be of various kind, e.g. a Personal Access Token, or an
+ * Application Installation Token.
+ */
+fun getGithubAuthTokenOrNull(): String? =
     System
         .getenv("GITHUB_TOKEN")
         .also {
@@ -15,7 +21,13 @@ fun getGithubTokenOrNull(): String? =
             }
         }
 
-fun getGithubToken(): String =
+/**
+ * Returns a token that should be used to make authorized calls to GitHub,
+ * or throws an exception if no token was configured.
+ * The token may be of various kind, e.g. a Personal Access Token, or an
+ * Application Installation Token.
+ */
+fun getGithubAuthToken(): String =
     System.getenv("GITHUB_TOKEN")
         ?: error(
             """

shared-internal/src/test/kotlin/io/github/typesafegithub/workflows/shared/internal/model/GithubApiTest.kt

@@ -98,7 +98,7 @@ class GithubApiTest :
                 fetchAvailableVersions(
                     owner = "some-owner",
                     name = "some-name",
-                    githubToken = "token",
+                    githubAuthToken = "token",
                     httpClientEngine = mockEngine,
                 )
 
@@ -129,7 +129,7 @@ class GithubApiTest :
                 fetchAvailableVersions(
                     owner = "some-owner",
                     name = "some-name",
-                    githubToken = "token",
+                    githubAuthToken = "token",
                     httpClientEngine = mockEngine,
                 )