pontil

Gleaming GitHub Actions

pontil | ˈpɒntɪl | (punty | ˈpʌnti |) noun
(in glass-making) an iron rod used to hold or shape soft glass.

pontil is a port of actions/toolkit to Gleam, targeting JavaScript targets only, since GitHub Actions run using a Node runtime and the use of Promises requires JavaScript.

Types

AnnotationProperties

</>

Optional properties that can be sent with output annotation commands (notice, error, and warning). See create a check run for more information about annotations.

pub type AnnotationProperties {
  Title(String)
  File(String)
  StartLine(Int)
  EndLine(Int)
  StartColumn(Int)
  EndColumn(Int)
}

Constructors

```
Title(String)
```
A title for the annotation.
```
File(String)
```
The path of the file for which the annotation should be created.
```
StartLine(Int)
```
The start line for the annotation.
```
EndLine(Int)
```
The end line for the annotation. Defaults to StartLine when StartLine is provided.
```
StartColumn(Int)
```
The start column for the annotation. Cannot be sent when StartLine and EndLine are different values.
```
EndColumn(Int)
```
The end column for the annotation. Cannot be sent when StartLine and EndLine are different values. Defaults to StartColumn when StartColumn is provided.

ExitCode

</>

The exit code for an action.

pub type ExitCode {
  Failure
  Success
}

Constructors

```
Failure
```
A code indicating that the action was a failure (1).
```
Success
```
A code indicating that the action was successful (0).

InputOptions

</>

Options for reading input values in an action.

pub type InputOptions {
  InputRequired
  PreserveInputSpaces
}

Constructors

```
InputRequired
```
Whether the input is required. If required and not present, will return an error. Inputs are not required by default.
```
PreserveInputSpaces
```
Whether leading/trailing whitespace will be preserved for the input. Inputs are trimmed by default.

PontilError

</>

Errors returned by pontil functions.

pub type PontilError =
  errors.PontilError

Values

add_path

</>

pub fn add_path(
  input_path: String,
) -> Result(Nil, errors.PontilError)

Prepends input_path to the PATH (for this action and future actions).

debug

</>

pub fn debug(message: String) -> Nil

Writes debug message to user log.

Debug messages are visible in an action runner only when Action Step Debug is enabled.

describe_error

</>

pub fn describe_error(error: errors.PontilError) -> String

Returns a human-readable description of a pontil error.

error_annotation

</>

pub fn error_annotation(
  msg msg: String,
  props props: List(AnnotationProperties),
) -> Nil

Adds an error issue with annotation options.

export_variable

</>

pub fn export_variable(
  name name: String,
  value value: String,
) -> Result(Nil, errors.PontilError)

Sets env variable for this action and future actions in the job.

get_boolean_input

</>

pub fn get_boolean_input(
  name: String,
) -> Result(Bool, errors.PontilError)

Gets the input value of the boolean type in the YAML 1.2 “core schema” specification. Supported boolean values are true, True, TRUE, false, False, or FALSE.

get_boolean_input_opts

</>

pub fn get_boolean_input_opts(
  name name: String,
  opts opts: List(InputOptions),
) -> Result(Bool, errors.PontilError)

Gets the input value of the boolean type in the YAML 1.2 “core schema” specification. Supported boolean values are true, True, TRUE, false, False, or FALSE.

get_id_token

</>

pub fn get_id_token(
  audience: option.Option(String),
) -> promise.Promise(Result(String, errors.PontilError))

Returns a GitHub OIDC token for the provided audience.

get_input

</>

pub fn get_input(name: String) -> String

Gets a GitHub Action input value with default options.

get_input_opts

</>

pub fn get_input_opts(
  name name: String,
  opts opts: List(InputOptions),
) -> Result(String, errors.PontilError)

Gets a GitHub Action input value with provided options.

get_multiline_input

</>

pub fn get_multiline_input(name: String) -> List(String)

Gets the values of a multiline input with default options. Each value is also trimmed.

get_multiline_input_opts

</>

pub fn get_multiline_input_opts(
  name name: String,
  opts opts: List(InputOptions),
) -> Result(List(String), errors.PontilError)

Gets the values of a multiline input with provided options.

get_state

</>

pub fn get_state(name: String) -> String

Gets the value of an state set by this action’s main execution.

See Sending values to the pre and post actions.

group

</>

pub fn group(name name: String, do do: fn() -> a) -> a

Wraps an action function in an output group, returning the same type as the function itself. This variant should not be used with functions returning promises, as the group is likely to be ended before the function executes.

group_async

</>

pub fn group_async(
  name name: String,
  do do: fn() -> promise.Promise(a),
) -> promise.Promise(a)

Wraps an async action function in an output group, returning the same type as the function itself.

group_end

</>

pub fn group_end() -> Nil

End an output group.

This is called endGroup in actions/core.

