Введение
GitHub Actions (GHA) — это отличный инструмент для настройки CI/CD для тех, кто пользуется GitHub. Существует и GitHub Marketplace, где можно найти тысячи готовых GHA под любые задачи. Но всегда найдётся процесс, который захочется настроить под себя — тогда нам придётся написать кастомный GHA.
В этой статье я покажу, как создать свой GHA на Kotlin/JS, используя плагин Kotlin Multiplatform. Особенно это будет интересно Android-разработчикам, ведь Kotlin — это наш родной язык, и мы можем применять уже имеющиеся навыки для написания GHA, не углубляясь в JavaScript.
В конце статьи вас ждёт готовый шаблон в GitHub. С его помощью вы сможете сразу приступить к написанию GHA на Kotlin/JS, минуя написание бойлерплейт-кода. О нём я и расскажу в этой статье.
Погнали!
GitHub Actions
GitHub Actions — это встроенный в GitHub инструмент, который даёт возможность настраивать CI/CD процессы. Например, когда в репозитории происходит событие, коммит или pull request, GHA автоматически запускает нужные скрипты. Одним словом — это наш инструмент для CI/CD.
В GHA всё начинается с Workflow — именно его GitHub Actions выполняет в ответ на определённые события. Каждый Workflow состоит из одного или нескольких jobs, которые могут выполняться параллельно. А внутри каждого job есть steps, выполняющиеся последовательно.
Step может быть обычным shell-скриптом или отдельным Action. Последние представляют собой «строительные блоки» GitHub Actions. Они позволяют переиспользовать и комбинировать готовые решения.
Иногда нам нужно написать собственный Action, чтобы реализовать особый сценарий. Например, в моём случае нужно было вычислять Commit Lead Time. У вас это могут быть другие задачи: особая логика управления версиями, загрузка сборок в специфичные хранилища и т.д. Чтобы создать кастомный GitHub Action, мы можем выбрать один из трёх вариантов:
Composite Action — это комбинация нескольких команд и других actions, объединённых в одном месте. Как Compound View, а не Custom View в мире Android-разработки;
Docker Action — это Action, упакованный в Docker-контейнер. В таком случае вы можете выбрать любой язык. Если ваш любимый язык Go, пишите на Go. Здесь главный недостаток в том, что контейнер должен работать на Linux. А значит он не подойдёт, если вам нужно будет что-то запустить на macOS (например, инструменты для iOS);
JavaScript Action — это Action, который запускается в среде Node.js, причём быстрее, чем Docker, потому что Node.js уже работает в раннерах, и не надо разворачивать контейнер. Если вы знакомы с экосистемой Node.js, этот вариант отлично вам подойдёт.
Напишем простейший GHA
Чтобы написать GitHub Action на Kotlin/JS, нужно понимать, как создавать кастомные экшены на обычном JavaScript. Если вы знаете, как писать GitHub Actions на JS, смело переходите к следующему разделу статьи.
Также я добавлю дисклеймер. Я в первую очередь Android-разработчик и большую часть времени работаю с Kotlin/Java. В JavaScript и его экосистеме я не считаю себя экспертом, поэтому в статье могут встречаться вещи, которые покажутся очевидными или даже баянистыми для опытных JS-разработчиков. Прошу отнестись с пониманием: моя цель — помочь другим Android-разработчикам и всем, кто привык к Kotlin, открыть возможность создавать кастомные GitHub Actions с помощью Kotlin/JS.
Нам потребуются знания таких слов, как Nodejs, npm и ncc. Я не буду вдаваться в их подробное описание, лишь кратко перечислю:
Node.js — это среда выполнения JavaScript-кода, которая позволяет запускать его не только в браузере, но и в любом другом окружении;
npm — менеджер пакетов в мире Node.js;
ncc — один из популярных инструментов (бандлеров), который упаковывает JS-код в единый файл.
На схеме ниже изображён GitHub Action на JS, но по сути это обычное приложение, которое работает в среде Node.js.
Точка входа в GHA — файл action.yml. Здесь описываются метаданные Action: имя, описание, входные и выходные данные и т.д.
Напишем простой action.yml:
name: 'Roll a dice'
description: 'Simple Github Action for roll a dice'
inputs:
number-of-sides:
description: 'How many sides the dice has'
required: true
default: '6'
outputs:
concat:
description: 'Result of rolling the dice'
runs:
using: 'node20'
main: 'index.js'Обратите внимание, что мы указали, где будет лежать сам исполняемый файл main: 'index.js'. Это означает, что исполняемый код будет лежать в текущей директории в файле index.js.
Теперь нам нужен Workflow, в рамках которого мы запустим и протестируем наш Action. Здесь стоит обратить внимание, что первым шагом (step) мы вызываем Action actions/checkout@v4. Он нужен, чтобы получить исходный код, в котором и будет написана сама логика экшена. Второй шаг — выполнение нашего экшена uses: ./, потому что action.yml лежит в текущей директории. Третий шаг — вывод результата.
on: [push]
jobs:
roll_the_dice_job:
runs-on: ubuntu-latest
name: Roll the dice
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Roll the dice step
id: roll
uses: ./
with:
number-of-sides: '12'
- name: Show the result step
run: echo "The die rolled at ${{ steps.roll.outputs.result }}"Теперь можно написать сам action в файле index.js.
const core = require('@actions/core');
try {
const sides = core.getInput('number-of-sides');
console.log(`Start rolling a dice with ${sides}!`);
const result = rollDice(sides)
core.setOutput("result", result);
} catch (error) {
core.setFailed(error.message);
}
function rollDice(sides) {
const numberOfSides = parseInt(sides, 10);
...
return Math.floor(Math.random() * numberOfSides) + 1;
}Этот action «кидает кубик» и показывает, какое число выпало. Протестировать наш action можно двумя путями:
запушить код в Github и запустить workflow;
запустить локально через инструмент act (https://nektosact.com/).
Последний штрих — это добавление ncc. Как вы могли заметить, в Node.js много библиотек и все они складываются в папке node_modules. Чтобы не таскать с собой эту кучу файлов, лучше упаковать всё в один исполняемый файл, где будет только то, что надо. Это можно сделать через паккер nnc. Это не единственный инструмент — есть и другие. Например, webpack, о котором мы позже поговорим, но сам GitHub в своей документации рекомендует именно ncc.
Запускаем ncc:
npm i -g @vercel/ncc
ncc build index.js --license licenses.txtИ получаем итоговую схему работы:
Создание простого Kotlin/JS Action
Как нам здесь поможет Kotlin/JS? Всё просто. Kotlin-код может компилироваться под разные платформы или таргеты: в байт-код Java (для JVM), в бинарные файлы под нативные платформы (.so, .a, .framework) и в JavaScript (JS). Благодаря этому мы можем использовать Kotlin для разработки приложения, которое в итоге будет работать в среде Node.js. Т.е. мы пишем на Kotlin, компилятор генерирует JS-код, и всё это запускается на Node.js.
Когда Gradle с плагином Kotlin/JS или Multiplatform скомпилирует наш код, он автоматически сгенерирует JavaScript и сформирует файл package.json, где пропишет все необходимые зависимости npm. Мы получим привычный GitHub Action, написанный на JS.
В Gradle необходимо подключить Kotlin-плагин для JavaScript. Существует два варианта:
kotlin("js").kotlin("multiplatform").
По факту эти подходы не отличаются друг от друга — они оба используют одни и те же модули под капотом. Тем не менее в официальной документации JetBrains рекомендуется использовать именно kotlin("multiplatform"). Видимо, это более гибкий и масштабируемый подход, если в дальнейшем вы будете делать сборку и под JVM, и под Native.
plugins {
kotlin("js") version "2.0.0"
}
или
plugins {
kotlin("multiplatform") version "2.0.0"
}Конфигурируем наш Kotlin плагин. Следующий шаг — конфигурация модуля для компиляции JS-кода. Ниже показано, как это обычно делается в файле build.gradle.kts, если вы используете Kotlin Multiplatform или Kotlin JS.
kotlin {
js(IR) {
nodejs {
binaries.executable()
}
}
sourceSets {
val jsMain by getting {
dependencies { }
}
}
}Здесь мы указываем, что используем IR-бэкенд для Kotlin/JS (это более современный режим компилятора), и настраиваем таргет nodejs, чтобы итоговый код можно было запустить в Node.js.
Файлы action.yml и workflow main.yml при этом не меняются — структура GitHub Action остаётся прежней.
Чтобы использовать любую npm-библиотеку (например, @actions/core) в проекте на Kotlin/JS, мы указываем её в секции зависимостей через метод npm в Gradle. Всё, что вы укажете здесь, будет записано в сгенерированный package.json, а потом скачано в папку node_modules.
В мире GitHub Actions есть официальный набор инструментов GitHub Actions Toolkit, а @actions/core — один из его ключевых пакетов. Он предоставляет функции и утилиты, упрощающие взаимодействие с GitHub Actions: чтение входных параметров (inputs), выставление выходных (outputs), логирование и т.д.
sourceSets {
val jsMain by getting {
dependencies {
implementation(npm("@actions/core", "1.4.0"))
}
}
}Чтобы воспользоваться методами из @actions/core в Kotlin/JS-коде, мы объявляем в отдельном файле внешние функции с помощью аннотации @file:JsModule("@actions/core"). Ключевое слово external указывает на то, что данные функции не реализованы на Kotlin напрямую, а подключаются из внешнего JS-кода.
@file:JsModule("@actions/core")
package com.example.utils.actions
external fun setOutput(name: String, value: Any)
external fun setFailed(message: String)Подключив и описав методы из @actions/core, мы можем приступить к написанию собственного GitHub Action на Kotlin/JS. Используем функции setOutput и setFailed, чтобы работать с результатами и ошибками внутри экшена.
import com.example.utils.actions.*
suspend fun main() {
setOutput("failed", false)
try {
val result = "Custom String! Congratulations!"
setOutput("result", result)
print(result)
} catch (ex: Exception) {
setFailed("Error while performing GHA")
}
}Обратите внимание, что функция main помечена как suspend. Это необязательно, но даёт возможность при необходимости использовать корутины или асинхронные вызовы.
Вызываем ./gradlew build и смотрим, что скомпилировал нам плагин Kotlin Multiplatform. Команда скомпилирует ваш Kotlin-код в JavaScript и добавит все необходимые зависимости в node_modules.
После сборки удобно свести все зависимости и исходный JS-код в один исполняемый файл. Для этого используем ncc. Ниже описаны шаги, как получить итоговый файл через ncc:
найти скомпилированные файлы
./build/js/packages/test-gha-1/kotlin;Выполнить ncc:
ncc build test-gha-1.js --license licenses.txt;Получить результат в:
./build/js/packages/test-gha-1/kotlin/dist;Скопировать оттуда в:
./dist.
Чтобы это не писать руками, можем всё сделать в Gradle-таске:
tasks.register<Exec>("buildAndPackWithInstalledNCC") {
dependsOn("build")
commandLine("npx", "ncc", "build",
"${layout.buildDirectory.get()}/js/packages/${project.name}
/kotlin/${project.name}.js",
"--license", "licenses.txt", "-o", "dist")
}Такой вариант требует предустановки ncc. Для удобства мы можем установить ncc автоматически через Gradle, указав его в разделе devNpm. Тогда Gradle сам добавит утилиту в package.json в разделе devDependencies.
sourceSets {
val jsMain by getting {
dependencies {
implementation(npm("@actions/core", "1.4.0"))
implementation(devNpm("@vercel/ncc", "0.38.1"))
}
}
}Полученный package.json будет выглядеть примерно так:
{
...
"devDependencies": {
"@vercel/ncc": "0.38.1",
"typescript": "5.4.3",
"source-map-support": "0.5.21"
},
"dependencies": { ... },
}Чтобы автоматизировать процесс, создадим две задачи в Gradle: installNodeModules и buildAndInstallAndPackWithNCC. Первая установит нужные пакеты, а вторая скомпилирует KotlinJS-код и запустит ncc:
tasks.register<Exec>("installNodeModules") {
dependsOn("build")
workingDir = file("${layout.buildDirectory.get()}/js/packages/${project.name}/")
commandLine("npm", "install")
}
tasks.register<Exec>("buildAndInstallAndPackWithNCC") {
dependsOn("installNodeModules")
workingDir = file("${layout.buildDirectory.get()}/js/packages/${project.name}/")
commandLine("npx", "ncc", "build", "./kotlin/${project.name}.js", "--license",
"licenses.txt", "-o", "${layout.projectDirectory}/dist")
}Сделаем круче — воспользуемся API NCC
NCC можно использовать как библиотеку и напрямую обращаться к функциям через Kotlin, а не запускать его из командной строки. Для этого создадим отдельный Gradle-модуль, где установим в зависимости @vercel/ncc. Обратите внимание: здесь уже не devNpm, а просто npm.
plugins {
kotlin("multiplatform") version "2.0.0"
}
kotlin {
// all the same...
}
dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.5.0")
implementation("org.jetbrains.kotlinx:kotlinx-nodejs:0.0.7")
implementation("org.jetbrains.kotlin-wrappers:kotlin-js:1.0.0-pre.785")
implementation(npm("@vercel/ncc", "0.38.1", generateExternals = false))
}Опишем внешний интерфейс для библиотеки @vercel/ncc, чтобы вызывать её функции:
@JsModule("@vercel/ncc")
external fun ncc(input: String, options: NccOptions = definedExternally): Promise<NccResult>
external interface NccResult {
val code: String
val map: String?
val assets: AssetMap?
}
external interface NccOptions {
var cache: dynamic
var externals: List<String>
...
}Главный метод ncc возвращает Promise с объектом, содержащим объединённый код, карту исходников (sourceMap) и другие вспомогательные данные.
val nccResult = ncc(
input = inputPath,
options = jsObject {
sourceMap = true
license = "LICENSES"
}
).await()
external interface NccResult {
val code: String
val map: String?
val assets: AssetMap?
}Далее пишем функцию main, где вызываем ncc и обрабатываем его результат:
suspend fun main() {
runCatching {
val (inputPath, outputPath) = readArgs(process.argv)
val combinedCode = combineCode(
inputPath = inputPath,
outputPath = outputPath,
fileName = "index.js"
)
createOutputFolder(outputPath = outputPath)
with(combinedCode) {
copyCode()
copyMapping()
copyAssets()
}
}.onFailure { throwable ->
console.error(throwable)
process.exit(1)
}
}Чтобы всё это запустить, передаём в Gradle-таске jsNodeProductionRun пути к файлам через метод args:
tasks.named<NodeJsExec>("jsNodeProductionRun") {
val inputPath =
"${rootProject.layout.buildDirectory.get()}/js/packages/${rootProject.name}/"
val outputPath = "${rootProject.layout.projectDirectory}/dist/"
args(inputPath, outputPath)
}
И запускаем:
./gradlew build :ncc:jsNodeProductionRunТеперь у нас есть полноценный модуль, который программно вызывает ncc API, комбинирует весь JS-код и зависимости. На схеме это выглядит так:
Webpack
Webpack — это один из наиболее популярных бандлеров JavaScript-приложений. В нашем случае функции Webpack и ncc идентичны. Webpack берёт скомпилированный JS-код, включая все зависимости, и собирает в единый файл.
Однако при использовании ncc я столкнулся с ошибкой, связанной с модулем abort-controller. Ошибка выглядит так:
https://api.github.com/repos/[...]/[...]/git/refs/tags
failed with exception: Error: Cannot find module 'abort-controller' |
Require stack: | -
./dist/index.jsКак оказалось, это известная проблема, на которую есть открытая задача в трекере KTOR-405. Поэтому пока мы вынуждены пользоваться хаком, чтобы устранить эту ошибку вручную.
Ниже показан пример, как можно руками подправить конфиг Webpack, чтобы подменить пути к проблемным пакетам:
private fun WebpackInputParams.toWebpackConfig(): WebpackConfig {
return WebpackConfig(
projectName = name,
inputFilePath = "$buildDir/js/packages/$name/kotlin/$name.js",
outputDirPath = outputDir,
outputFileName = "index.js",
modules = listOf(...),
aliases = mapOf(
"node-fetch$" to "node-fetch/lib/index.js",
"abort-controller$" to "abort-controller/dist/abort-controller.js",
)
)
}
...
if (content.contains("eval('require')")) {
val fixedContent = content.replace("eval('require')", "require")
writeFileSync(path, fixedContent)
}Здесь мы в явном виде переопределяем пути для node-fetch и abort-controller, а также устраняем вызов eval('require'), чтобы всё корректно работало при сборке. Это не самое изящное решение, но что поделать.
Если вы знаете лучший способ обойти эту ошибку, обязательно напишите в комментариях. Буду признателен!
Таким образом, у нас есть как минимум два способа собрать результат в один JS-файл:
./gradlew build :ncc:jsNodeProductionRun;./gradlew build :webpack:jsNodeProductionRun.
Обе команды выполняют одну и ту же задачу, но разными инструментами. Ncc показался мне проще в настройке, однако Webpack смог исправить баг.
Template
В этой статье мы разобрали много мелких деталей. Может показаться, что написать кастомный GitHub Action на Kotlin/JS сложно. Слишком много различных шагов.
Чтобы упростить вам и себе задачу, я подготовил шаблон на GitHub. В этом репозитории уже настроены все необходимые инструменты: плагин, зависимости, сборка в единый файл через ncc и Webpack и так далее. Если захотите что-то доработать или улучшить, смело присылайте Pull Request!
https://github.com/makzimi/kotlin-github-action
Структура main метода шаблона похожа на то, что я описывал в статье:
Читаем входные параметры.
Запускаем основную бизнес-логику.
Устанавливаем результат или ошибку.
suspend fun main() {
val input = buildGHAInput()
try {
group("Action body") {
val output = runAction(input = input)
if (output.success) {
setOutput(Result.value, output.result)
} else {
setFailed(output.errorText.orEmpty())
}
}
} catch (e: Exception) {
setFailed("Error while performing GitHub Action: ${e.message}")
}
}Благодаря этому шаблону вам не придётся возиться с подготовительным кодом. Вы сможете сразу приступить к написанию собственной логики экшена.
Выводы
В GitHub Marketplace действительно много готовых экшенов, но далеко не все из них подойдут именно вам. У меня возник кейс, для которого мне понадобился кастомный GitHub Action.
Docker-вариант на первый взгляд кажется удобнее, особенно если вы не планируете писать на Kotlin.
Но если вы хотите применить Kotlin для CI/CD, то это отличный способ использовать уже знакомый язык на новую задачу. Написание GitHub Action на Kotlin/JS не будет слишком сложной задачей, особенно если пользоваться шаблоном и не писать бойлерплейт-код.
Круто, что Kotlin позволяет компилировать код под разные платформы. Сегодня вы пишете Android-приложение, а завтра точно так же на Kotlin создаёте GitHub Action.
Если у вас остались вопросы или идеи, как улучшить процесс, обязательно делитесь ими в комментариях или открывайте Pull Request к шаблону!
Спасибо, что дочитали статью! Если вам интересен мой опыт, но лень читать большие тексты, подписывайтесь на Telegram-канал «Мобильное чтиво». Там я в формате постов делюсь своими мыслями про Android-разработку и не только.
О том, как мы развиваем IT в Додо в целом, читайте в Telegram-канале Dodo Engineering. Там мы рассказываем о нашей жизни, культуре и последних разработках.
