05.6_custom-action.md

Toolkits, tips, tricks for writing custom actions {docsify-ignore-all}

JavaScript actions library

When writing JavaScript based actions it is incredibly useful to leverage the GitHub Actions toolkit. This toolkit comes packed with functions to perform a wide range of tasks.

core

Useful when managing inputs, outputs, results, logging, secrets and variables.

Installation: npm install @actions/core --save

exec

Allows execution of CLI tools and is capable of processing the output.

Installation: npm install @actions/exec --save

glob

Provides a set of functions that make searching for files matching a glob patterns easy to use.

Installation: npm install @actions/glob --save

io

Need to perform disk related tasks such as copying, moving or deleting files? If so, this is the package for you.

Installation: npm install @actions/io --save

tool-cache

Provides functions for downloading and caching tools.

Installation: npm install @actions/tool-cache --save

github

If interaction with your repo through the GitHub API is likely, this package provides you will an Octokit client that is fully hydrated to the current action context.

Installation: npm install @actions/github --save

artifact

Provides functions that interact with artifacts.

Installation: npm install @actions/artifact --save

Workflow commands for GitHub Actions

If you are running shell commands or writing a Docker container action there is a set of workflow commands available to you. These commands can be a part of your workflow.yml files or source code in your custom actions.

Each function in the @actions/core tookit package has an equivalent workflow command. Let's look at how them map together now:

Toolkit function	Equivalent workflow command
core.addPath	add-path
core.debug	debug
core.error	error
core.endGroup	endgroup
core.exportVariable	set-env
core.getInput	Accessible using environment variable INPUT_{NAME}
core.getState	Accessible using environment variable STATE_{NAME}
core.isDebug	Accessible using environment variable RUNNER_DEBUG
core.saveState	save-state
core.setFailed	Used as a shortcut for ::error and exit 1
core.setOutput	set-output
core.setSecret	add-mask
core.startGroup	group
core.warning	warning fil

Using these commands in a workflow

- name: Set selected color
  run: echo '::set-env name=USER_NAME::Mona'
- name: Get color
  run: echo 'The selected color is' $USER_NAME

Using commands as a part of a Python based Docker container action

def select_random_fact(fact_arr):
    return fact_arr[random.randint(0, len(fact_list)+1)]


random_fact = select_random_fact(fact_list)

# Set the output of the action as the value of random_fact
print(f"::set-output name=fact::{random_fact}")

GitHub Script

A really useful action that exists is called GitHub Script and its main purpose is to allow you to use the GitHub API through Octokit directly in your workflow files without the need to package and manage a complete custom action.

Take a look at this quick example of using GitHub Script

on:
  issues: { types: opened }

jobs:
  comment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/[email protected]
        with:
          github-token: ${{secrets.GITHUB_TOKEN}}
          script: |
            github.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '👋 Thanks for reporting!'
            })

At first glance it may seem as though a workflow files accepts the Octokit JavaScript library. It is important to note that this is not the case, and rather you are passing raw text to an action located at actions/[email protected].

It's also worth noting that this action is under active development and many things can change, so use at your own risk. We will show you this action in action... pun intended, regardless of it's development state.

---

👈 Enough talk, let's get our hands... or keyboards rather... dirty!