Using Action Plugins

Applicable Scenarios: When you need to call reusable Action plugins in a step to perform operations such as pulling code, setting up the language environment, caching dependencies, and uploading artifacts.

Prerequisites

• Familiar with the usage of uses and with.

Quick Example

jobs:
  build:
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - name: Checkout source code
        uses: checkout

      - name: Setup Node.js
        uses: setup-node
        with:
          node-version: "20"

      - run: npm ci
      - run: npm test

Configuration Description

Three Ways to Reference

AtomGit Action supports three ways to reference Action plugins:

Method	Syntax	Description
Official Plugin	uses: action-name@ref	Directly write the plugin name
Open Source Plugin	uses: owner/repo/path@ref	Plugin in AtomGit public repository
Local Reference	uses: ./path/to/action	Plugin in the current repository

1. Official Plugin Reference

Directly write the plugin name:

steps:
  - uses: checkout
  - uses: setup-node
    with:
      node-version: "20"

2. Open Source Plugin Reference

Reference an Action in an open-source repository using the {owner}/{repo}/{path}@{ref} format:

steps:
  - uses: checkout
  - uses: docker/build-push-action@v6
    with:
      push: true
      tags: example.com/demo/app:latest

3. Custom Plugin Reference (Relative Path in the Same Repository)

Reference a local Action in the current repository:

steps:
  - uses: ./.gitcode/actions/my-custom-action

The local Action must have an action.yml metadata file in the corresponding path of the repository:

# Using Action Plugins
name: "My Custom Action"
description: "Do something custom"
inputs:
  param1:
    description: "Parameter 1"
    required: false
    default: "default-value"
outputs:
  result:
    description: "Action result"
runs:
  using: 'node16'
  main: 'dist/main.js'

Action Version Reference Methods

Reference Method	Description	Recommendation
@v4 (Tag)	Use the major version tag, which can automatically get patch updates	Recommended
@v4.1.0 (Full Version)	Use the exact version, stable behavior but no automatic update	Highest Security
@main (Branch)	Use the latest commit in the branch, behavior may change	Not Recommended
@a1b2c3d (SHA)	Use the exact commit SHA, behavior is completely determined	Recommended for Production

Passing Parameters with with

with is used to pass input parameters to the Action, and the parameter names must match the inputs defined in the Action's action.yml:

steps:
  - uses: setup-node
    with:
      node-version: "20"
      registry-url: "https://registry.npmjs.org"