Creating and working with action.yml

Creating and working with action.yml

GitHub actions, irrespective of the chosen environment, require a metadata file, which contains information such as title, description, author, etc., and also defines the inputs, outputs and entry-point for the action. GitHub uses this file to understand that the information contained identifies an action.

Action metadata files use the YAML syntax, identified by a .yml or .yaml extension. The action metadata file is named action.yml. If you're new to YAML, you can read more here.

Action Metadata

Meta Info

The action.yml relies on seven metas, some of which are required, and others optional, as shown below:

MetaDescription
name *The name of your action. GitHub displays the name in the actions workflow run log and in the actions marketplace.
authorThe name of the action's author.
descriptionA short description of the action.
inputsInput parameters allow you to specify data that the action expects during runtime. These are stored as environment variables. It is recommended to use lowercase input ids (Uppercase is automatically converted to lowercase).
outputsOutput parameters allow you to declare data that an action produces. For actions that run in succession, the output data of one action can in turn be used as input for the next action.
runs *Configures the path to the action's code and the application used to execute the code.
branding *You can use a color and Feather icon to create a badge to personalize and distinguish your action. Badges are shown next to your action name in the GitHub Marketplace.

* Required Field

The inputs, outputs, runs and branding meta contains multiple parameters each, and hence requires an exploration in-depth, which we will learn below.


inputs

Inputs Args

Input parameters allow you to specify data that the action expects to use during runtime. These are stored as environment variables. It is recommended to use lowercase input ids (Uppercase variables are automatically converted to lowercase).

There are four input parameters that an action permits, as shown below:

MetaTypeDescription
inputs.<id> *stringUnique identifier within the inputs object. The value of is a map of the input's metadata. It must start with a letter or _ and contain only alphanumeric characters, -, or _.
inputs.<id>.description *stringDescription of the input parameter.
inputs.<id>.required *booleanIndicates if the action requires the input parameter. true if the parameter is required.
inputs.<id>.defaultstringRepresents a default value. It is used when an input parameter isn't specified in a workflow file.

* Required Field


outputs

Output Args

Output parameters allow you to declare data that an action produces as output. For actions that run in succession, the output data of one action can in turn be used as input for the next action.

There are two output parameters that an action permits, as shown below:

MetaTypeDescription
outputs.<id> *stringUnique identifier within the outputs object. The value of <id> is a map of the outputs’s metadata. It must start with a letter or _ and contain only alphanumeric characters, -, or _.
outputs.<id>.description *stringDescription of the output parameter.

* Required Field


runs

Configures the path to the action's code and the application used to execute the code. The runs meta contains a separate set of parameters which is environment-specific. These are discussed environment-wise as below:

JavaScript Action

JSArgs

The runs meta for a JavaScript action, contains six parameters as detailed below:

MetaDescription
using *The application used to execute the code specified in main.
main *The file containing the action code.
preRun a script at the start of a job before main: begins, such as a prerequisite setup script. Always runs by default, but can be overridden using pre-if
pre-ifDefine conditions for pre:, which will only run if the conditions in pre-if are met. If not set, then pre-if defaults to always().
postRun a script at the end of a job after main: has completed. For example, you can use post: to terminate certain processes or remove unneeded files.
post-ifDefine conditions for post: execution, which will only run if the conditions in post-if are met. If not set, then post-if defaults to always().

* Required Field

Docker Action

DockerArgs

The runs meta for a Docker actions, contains seven parameters as detailed below:

MetaDescription
using *You must set this value to 'docker'.
pre-entrypointRun a script before the entrypoint action begins. For example, you can use pre-entrypoint: to run a prerequisite setup script. Always runs by default but can be overridden using pre-if.
pre-ifDefine conditions for pre-entrypoint:, which will only run if the conditions in pre-if are met. If not set, then pre-if defaults to always().
image *The Docker image to use as the container to run the action. Can be Docker base image name, a local Dockerfile, or public image in Docker Hub or another registry. To reference local Dockerfile, use a relative path to your action metadata file.
envKey/value map of environment variables to set in the container environment.
entrypointUsed when Dockerfile does not specify ENTRYPOINT or you want to override the ENTRYPOINT
post-entrypointRun scripts after entrypoint action is complete. For example, cleanup scripts. This runs by default but can be overridden using post-if.
post-ifDefine conditions for post: execution, which will only run if the conditions in post-if are met. If not set, then post-if defaults to always().
argsArray of strings that define the inputs for a Docker container, which can include hardcoded strings. GitHub passes the args to the container's ENTRYPOINT when the container starts up.

* Required Field


branding

Branding

The branding meta contains two parameters, both of which are required if you are publishing to a marketplace, otherwise are optional. They are as below:

MetaDescription
colorBackground color of the badge. Can be: white, yellow, blue, green, orange, red, purple, or gray-dark.
iconThe name of the icon to use. Refer Feather Icons for names.

* Required Field

haya14busa has created a GitHub Actions Branding Cheat sheet which you can use to find icon & color for your GitHub action


We will learn about Creating Github Actions Using Javascript in the next blog

Do stay tuned.