group_start

</>

pub fn group_start(name: String) -> Nil

Begin an output group.

Output until the next group_end will be foldable in this group.

This is called startGroup in actions/core.

info

</>

pub fn info(message: String) -> Nil

Writes info to log.

is_debug

</>

pub fn is_debug() -> Bool

Gets whether Actions Step Debug is on or not

notice

</>

pub fn notice(message: String) -> Nil

Adds a notice issue.

notice_annotation

</>

pub fn notice_annotation(
  msg msg: String,
  props props: List(AnnotationProperties),
) -> Nil

Adds a notice issue with annotation options.

promise_finally

</>

pub fn promise_finally(
  promise promise: promise.Promise(a),
  do fun: fn() -> b,
) -> promise.Promise(a)

register_default_process_handlers

</>

pub fn register_default_process_handlers() -> Nil

This is the recommended setup for most actions:

pub fn main() {
  pontil.register_default_process_handlers()
  // ...
}

register_process_handlers

</>

pub fn register_process_handlers(
  exception exception_fn: fn(String) -> Nil,
  promise rejection_fn: fn(String) -> Nil,
) -> Nil

Register handlers for uncaughtException and unhandledRejection on the Node.js process. Without these, unhandled errors may cause the action to exit 0 (appearing to succeed).

Call this at the top of main() before starting any async work.

pontil.register_process_handlers(
  exception: pontil.set_failed,
  promise: pontil.set_failed,
)

The rejection or exception will be converted to a string and passed to the appropriate handler function function.

save_state

</>

pub fn save_state(
  name name: String,
  value value: String,
) -> Result(Nil, errors.PontilError)

Saves state for current action, the state can only be retrieved by this action’s post job execution.

See Sending values to the pre and post actions.

set_command_echo

</>

pub fn set_command_echo(enabled: Bool) -> Nil

Enable or disable the echoing of commands into stdout for the rest of the step.

Disabled by default unless Action Step Debug is enabled.

set_exit_code

</>

pub fn set_exit_code(value: ExitCode) -> Nil

Sets the action exit code.

set_failed

</>

pub fn set_failed(message: String) -> Nil

Writes the message as an error to the log and sets the action status to failed.

When the action exits it will have an exit code of 1.

set_output

</>

pub fn set_output(
  name name: String,
  value value: String,
) -> Result(Nil, errors.PontilError)

Sets the value of an output for passing values between steps or jobs.

See Passing job outputs, steps context, and outputs for JavaScript actions.

set_secret

</>

pub fn set_secret(secret: String) -> String

Registers a secret which will get masked from logs

This function instructs the Actions runner to mask the specified value in any logs produced during the workflow run. Once registered, the secret value will be replaced with asterisks (***) whenever it appears in console output, logs, or error messages.

This is useful for protecting sensitive information such as:

API keys
Access tokens
Authentication credentials
URL parameters containing signatures (SAS tokens)

Note that masking only affects future logs; any previous appearances of the secret in logs before calling this function will remain unmasked.

For security purposes, if the environment variable GITHUB_ACTIONS is not "true", the actual secret will not be printed as it is likely that the action is being tested outside of GitHub Actions.

Because Gleam returns the last expression, this function returns the input value so that if it is the last expression in your function that returns a secret value, you may set the secret and return it in one value.

Ok(set_secret("mypassword")) // => Ok("mypassword")

to_platform_path

</>

pub fn to_platform_path(path: String) -> String

to_platform_path converts the given path to a platform-specific path. It does this by replacing instances of / and \\ with the platform-specific path separator.

If possible, prefer using the filepath library.

to_posix_path

</>

pub fn to_posix_path(path: String) -> String

to_posix_path converts the given path to the posix form. On Windows, \\ will be replaced with /.

If possible, prefer using the filepath library.

to_win32_path

</>

pub fn to_win32_path(path: String) -> String

to_win32_path converts the given path to the win32 form. On Linux, / will be replaced with \\.

If possible, prefer using the filepath library.

try_promise

</>

pub fn try_promise(
  result result: Result(a, e),
  next next: fn(a) -> promise.Promise(Result(b, e)),
) -> promise.Promise(Result(b, e))

Lift a synchronous Result into a Promise chain.

This is glue between sync operations (reading env vars, parsing input) and async pipelines. On Ok, the next function is called. On Error, the error is wrapped in a resolved Promise.

fn run() -> Promise(Result(Nil, PontilError)) {
  use token <- pontil.try_promise(get_token())
  use resp <- promise.try_await(fetch_data(token))
  promise.resolve(Ok(Nil))
}

warning

</>

pub fn warning(message: String) -> Nil

Adds a warning issue

warning_annotation

</>

pub fn warning_annotation(
  msg msg: String,
  props props: List(AnnotationProperties),
) -> Nil

Adds a warning issue with annotation options.