2019-08-16 13:43:51 +00:00
# `@actions/core`
> Core functions for setting results, logging, registering secrets and exporting variables across actions
## Usage
2020-10-01 14:45:33 +00:00
### Import the package
2019-08-16 13:43:51 +00:00
2020-10-01 14:45:33 +00:00
```js
// javascript
const core = require('@actions/core');
2019-08-16 13:43:51 +00:00
2020-10-01 14:45:33 +00:00
// typescript
import * as core from '@actions/core';
2019-08-16 13:43:51 +00:00
```
2020-10-01 14:45:33 +00:00
#### Inputs/Outputs
2019-08-16 13:43:51 +00:00
2020-10-01 14:45:33 +00:00
Action inputs can be read with `getInput` . Outputs can be set with `setOutput` which makes them available to be mapped into inputs of other actions to ensure they are decoupled.
```js
const myInput = core.getInput('inputName', { required: true });
2019-08-16 13:43:51 +00:00
core.setOutput('outputKey', 'outputVal');
```
2020-10-01 14:45:33 +00:00
#### Exporting variables
2019-08-16 13:43:51 +00:00
2020-10-01 14:45:33 +00:00
Since each step runs in a separate process, you can use `exportVariable` to add it to this step and future steps environment blocks.
2019-08-16 13:43:51 +00:00
2020-10-01 14:45:33 +00:00
```js
core.exportVariable('envVar', 'Val');
2019-08-16 13:43:51 +00:00
```
2020-10-01 14:45:33 +00:00
#### Setting a secret
2019-08-16 13:43:51 +00:00
2020-10-01 14:45:33 +00:00
Setting a secret registers the secret with the runner to ensure it is masked in logs.
```js
core.setSecret('myPassword');
2019-08-16 13:43:51 +00:00
```
#### PATH Manipulation
2020-10-01 14:45:33 +00:00
To make a tool's path available in the path for the remainder of the job (without altering the machine or containers state), use `addPath` . The runner will prepend the path given to the jobs PATH.
2019-08-16 13:43:51 +00:00
2020-10-01 14:45:33 +00:00
```js
core.addPath('/path/to/mytool');
2019-08-16 13:43:51 +00:00
```
#### Exit codes
2020-10-01 14:45:33 +00:00
You should use this library to set the failing exit code for your action. If status is not set and the script runs to completion, that will lead to a success.
2019-08-16 13:43:51 +00:00
2020-10-01 14:45:33 +00:00
```js
2019-08-16 13:43:51 +00:00
const core = require('@actions/core');
try {
// Do stuff
}
catch (err) {
// setFailed logs the message and sets a failing exit code
core.setFailed(`Action failed with error ${err}`);
}
2020-10-01 14:45:33 +00:00
Note that `setNeutral` is not yet implemented in actions V2 but equivalent functionality is being planned.
2019-08-16 13:43:51 +00:00
```
#### Logging
2020-10-01 14:45:33 +00:00
Finally, this library provides some utilities for logging. Note that debug logging is hidden from the logs by default. This behavior can be toggled by enabling the [Step Debug Logs ](../../docs/action-debugging.md#step-debug-logs ).
2019-08-16 13:43:51 +00:00
2020-10-01 14:45:33 +00:00
```js
2019-08-16 13:43:51 +00:00
const core = require('@actions/core');
const myInput = core.getInput('input');
try {
core.debug('Inside try block');
if (!myInput) {
2020-10-01 14:45:33 +00:00
core.warning('myInput was not set');
2019-08-16 13:43:51 +00:00
}
2020-10-01 14:45:33 +00:00
if (core.isDebug()) {
// curl -v https://github.com
} else {
// curl https://github.com
}
2019-08-16 13:43:51 +00:00
// Do stuff
2020-10-01 14:45:33 +00:00
core.info('Output to the actions build log')
2019-08-16 13:43:51 +00:00
}
catch (err) {
2020-10-01 14:45:33 +00:00
core.error(`Error ${err}, action may still succeed though`);
2019-08-16 13:43:51 +00:00
}
```
2020-10-01 14:45:33 +00:00
This library can also wrap chunks of output in foldable groups.
```js
const core = require('@actions/core')
// Manually wrap output
core.startGroup('Do some function')
doSomeFunction()
core.endGroup()
// Wrap an asynchronous function call
const result = await core.group('Do something async', async () => {
const response = await doSomeHTTPRequest()
return response
})
```
#### Action state
You can use this library to save state and get state for sharing information between a given wrapper action:
**action.yml**
```yaml
name: 'Wrapper action sample'
inputs:
name:
default: 'GitHub'
runs:
using: 'node12'
main: 'main.js'
post: 'cleanup.js'
```
In action's `main.js` :
```js
const core = require('@actions/core');
core.saveState("pidToKill", 12345);
```
In action's `cleanup.js` :
```js
const core = require('@actions/core');
var pid = core.getState("pidToKill");
process.kill(pid);
```