Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

core: Rewrite the README.md I/O section #1821

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+35 −8
Open

core: Rewrite the README.md I/O section #1821

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 35 additions & 8 deletions packages/core/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,19 +14,46 @@ const core = require('@actions/core');
import * as core from '@actions/core';
```

#### Inputs/Outputs
#### Inputs

Action inputs can be read with `getInput` which returns a `string` or `getBooleanInput` which parses a boolean based on the [yaml 1.2 specification](https://yaml.org/spec/1.2/spec.html#id2804923). If `required` set to be false, the input should have a default value in `action.yml`.
There are three functions to parse an action's input from the `INPUT_*` environment variables:

Outputs can be set with `setOutput` which makes them available to be mapped into inputs of other actions to ensure they are decoupled.
- **`getInput(name: string, options?: InputOptions): string`**
- Returns the input value as a string.

- **`getBooleanInput(name: string, options?: InputOptions): boolean`**
- Parses the input value as a boolean, following the YAML 1.2 specification.

- **`getMultilineInput(name: string, options?: InputOptions): string[]`**
- Parses the input value as an array of non-blank lines.

> **Note:** Input names are always converted to uppercase, with any spaces replaced by underscores, when matching `INPUT_*` environment variables.

**InputOptions:**

- **`required`**: If set to `false` and the input environment variable is not set, these functions will throw an error. To prevent this, `action.yml` should define a default value.
- **`trimWhitespace`**: If set to `true`, `getInput()` and `getMultilineInput()` will trim whitespace from the returned values, and `getBooleanInput()` will trim whitespace before parsing the value.

```js
const myInput = core.getInput('inputName', { required: true });
const myBooleanInput = core.getBooleanInput('booleanInputName', { required: true });
const myMultilineInput = core.getMultilineInput('multilineInputName', { required: true });
core.setOutput('outputKey', 'outputVal');
const myInput = core.getInput('inputName', { required: true })
const myBooleanInput = core.getBooleanInput('booleanInputName')
const myMultilineInput = core.getMultilineInput('multilineInputName', { trimWhitespace: true })
```

#### Outputs

To set outputs for downstream actions, use:

- **`setOutput(name: string, value: any): void`**
- Any data passed to this function will be available in the [`steps`][steps-context] context as `steps['<step_id>'].outputs['<output_name>']`, ensuring decoupling between actions.
Non-string values will be serialized to JSON.

```js
core.setOutput('outputKey', 'outputVal')
```

[steps-context]: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#steps-context

#### Exporting variables

Since each step runs in a separate process, you can use `exportVariable` to add it to this step and future steps environment blocks.
Expand Down Expand Up @@ -483,4 +510,4 @@ core.summary.emptyBuffer()

// Writes text in the buffer to the summary buffer file and empties the buffer, optionally overwriting all existing content in the summary file with buffer contents. Defaults to false.
core.summary.write({overwrite: true})
```
```