pwsh-github-action-base

Base support for implementing GitHub Actions in PowerShell Core

:star: I appreciate your star, it helps me decide to which OSS projects I should allocate my spare time.

This repository contains a bundle of files to support creating GitHub Actions in PowerShell Core that can be executed across all the supported platforms where GitHub Workflows are executed.

The distribution includes a number of base components:

• _init/index.js - The entry point into invoking the Action.
• SAMPLE-action.ps1 - A sample script implementing a simple Action script demonstrating some of the features made available from the Core library.
• SAMPLE-action.yml - A sample Action metadata file that describes various attributes such as a description, licensing, branding and formal input and output values.

Additionally, the sample Action shows how to make use of the GitHubActions module to get access to the GH Actions/Workflow environment for input, output and messaging. More details can be found below

Required Components

action.ps1 - The PowerShell Entry Point

You create an Action by creating a PowerShell script named action.ps1, this the the main entry point into your Action logic. From here you can inspect for, and assemble inputs and environment variables, call into other processes in the local environment context, and issue commands to the Action/Workflow context to perform logging and adjust the state of the job as seen by subsequent Actions and Steps.

You can also make calls out to external services via APIs, including calling into the GitHub API.

action.yml - The Action Metadata

As per the GitHub Actions mechanism, you must provide a metadata file that describes various attributes about your Action, including any formal inputs and outputs. You use this metadata file to enumerate any required inputs that must be provided by a Workflow definition.

runs Entry Point Attribute

The most important attribute in this file for our purposes is the runs setting which has two child settings, using and main. This attribute indicates what is the type of your Action and how to run it.

There are two main types of Actions, one based on Docker containers and one based on JavaScript (NodeJS). While Docker Actions give you the ability to define and carry the entire runtime with you, they are slower to start and limited to only executing in Linux environments.

JavaScript Actions however are simpler and more lightweight, and therefore quicker to start, and they can run on any of the supported platforms (Linux, Windows, MacOS). They also execute directly in the hosted virtual machine where the Workflow runs instead of a dedicated container.

Because of these advantages, this repo hosts a solution that is based on JavaScript-type Actions. A stub JavaScript script is provided to bootstrap the Action entry point and then immediately switches over to your provided PowerShell script. To use this bootstrap script, you need to specify the following runs attribute in your actions.yml metadata file:

runs:
  using: node12
  main: _init_/index.js

This configuration assumes you have placed the bootstrap JavaScript file in a _init subdirectory within your Action root directory. The bootstrap code also assumes this subdirectory location. If you decide to place it elsewhere or otherwise rename it, make sure to adjust the metadata file appropriately, and update the bootstrap script logic to accommodate any path changes.

_init/index.js

As mentioned above the _init/index.js file is a bootstrap JavaScript file that is used as the initial main entry point into your custom Action. After starting, it immediately transfers control to your PowerShell script by invoking the file action.ps1 in the directory immediately above the _init subdirectory. The invocation is equivalent to the following command-line call:

pwsh -f /full/path/to/action.ps1

The working directory is the same as at the start of the bootstrap script which is the root of the cloned repository of the Workflow in which the action is being invoked.

Optional Support Module

In addition to the required components above, you may choose to make use of the GitHubActions PowerShell module utility script that defines a number of cmdlets that help interact with the Worklfow/Action environment context in a more natural way for PowerShell scripts. These cmdlets are adaptations of the JavaScript Actions core package provided in the Actions Toolkit. See that package description for details about what it provides

For details about the counterpart cmdlets, go to the docs.