create-custom-github-action.md

GitHub Actions is a powerful feature that empowers you to go from code to cloud all from the comfort and convenience of your own repository. Here, you'll learn about the different types of GitHub actions and the metadata, syntax, and workflow commands to create custom GitHub actions.

Types of GitHub actions

:::image type="content" source="../media/action-types.png" alt-text="Image that displays the three types of GitHub Actions; Docker, JavaScript, and composite run step actions." border="false":::

Actions are individual tasks that you can use to customize your development workflows. You can create your own actions by writing custom code that interacts with your repository to perform custom tasks or by using actions shared by the GitHub community. Navigating through various actions you'll notice that there are three different types of actions: Docker container actions, JavaScript actions, and composite run steps actions. Let's take a closer look at each action type.

Docker container actions

Docker containers package the environment with the GitHub Actions code. This means that the action runs in a consistent and reliable environment because all of its dependencies are within that container. If the action needs to run in a specific environment configuration, then Docker containers are a good way to go because you can customize the operating system and tools. The downside is that because the job has to build and retrieve the container, Docker container actions are often slower than JavaScript actions.

Before building a Docker container action, you should have some basic understanding of how to use environment variables and the Docker container filesystem. The steps to take to build a Docker container action are then minimal and straightforward:

1. Create a Dockerfile to define the commands to assemble the Docker image.
2. Create an action.yml metadata file to define the inputs and outputs of the action. Set the runs: using: value to docker and the runs: image: value to Dockerfile in the file.
3. Create an entrypoint.sh file to describe the docker image.
4. Commit and push your action to GitHub with the following files: action.yml, entrypoint.sh, Dockerfile, and README.md.

JavaScript actions

JavaScript actions can run directly on the runner machine and separate the action code from the environment that is used to run the action. Because of this, the action code is simplified and can execute faster than actions within a Docker container.

As a prerequisite for creating and using packaged JavaScript actions, you need to download Node.js, which includes npm. As an optional step but one that we recommend is to use GitHub Actions Toolkit Node.js, which is a collection of Node.js packages that enables you to quickly build JavaScript actions with more consistency.

The steps to take to build a JavaScript action are then minimal and straightforward:

1. Create an action.yml metadata file to define the inputs and outputs of the action as well as tell the action runner how to start running this JavaScript action.
2. Create an index.js file with context information about the Toolkit packages, routing, and other functions of the action.
3. Commit and push your action to GitHub with the following files: action.yml, index.js, node_modules, package.json, package-lock.json, and README.md.

Composite run steps actions

Composite run steps actions enable you to reuse actions using shell scripts. You can even mix multiple shell languages within the same action. If you have a lot of shell scripts to automate several tasks, now you can easily turn them into an action and reuse them for different workflows. Sometimes it's easier to just write a shell script than using JavaScript or wrapping your code in a Docker container.

Metadata and syntax needed to create an action

When creating or reviewing a GitHub action, a great first step is to review the action.yml file to assess which inputs, outputs, description, runs, and other configuration information are needed for the action. Some of these parameters are required while others are optional. The action.yml file defines the following information about your action:

Parameter	Description	Required
Name	The name of your action. Helps visually identify the action in a job.	yes
Description	A summary of what your action does.	yes
Inputs	Input parameters enable you to specify data that the action expects to use during runtime. These parameters become environment variables in the runner.	no
Outputs	Output parameters enable you to specify data that subsequent actions can use later in the workflow after the action that defines these outputs has run.	no
Runs	The command to run when the action executes.	yes
Branding	Color and Feather icon to use to create a badge to personalize and distinguish your action in GitHub Marketplace.	no

Inputs

Inputs are the parameters that enable you to specify data that the action expects to use during its runtime. GitHub stores these input parameters as environment variables.

Below is an example of a list of inputs for an action. The firstNameStudent input is optional while the studentGrade input is required.

inputs:
  firstNameStudent:
    description: 'First name of student'
    required: false
    default: '1'
  studentGrade:
    description: 'Grade of the student'
    required: true

Outputs

Outputs are the parameters that enable you to declare data. Keep in mind that actions that run later in a workflow can use the output data that was declared in a previously ran action.

The below example is a simple output to declare the average grade of the students.

outputs:
  average:
    description: 'The average grade of the students'

Runs

As you learned previously, your action needs to have a runs statement that defines the command necessary to execute your action. Depending on how you're creating your action, whether you are using a Docker container, JavaScript, or composite run steps, the runs syntax is defined differently.

runs for Docker actions

Docker container actions require that the runs statement configures the image used for the Docker action with the following arguments:

• using: needs to be set to docker to run a Docker container action.
• image: Docker image used as the container to run the action.

runs:
  using: 'docker'
  image: 'Dockerfile'

runs for JavaScript actions

JavaScript actions require that the runs statement take the following two arguments:

• using: application used to execute the code as defined in main.
• main: file that contains the action code. The application defined in using executes this file.

For example, here is a runs statement for a JavaScript action using Node.js.

runs:
  using: 'node12'
  main: 'main.js'

runs for composite run steps actions

Composite run steps actions require that the runs statement take the following three arguments:

• using: needs to be set to "composite" to run a composite run step.
• steps: run steps to run the action.
• steps[*].run: command you want to run (can be inline or a script in your action repository).

For example, here is a runs statement for a composite run steps action that will run the script at filepath /test/script/sh.

runs:
  using: "composite"
  steps:
    - run: ${{ github.action_path }}/test/script.sh
      shell: bash

Branding

An optional but fun feature is the ability to customize the badge of your action. The badge is displayed next to the action name in the GitHub Marketplace. You can use a color and Feather icon to create the badge. For branding, you'll need to specify the icon and color you wish to use.

branding:
  icon: 'shield'  
  color: 'blue'

Here is an example of a badge for the Checkout action on the GitHub Marketplace.

:::image type="content" source="../media/actions-branding.png" alt-text="Screenshot that shows an action's branding on the GitHub Marketplace.":::

We'll cover choosing the right visibility for your action, best practices for documenting and versioning your action, and how to publish your action to the GitHub Marketplace in the next unit.