What is @actions/core?
The @actions/core package provides a set of core functions for GitHub Actions users to help manage inputs, outputs, and other features within their GitHub Actions workflows. It simplifies the process of coding actions by offering utility functions for common tasks.
What are @actions/core's main functionalities?
Getting action inputs
This feature allows you to easily retrieve inputs defined in your action's YAML file. The example code demonstrates how to get an input with the name 'inputName', marking it as required.
const input = core.getInput('inputName', { required: true });
Setting action outputs
Enables you to set outputs for your action, which can be used by other steps in your workflow. The code sample shows how to set an output with a key of 'outputKey' and a value of 'outputValue'.
core.setOutput('outputKey', 'outputValue');
Logging
Provides various logging functions to help debug or provide information during the execution of your action. The code demonstrates how to log an information message, a warning message, and an error message.
core.info('Information message');
core.warning('Warning message');
core.error('Error message');
Setting environment variables
Allows you to set environment variables that will be available to subsequent steps in your workflow. The example code sets an environment variable named 'VAR_NAME' with a value of 'value'.
core.exportVariable('VAR_NAME', 'value');
Setting a secret
This function registers a value as a secret, which masks the value from logs. The code sample demonstrates how to mask 'secretValue' from GitHub Actions logs.
core.setSecret('secretValue');
Other packages similar to @actions/core
@actions/github
While @actions/core provides general utilities for GitHub Actions, @actions/github offers GitHub-specific functionalities, such as interacting with GitHub API directly from your actions. It complements @actions/core by providing a higher level of GitHub integration.
@actions/exec
This package is designed to execute system commands within GitHub Actions. It's similar to @actions/core in that it provides utility functions for actions, but focuses on command execution, allowing you to run shell commands, capture output, and handle errors.
@actions/io
Offers utilities for file system operations, such as moving, copying, and deleting files or directories within GitHub Actions. It's a complementary package to @actions/core, focusing on file and directory manipulation tasks.
@actions/core
Core functions for setting results, logging, registering secrets and exporting variables across actions
Usage
Import the package
const core = require('@actions/core');
import * as core from '@actions/core';
Inputs/Outputs
Action inputs can be read with getInput
which returns a string
or getBooleanInput
which parses a boolean based on the yaml 1.2 specification. If required
set to be false, the input should have a default value in action.yml
.
Outputs can be set with setOutput
which makes them available to be mapped into inputs of other actions to ensure they are decoupled.
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');
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.
core.exportVariable('envVar', 'Val');
Setting a secret
Setting a secret registers the secret with the runner to ensure it is masked in logs.
core.setSecret('myPassword');
PATH Manipulation
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.
core.addPath('/path/to/mytool');
Exit codes
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.
const core = require('@actions/core');
try {
}
catch (err) {
core.setFailed(`Action failed with error ${err}`);
}
Note that setNeutral
is not yet implemented in actions V2 but equivalent functionality is being planned.
Logging
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.
const core = require('@actions/core');
const myInput = core.getInput('input');
try {
core.debug('Inside try block');
if (!myInput) {
core.warning('myInput was not set');
}
if (core.isDebug()) {
} else {
}
core.info('Output to the actions build log')
}
catch (err) {
core.error(`Error ${err}, action may still succeed though`);
}
This library can also wrap chunks of output in foldable groups.
const core = require('@actions/core')
core.startGroup('Do some function')
doSomeFunction()
core.endGroup()
const result = await core.group('Do something async', async () => {
const response = await doSomeHTTPRequest()
return response
})
Styling output
Colored output is supported in the Action logs via standard ANSI escape codes. 3/4 bit, 8 bit and 24 bit colors are all supported.
Foreground colors:
core.info('\u001b[35mThis foreground will be magenta')
core.info('\u001b[38;5;6mThis foreground will be cyan')
core.info('\u001b[38;2;255;0;0mThis foreground will be bright red')
Background colors:
core.info('\u001b[43mThis background will be yellow');
core.info('\u001b[48;5;6mThis background will be cyan')
core.info('\u001b[48;2;255;0;0mThis background will be bright red')
Special styles:
core.info('\u001b[1mBold text')
core.info('\u001b[3mItalic text')
core.info('\u001b[4mUnderlined text')
ANSI escape codes can be combined with one another:
core.info('\u001b[31;46mRed foreground with a cyan background and \u001b[1mbold text at the end');
Note: Escape codes reset at the start of each line
core.info('\u001b[35mThis foreground will be magenta')
core.info('This foreground will reset to the default')
Manually typing escape codes can be a little difficult, but you can use third party modules such as ansi-styles.
const style = require('ansi-styles');
core.info(style.color.ansi16m.hex('#abcdef') + 'Hello world!')
Action state
You can use this library to save state and get state for sharing information between a given wrapper action:
action.yml:
name: 'Wrapper action sample'
inputs:
name:
default: 'GitHub'
runs:
using: 'node12'
main: 'main.js'
post: 'cleanup.js'
In action's main.js
:
const core = require('@actions/core');
core.saveState("pidToKill", 12345);
In action's cleanup.js
:
const core = require('@actions/core');
var pid = core.getState("pidToKill");
process.kill(pid);