pontil/core

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/core is a port of core functionality from the GitHub actions/toolkit to Gleam. This targets both JavaScript and the BEAM. This library is primarily intended to be used by a higher-level API surface and its use directly is discouraged.

Functions in pontil/core are marked with {actions} or {portable} tags. Functions tagged {actions} only work meaningfully in a GitHub Actions environment (they depend on variables set by GitHub Actions runners and/or output to files managed by runners). Functions tagged {portable} may be used in any environment, although output configuration may be required (see set_output_mode) and they may perform additional work in a GitHub Actions runner.

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.

This type is part of the public API for pontil.

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

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.

OutputMode

</>

The output mode that determines how {portable} functions format their output.

pub type OutputMode {
  OutputMode(
    debug: fn(String) -> Nil,
    info: fn(String) -> Nil,
    warning: fn(String, List(AnnotationProperties)) -> Nil,
    error: fn(String, List(AnnotationProperties)) -> Nil,
    notice: fn(String, List(AnnotationProperties)) -> Nil,
    group_start: fn(String) -> Nil,
    group_end: fn() -> Nil,
  )
}

Constructors

OutputMode(
  debug: fn(String) -> Nil,
  info: fn(String) -> Nil,
  warning: fn(String, List(AnnotationProperties)) -> Nil,
  error: fn(String, List(AnnotationProperties)) -> Nil,
  notice: fn(String, List(AnnotationProperties)) -> Nil,
  group_start: fn(String) -> Nil,
  group_end: fn() -> Nil,
)

PontilCoreError

</>

Errors returned by pontil_core functions.

This type is part of the public API for pontil.

pub type PontilCoreError {
  FileError(error: simplifile.FileError)
  FileNotFound(path: String)
  MissingRequiredInput(name: String)
  InvalidBooleanInput(name: String)
  MissingEnvVar(name: String)
}

Constructors

```
FileError(error: simplifile.FileError)
```
A file system operation failed.
```
FileNotFound(path: String)
```
A file expected at the given path does not exist.
```
MissingRequiredInput(name: String)
```
A required input was not supplied.
```
InvalidBooleanInput(name: String)
```
An input value does not meet the YAML 1.2 “Core Schema” boolean specification.
```
MissingEnvVar(name: String)
```
A required environment variable is missing or empty.

Values

action_mode

</>

pub fn action_mode() -> OutputMode

The default mode that emits GitHub Actions workflow commands.

{actions}

add_path

</>

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

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

{portable}

ansi_mode

</>

pub fn ansi_mode() -> OutputMode

An ANSI-colored mode for terminal output.

{portable}

debug

</>

pub fn debug(message: String) -> Nil

Writes debug message to user log.

{portable}

describe_error

</>

pub fn describe_error(error: PontilCoreError) -> String

Returns a human-readable description of a pontil/core 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

</>

pub fn error(message: String) -> Nil

Adds an error issue.

{portable}

error_annotation

</>

pub fn error_annotation(
  msg message: 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, PontilCoreError)

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

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

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_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, PontilCoreError)

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

Gets the values of a multiline input with provided options.

{actions}

get_state

</>

pub fn get_state(name: String) -> String

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

{actions}

group

</>

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

Wraps an action function in an output group.

{portable}

group_end

</>

pub fn group_end() -> Nil

End an output group.

{portable}

group_start

</>

pub fn group_start(name: String) -> Nil

Begin an output group.

{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 message: String,
  props props: List(AnnotationProperties),
) -> Nil

Adds a notice issue with annotation options.

{portable}

plaintext_mode

</>

pub fn plaintext_mode() -> OutputMode

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

{portable}

save_state

</>

pub fn save_state(
  name name: String,
  value value: String,
) -> Result(Nil, PontilCoreError)

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

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

{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 and sets the action status to failed.

{portable}

set_output

</>

pub fn set_output(
  name name: String,
  value value: String,
) -> Result(Nil, PontilCoreError)

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

{actions}

set_output_mode

</>

pub fn set_output_mode(mode: 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(value: 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")

{portable}

set_secrets

</>

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

Registers multiple secrets which will be masked from logs.

Returns the input values.

{portable}

to_platform_path

</>

pub fn to_platform_path(path: String) -> String

Converts the given path to the platform-specific form.

{portable}

to_posix_path

</>

pub fn to_posix_path(path: String) -> String

Converts the given path to posix form (\\ → /).

{portable}

to_win32_path

</>

pub fn to_win32_path(path: String) -> String

Converts the given path to win32 form (/ → \\).

{portable}

warning

</>

pub fn warning(message: String) -> Nil

Adds a warning issue.

{portable}

warning_annotation

</>

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

Adds a warning issue with annotation options.

{portable}