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
  Exit(Int)
}

Constructors

```
Failure
```
A code indicating that the action was a failure (1).
```
Success
```
A code indicating that the action was successful (0).
```
Exit(Int)
```
An exit code option for more complex values. This should not be used when using pontil to write GitHub actions, but may be used when using pontil to write command-line utilities.

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 {
  CoreError(error: core.PontilCoreError)
  FetchError(error: fetch.FetchError)
  OidcTokenMissing
}

Constructors

```
CoreError(error: core.PontilCoreError)
```
An error raised from pontil/core.
```
FetchError(error: fetch.FetchError)
```
A fetch (HTTP) operation failed.
```
OidcTokenMissing
```
The OIDC token response did not contain a token value.

Values

action_mode

</>

pub fn action_mode() -> core.OutputMode

The default mode that emits GitHub Actions workflow commands.

{actions}

add_path

</>

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

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

{portable}

ansi_mode

</>

pub fn ansi_mode() -> core.OutputMode

An ANSI-colored mode for terminal output.

{portable}

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.

{portable}

describe_error

</>

pub fn describe_error(error: PontilError) -> String

Returns a human-readable description of a pontil error.

{portable}

env_get_nonempty

</>

pub fn env_get_nonempty(name: String) -> option.Option(String)

Returns the value of an environment variable if it is set and non-empty.

{portable}

error_annotation

</>

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

Adds an error issue with annotation options.

{portable}

export_variable

</>

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

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

{portable}

get_boolean_input

</>

pub fn get_boolean_input(
  name: String,
) -> Result(Bool, 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.

{actions}

get_boolean_input_opts

</>

pub fn get_boolean_input_opts(
  name name: String,
  opts opts: List(InputOptions),
) -> Result(Bool, 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.

{actions}

get_id_token

</>

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

Returns a GitHub OIDC token for the provided audience.

{actions}

get_input

</>

pub fn get_input(name: String) -> String

Gets a GitHub Action input value with default options.

{actions}

get_input_opts

</>

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

Gets a GitHub Action input value with provided options.

{actions}

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.

{actions}

get_multiline_input_opts

</>

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

Gets the values of a multiline input with provided options.

{actions}

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.

{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.

{portable}

group_async

</>

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

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

{portable}

group_end

</>

pub fn group_end() -> Nil

End an output group.

This is called endGroup in actions/core.

{portable}

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.

{portable}

in_actions

</>

pub fn in_actions() -> Bool

Return True if running inside of a GitHub Actions runner.

{portable}

info

</>

pub fn info(message: String) -> Nil

Writes info to log.

{portable}

is_debug

</>

pub fn is_debug() -> Bool

Gets whether Actions Step Debug is on or not

{actions}

mask_secrets

</>

pub fn mask_secrets(text: String) -> String

Replaces all registered secret values in the given text with ***.

{portable}

notice

</>

pub fn notice(message: String) -> Nil

Adds a notice issue.

{portable}

notice_annotation

</>

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

Adds a notice issue with annotation options.

{portable}

plaintext_mode

</>

pub fn plaintext_mode() -> core.OutputMode

A plaintext mode that formats output as readable text without workflow command syntax.

{portable}

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()
  // ...
}

{portable}

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.

{portable}

save_state

</>

pub fn save_state(
  name name: String,
  value value: String,
) -> Result(Nil, 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.

{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.

{actions}

set_exit_code

</>

pub fn set_exit_code(value: ExitCode) -> Nil

Sets the action exit code.

{portable}

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.

{portable}

set_output

</>

pub fn set_output(
  name name: String,
  value value: String,
) -> Result(Nil, 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.

{actions}

set_output_mode

</>

pub fn set_output_mode(mode: core.OutputMode) -> Nil

Sets the OutputMode for a program using pontil/core.

If not specified, the default is the GitHub Actions output mode. The output mode may be changed at any time. It is recommended that this be selected as early possible.

{portable}

set_secret

</>

pub fn set_secret(secret: String) -> String

Registers a secret which will be masked from logs.

Returns the input value so it can be used as the last expression in a pipeline:

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

In a GitHub Actions runner, a command is emitted 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.

Outside of GitHub Actions, secrets may be masked with mask_secrets.

{portable}

set_secrets

</>

pub fn set_secrets(values: List(String)) -> List(String)

Registers multiple secrets which will be masked from logs. See set_secret for more details.

Returns the input values.

{portable}

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.

{portable}

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.

{portable}

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.

{portable}

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))

Deprecated: Use try_sync instead

try_sync

</>

pub fn try_sync(
  result value: 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_sync(get_token())
  use resp <- promise.try_await(fetch_data(token))
  promise.resolve(Ok(Nil))
}

{portable}

warning

</>

pub fn warning(message: String) -> Nil

Adds a warning issue

{portable}

warning_annotation

</>

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

Adds a warning issue with annotation options.

{portable}