javascript-action

This template includes a licensed.yml workflow that uses Licensed to check for non-compliant or missing licenses in your dependencies. By default, this workflow is disabled.

Enabling License Checks

To enable, edit .github/workflows/licensed.yml and uncomment the following lines:

# pull_request:
#   branches:
#     - main
# push:
#   branches:
#     - main

Updating the License Database

If you install or update dependencies, you may need to update the cached licenses using the Licensed CLI:

• Update cache: licensed cache
• Check status: licensed status

The @github/local-action utility simulates the GitHub Actions Toolkit, allowing you to test your action without committing and pushing to GitHub.

Using the CLI

Run the utility via npx by providing the path to your action.yml, your entrypoint, and a .env file containing environment variables (like inputs or event payloads).

# Syntax: npx @github/local-action <action-yaml-path> <entrypoint> <dotenv-file>
npx @github/local-action . src/main.js .env

Using VS Code

You can also use the Visual Studio Code Debugger by configuring .vscode/launch.json.

Use this repository as a template to create a production-ready JavaScript GitHub Action. The template includes support for compilation (bundling), testing, validation workflows, and publishing guidance.

To start:

1. Click the Use this template button in the repository header.
2. Create a new repository with your desired owner and name.
3. Clone your new repository locally.

Important: After cloning, ensure you update or remove the CODEOWNERS file to reflect your own ownership.

Your action logic resides in the src/ directory. When writing your code, remember that most GitHub Actions toolkit operations are asynchronous; your entrypoint (e.g., main.js) should use an async function.

Development Workflow:

1. Replace the contents of src/ with your logic.
2. Add tests to __tests__/.
3. Crucial Step: Run npm run all to format, test, and build the action using rollup. This step bundles your dependencies into the final JavaScript file. If you skip this, your action will not work in a workflow.
4. Commit and push your changes to a release branch (e.g., releases/v1).

After cloning the template, perform these steps to prepare your local environment. This template requires Node.js 20.x or later.

1. Install dependencies:

   npm install

2. Package the JavaScript for distribution (bundling):

   npm run bundle

3. Run existing tests:

   npm test

The action.yml file is the source of truth for your action's metadata. You must update this file to define the action's:

• Name
• Description
• Inputs (parameters passed to the action)
• Outputs (data produced by the action)

Once your action is published and tagged (e.g., v1), other developers can use it via the uses syntax. Reference a specific version using the @ symbol.

steps:
  - name: Checkout
    uses: actions/checkout@v4

  - name: Run My Action
    uses: actions/javascript-action@v1
    with:
      milliseconds: 1000

  - name: Print Output
    run: echo "${{ steps.test-action.outputs.time }}"

To verify your action works in a real GitHub environment, reference it in a workflow file within your repository using a relative path.

steps:
  - name: Checkout
    uses: actions/checkout@v4

  - name: Test Local Action
    id: test-action
    uses: ./
    with:
      milliseconds: 1000

  - name: Print Output
    id: output
    run: echo "${{ steps.test-action.outputs.time }}"

The run() function is the main entrypoint for this JavaScript action. When executed, it performs the following lifecycle:

1. Reads the milliseconds input from the GitHub Action environment.
2. Logs debug information (only visible if ACTIONS_STEP_DEBUG is enabled).
3. Waits for the specified number of milliseconds.
4. Sets a time output containing the timestamp (in toTimeString() format) after the wait period.
5. Handles errors by calling core.setFailed with the error message, which fails the GitHub Action step.

To use this in a custom action, ensure you have an input named milliseconds defined in your action.yml.

import { run } from './src/main.js';

// This is typically called by the action runner
await run();

This action interacts with the GitHub Actions environment using the following inputs and outputs:

Inputs

• milliseconds: The duration to wait, provided as a string representing an integer.

Outputs

• time: A string representing the timestamp (via Date.prototype.toTimeString()) recorded after the wait period completes.