Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rnett/kotlin-js-action
Kotlin JS SDK for writing GitHub Actions
https://github.com/rnett/kotlin-js-action
actions github-actions kotlin kotlin-js
Last synced: 29 days ago
JSON representation
Kotlin JS SDK for writing GitHub Actions
- Host: GitHub
- URL: https://github.com/rnett/kotlin-js-action
- Owner: rnett
- License: apache-2.0
- Created: 2021-02-13T01:21:37.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2022-11-23T06:27:25.000Z (about 2 years ago)
- Last Synced: 2024-11-21T14:32:12.950Z (about 1 month ago)
- Topics: actions, github-actions, kotlin, kotlin-js
- Language: Kotlin
- Homepage: https://rnett.github.io/kotlin-js-action/
- Size: 8.48 MB
- Stars: 16
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Kotlin JS GitHub Action SDK
[](https://search.maven.org/artifact/com.github.rnett.ktjs-github-action/kotlin-js-action)
[](https://oss.sonatype.org/content/repositories/snapshots/com/github/rnett/ktjs-github-action/)
[](https://github.com/rnett/kotlin-js-action)
[](https://opensource.org/licenses/Apache-2.0)
[](./CHANGELOG.md#changelog)
### Artifacts
* `com.github.rnett.ktjs-github-action:kotlin-js-action` - the SDK
* `com.github.rnett.ktjs-github-action:serialization` - Kotlinx serialization support for the SDK
* `com.github.rnett.ktjs-github-action` - a gradle plugin for building GitHub Actions. The maven artifact
is `com.github.rnett.ktjs-github-action:kotlin-js-action-plugin`
if you are not using the `plugins` block.
Using the IR backend is required.
### [Docs](https://rnett.github.io/kotlin-js-action/release/)
[For latest SNAPSHOT build](https://rnett.github.io/kotlin-js-action/snapshot/)
Kotlin JS utilities for writing GitHub Actions, including wrappers
for [actions/toolkit](https://github.com/actions/toolkit) packages, except for `@actions/github`
and `@actions/tool-cache`. `@actions/tool-cache` will be added once blocking `dukat` bugs are fixes.
## SDK
The GitHub actions SDK provides wrappers for most of the [`actions/toolkit`](https://github.com/actions/toolkit)
packages, as well as some utilities for working with NodeJS types.
Actions should almost always have an entrypoint like:
```kotlin
suspend fun main() = runAction {
}
```
This ensures that any uncaught exceptions are properly reported to the GitHub runtime.
Generally, most of the wrappers are thin and can be fully understood by reading the docs. We explain the more
complicated ones below.
### Utils
Utilities include backpressure cognizant `Flow` <-> `Stream` conversions,
`WritableStream.writeSuspending` (which suspend for backpressure),
`Buffer.asByteArray()`, `jsEntries`, and an `external interface` object builder `JsObject`.
### Inputs, State, and Env
The `inputs`, `state`, and `env` (and `exportEnv`) objects provide action input, state, and environment accessors. They
can all be accessed by key, but also provide delegates. Delegates can delegate from the object directly, specify a name
with `invoke(String)`, or whether the value is required with `optional`/`optional(String)` and `required`
/`required(String)`.
`inputs` and `state` delegates are required by default and the objects have `optional` versions, where `env` is the
opposite.
`exportEnv`/`env.export` is another environment wrapper that exports set environment variables to the GitHub workflow.
### Typesafe delegates
Many objects, including `inputs`, `env`, and `outputs`, are accessed primarily by `String` delegates. However, this is
insufficient when accessing structured data, such as multi-line or boolean inputs or JSON formatted `state`.
To this end, we provide delegate (`ReadOnlyProperty` and `ReadWriteProperty`, to be exact) mapping functions in
the `delegates` package. You can write your own using `map`, `mapNonNull`, `ifNull`, etc, and we provide a large set of
default implementations including `isTrue` (\~`toBoolean` in the stdlib),
`toBoolean` (\~`toBooleanStrict` in the stdlib), `toInt`, `lines`, `trim`, and `lowercase` for both read-only and
read-write delegates.
This is also how serialization support is implemented. The `serialization` artifact provides `deserialize`
and `serialize` methods, so you can do something like `val myState by state.deserialize()`.
### Shell Exec
`exec` is based on the `@actions/exec` package, however it has some issues with input redirection, in particular that
passing `outStream` will cause a `[command] $command` header to be written to the output file. To this end we provide
`execShell` commands that instead of executing the raw command, excuting it using something like `bash -c "$command"`.
Powershell (Windows) or bash are used by default. Note that powershell output redirects (`>`) will be written in
UTF-16-le with a BOM. Command strings passed here support things like `>`, `|`, aliases, and posix-like powershell
commands.
### HttpClient
The `httpclient` package wraps `@actions/http-client`. `HttpClient` provides a lightweight http client, with the
ability to send, `Flow`s and text, and set default and per-request headers. While the typed result methods are provided,
typed requests should usually be handled via `JsonHttpClient` in the `serialization` artifact.
## Gradle Plugin
The gradle plugin (`com.github.rnett.ktjs-github-action`) can Kotlin JS with bundling for GitHub Actions, since the
Kotlin JS plugin doesn't support bundling NodeJS yet.
There are two functions you can call in your build script:
* `com.rnett.action.githubAction`, called in the `js` target block to configure the target for GitHub actions. It
configures a browser target, but with node dependencies in Webpack, and adds a task to generate the custom webpack
config. This replaces `browser` or `nodejs`.
* `com.rnett.action.generateAutoBuildWorkflow`, called anywhere. Generates a GitHub actions workflow for the project to
build and commit the distributable on push, in case it wasn't built locally. This keeps it up to date with your latest
changes. By default, if called with a `Project` receiver, generates it in `$rootDir/.github/workflows/`
## Examples
The [test action](./test-action) and its [metadata file](./.github/actions/test-action/action.yml)
https://github.com/rnett/find-regex
https://github.com/rnett/publish-docs
https://github.com/rnett/import-gpg-key