Using Action Plugins

This document introduces how to reference official plugins, open-source plugins, and custom plugins in steps, as well as how to pass parameters and specify versions.

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

• Have knowledge of the usage of uses and with.

Quick Example

jobs:
  build:
    name: 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"

      - name: Run ci
        run: npm ci
      - name: Run test
        run: npm test

Configuration Instructions

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	Action in AtomGit public repository
Local Reference	uses: ./path/to/action	Action in the current repository

1. Reference to Official Plugin

Directly write the plugin name:

steps:
  - name: Checkout source code
    uses: checkout
  - name: setup node
    uses: setup-node
    with:
      node-version: "20"

2. Reference to Open Source Plugin

Use the {owner}/{repo}/{path}@{ref} format to reference an Action in an open-source repository:

steps:
  - name: Checkout source code
    uses: checkout
  - name: Run build
    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:
  - name: Run custom action
    uses: ./.gitcode/actions/my-custom-action

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

# .gitcode/actions/my-custom-action/action.yml
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, behavior is stable but will not auto update	Highest security
@main (Branch)	Use the latest commit of the branch, behavior may change	Not recommended
@a1b2c3d (SHA)	Use the exact commit SHA, behavior is fully 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 definitions in inputs of the Action's action.yml:

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