Actions¶
This plugin provides common functions that can be used on any execution environment.
They cover the following areas:
git
commands- files commands
- inception commands
The functions have an actions
category prefix.
Functions¶
actions/checkout@v2¶
Checkout a repository at a particular version.
checkout
functions have a mandatory repository
input:
- uses: actions/checkout@v2
with:
repository: https://github.com/robotframework/RobotDemo.git
They also allow for two optional inputs:
ref
, which is the git reference to checkout: a branch name, a tag name, or a commit SHA (defaults to the default branch if unspecified). You must provide a complete commit SHA (40 characters).path
, which is where to clone/checkout the repository, relative to the current workspace.
- uses: actions/checkout@v2
with:
repository: https://github.com/robotframework/RobotDemo.git
ref: dev
path: foo/bar
Inputs¶
The function has the following inputs:
-
repository
(required)the repository to clone
-
ref
(optional)the branch, tag, or SHA to checkout
-
path
(optional)where to clone the repository
actions/checkout@v3¶
Checkout a repository at a particular version. Compared to actions/checkout@v2
,
actions/checkout@v3
allows additionally to indicate the number of commits to fetch.
checkout
functions have a mandatory repository
input:
- uses: actions/checkout@v3
with:
repository: https://github.com/robotframework/RobotDemo.git
They also allow for three optional inputs:
ref
, which is the git reference to checkout: a branch name, a tag name, or a commit SHA (defaults to the default branch if unspecified). You must provide a complete commit SHA (40 characters).path
, which is where to clone/checkout the repository, relative to the current workspace.fetch-depth
, which indicates the number of commits to fetch. Default value of thefetch-depth
is1
. To fetch all history, set value to0
.
If the git reference to checkout is a commit SHA, you must ensure that
a correct fetch-depth
value is used to fetch the commit, or set it to 0
.
When the ref
parameter is unspecified, history is fetched for all the
branches at a given depth (1 by default).
Inputs¶
The function has the following inputs:
-
repository
(required)the repository to clone
-
ref
(optional)the branch, tag, or SHA to checkout
-
path
(optional)where to clone the repository
-
fetch-depth
(optional)number of commits to fetch
Examples¶
In this example, only two last commits on dev
branch are fetched
into foo/bar
.
- uses: actions/checkout@v3
with:
repository: https://github.com/robotframework/RobotDemo.git
ref: dev
path: foo/bar
fetch-depth: 2
In this example, only the last commit on v22.1
branch is fetched.
- uses: actions/checkout@v3
with:
repository: https://github.com/robotframework/RobotDemo.git
ref: v22.1
actions/create-file@v1¶
Create a file on the execution environment.
Inputs¶
The function has the following inputs:
-
data
(required)the file content
-
format
(required)the file format, one of
ini
,json
,txt
, oryaml
-
path
(required)the file location, relative to the current workspace
Example¶
- uses: actions/create-file@v1
with:
data:
foo:
key1: value1
key2: value2
bar:
key1: value1
key2: value2
format: ini
path: foobar.ini
This will create a foobar.ini
file with the following content:
[foo]
key1=value1
key2=value2
[bar]
key1=value1
key2=value2
actions/put-file@v1¶
Put an existing file on the execution environment.
Inputs¶
The function has the following inputs:
-
file
(required)the file to upload, which must be an entry in the
resources.files
part of the workflow -
path
(required)the file destination, relative to the current workspace
Examples¶
Put a file in the current directory in an execution environment:
- uses: actions/put-file@v1
with:
file: file-to-put
path: destination-path
If you need to put a file somewhere other than the current directory,
use the working-directory
statement:
- uses: actions/put-file@v1
with:
file: file-to-put
path: destination-path
working-directory: /foo/bar
If you want to put a file in the execution environment from a workflow, the file must be declared as a workflow resource:
metadata:
name: put-file example
resources:
files:
- foo.json
jobs:
keyword-driven:
runs-on: ssh
steps:
- uses: actions/put-file@v1
with:
file: foo.json
path: bar/baz.json
working-directory: /qux/quux/corge
This example can be run with the following cURL
command:
curl -X POST \
-F workflow=@{my-workflow.yaml} \
-F foo.json=@foo.json \
-H "Authorization: Bearer {my-token}" \
http://example.com/workflows
If the referred file is not part of the resources
section of your workflow file,
the step will fail with an error code 2.
actions/touch-file@v1¶
Ensure a file exists on the execution environment.
If the file does not exist, it will be created (with an empty content).
Inputs¶
The function has the following inputs:
-
path
(required)the file location, relative to the current workspace
Example¶
- uses: actions/touch-file@v1
with:
path: foobar.ini
actions/delete-file@v1¶
Delete a file on the execution environment.
Inputs¶
The function has the following inputs:
-
path
(required)the file location, relative to the current workspace
Example¶
- uses: actions/delete-file@v1
with:
path: foobar.ini
actions/create-archive@v1¶
Create an archive from a set of selected files or directories on the execution environment.
create-archive
functions create an archive from selected files or directories.
They have mandatory path
and patterns
inputs.
If no files or directories match the specified patterns, an error message is issued, no archive is created, and the workflow is stopped. This is the default behavior.
An optional warn-if-not-found
input can be specified.
Instead of the default behavior, if the specified patterns do not match any files,
a warning message is issued, an archive containing an empty file intentionnally_empty_archive
is created, and the workflow continues.
An optional format
input may be specified.
Possible archive formats are tar
or tar.gz
. Default format is tar.gz
.
Inputs¶
The function has the following inputs:
-
path
(required)The archive name, relative to the current working directory.
-
patterns
(required)A list of directory or file name patterns, possibly with paths. They may contain placeholders (
*
or**
). The*
character in a subdirectory is not supported in Windows environment. -
format
(optional)The archive format, either
tar
ortar.gz
if specified, defaulting totar.gz
if not specified. -
warn-if-not-found
(optional)A message to display when no files matching one of the patterns are found. If specified, enables the generation of an empty archive. May also be set to
true
, in this case, the default warning message is logged.
Examples¶
- uses: actions/create-archive@v1
with:
path: myarchive.tar.gz
patterns:
- 'screenshots/*.svg'
- bar/
- foo.html
- '*.png'
If you want to specify a tar
format to create the archive instead the tar.gz
default format,
use the format
input:
- uses: actions/create-archive@v1
with:
path: myarchive.tar
format: tar
patterns:
- 'data/foo/screenshots/*.svg'
- data/foo/bar/
- data/foo/foo.html
- 'data/foo/*.png'
If you need to archive files that are not in the current directory,
use the working-directory
statement:
- uses: actions/create-archive@v1
with:
path: myarchive.tar.gz
format: tar.gz
patterns:
- 'screenshots/*.svg'
- bar/
- foo.html
- '*.png'
working-directory: /data/foo
If you want to archive files recursively in a folder tree, use the
**/*.ext
pattern format:
- uses: actions/create-archive@v1
with:
path: myarchive.tar.gz
patterns:
- '**/*.png'
- 'screenshots/*.svg'
- bar/
- foo.html
If you want to display a warning message when no files matching one of the patterns are found,
use the warn-if-not-found
input. This allows to create an empty archive:
- uses: actions/create-archive@v1
with:
path: myarchive.tar.gz
patterns:
- 'screenshots/*.svg'
- bar/
- foo.html
- '*.png'
warn-if-not-found: "No files to archive found, an empty archive will be created."
If you want to create an empty archive and to display a default warning message
when no files matching one of the patterns are found, set the warn-if-not-found
input to true
.
- uses: actions/create-archive@v1
with:
path: myarchive.tar.gz
patterns:
- 'screenshots/*.svg'
- bar/
- foo.html
- '*.png'
warn-if-not-found: true
If you want to archive all present files and subfolders recursively in the working-directory
/data/foo
, use the **/*
pattern format:
- uses: actions/create-archive@v1
with:
path: myarchive.tar.gz
patterns:
- '**/*'
working-directory: /data/foo
actions/get-file@v1¶
Attach a file from the execution environment.
get-file
functions attach the specified file so that publisher
plugins can process them. They have mandatory path
input and
an optional type
input.
Inputs¶
The function has the following inputs:
-
path
(required)the file to attach
-
type
(optional)the file type (a media type such as
application/xml
)
Examples¶
- uses: actions/get-file@v1
with:
path: 'foo.xml'
It is a good practice to specify the attachment type, if known:
- uses: actions/get-file@v1
with:
path: 'foobar.xml'
type: 'application/xml'
If you need to get files that are not in the current directory,
use the working-directory
statement:
- uses: actions/get-file@v1
with:
path: 'bar.json'
working-directory: /data/foo
actions/get-files@v1¶
Attach a set of files from the execution environment.
get-files
functions attach the matching files so that publisher
plugins can process them. They have mandatory pattern
input.
An optional type
input may be specified. It is expected to be
a media type.
An optional warn-if-not-found
input may be specified. A warning
will be issued if no file matching pattern is found.
Inputs¶
The function has the following inputs:
-
pattern
(required)the pattern that identifies the files to attach
-
type
(optional)the file type (a media type such as
application/xml
) -
warn-if-not-found
(optional)the warning to display if no matching file is found
Examples¶
- uses: actions/get-files@v1
with:
pattern: '*.xml'
It is a good practice to specify the attachment type, if known. Please note that all matching files will be decorated with the specified type:
- uses: actions/get-files@v1
with:
pattern: '*.xml'
type: 'application/xml'
If you want to get files recursively in a folder tree, use the
**/*.ext
pattern format:
- uses: actions/get-files@v1
with:
pattern: '**/*.html'
working-directory: /data/foo
If you need to get files that are not in the current directory,
use the working-directory
statement:
- uses: actions/get-files@v1
with:
pattern: '*.json'
working-directory: /data/foo
actions/prepare-inception@v1¶
Preload the inception environment with data.
A common use case is to prepare test execution results. Provider plugins typically document the artifacts they generate. Please refer to their documentation for more information.
Inputs¶
The function has the following inputs:
-
{pattern}
(optional)the pattern that identifies the files to attach
Example¶
- uses: actions/prepare-inception@v1
with:
export.xml: ${{ resources.files.export }}
report.html: ${{ resources.files.report }}