Product Overview

What is AtomGit Action

AtomGit Action is the native automation pipeline engine of the AtomGit platform, adopting the Pipeline as Code concept, allowing you to define, trigger, and execute software delivery processes by writing YAML configuration files in your code repository. Pipeline configurations are stored alongside business code, versioned together, following the GitOps practice of Everything as Code.

Core Concepts

Concept	Description
Pipeline as Code	Pipeline definitions are stored in the .gitcode/workflows/ directory, shared with business code for submission, review, and audit processes, all changes are traceable
Declarative Configuration	Define pipeline structure using concise YAML syntax, no need to write orchestration scripts, lowering the learning curve
Reusable Orchestration	Action plugins and reusable workflows (workflow_call) support cross-repository references and nested calls, avoiding repetitive maintenance
Security Isolation	Built-in pull_request / pull_request_target dual-event model, Secret encryption storage, Token minimum permission control, ensuring pipeline security in Fork scenarios

Platform Capabilities Overview

Event-Driven: Multiple Trigger Methods

AtomGit Action supports a rich set of event triggers, covering the full range of code collaboration scenarios:

Trigger Method	Description	Typical Scenario
push	Code push trigger	Automatic build and deployment after main branch merge
pull_request	Trigger on PR creation, update, or merge	PR code check, build validation
pull_request_target	Secure mode PR trigger (target branch context)	Fork PR auto-tagging, comments (can access Secrets)
issue_comment	Issue comment trigger	/deploy command-based deployment
pull_request_comment	PR comment trigger (supports regex filtering)	Execute specific actions within PR comments
workflow_dispatch	Manual trigger (supports input parameters)	Release specific versions, emergency hotfixes
workflow_call	Reusable workflow call	Organization-level standardized process orchestration
schedule	Scheduled trigger (cron expression)	Daily build, regular inspection

Each event supports branches, paths, tags and other filtering rules, precisely controlling the trigger scope. A single workflow can combine multiple trigger events.

Execution Orchestration: Stages + Jobs + Steps

AtomGit Action provides a two-tier orchestration mechanism, balancing flexibility and controllability:

Event → Workflow → Stages (serial) → Jobs (parallel within stage) → Steps (serial)
                                                                ├─ run (Shell command)
                                                                └─ uses (Action plugin)

• Stages Mechanism: Unique to AtomGit Action, stages are executed serially, jobs within a stage are parallel by default, supports fail_fast fast-fail strategy, suitable for delivery processes requiring strict gatekeeping
• Needs Dependency Mechanism: DAG dependency orchestration at the job level, enabling flexible topological relationships
• Post Processing: A unique post-processing stage in AtomGit Action, default run_always: true, used for notifications, cleanup, reporting, etc.
• Matrix Strategy: Achieve parallel builds and tests across multiple OS, versions, and architectures through strategy.matrix

Runtime Environment: Managed + Self-hosted Runner

Runner Type	Description	Tag Format
Official Managed	Cloud resource pool ready to use, pre-installed with mainstream language toolchains	Three-part format {os},{arch},{flavor}, such as {ubuntu-24,x64,small}
Self-hosted	Self-built infrastructure, supports GPU, internal network, custom toolchains	self-hosted + custom tags

The official resource pool provides 6 specifications from 1 core 4G (slim) to 32 cores 128G (2xlarge), defaulting to [ubuntu-latest, x64, small] (2 cores 8G). It supports specifying a custom Docker image via the container field.

Variables and Secrets: Four-Level Configuration System

Type	Scope	Reference Method	Applicable Scenario
env	workflow / job / step three levels	$VAR_NAME or ${{ env.VAR }}	Temporary environment variables
vars	organization / project level	${{ vars.VAR }}	Cross-pipeline shared configuration
secrets	organization / project	${{ secrets.NAME }}	Sensitive information (passwords, Tokens) (logs automatically masked)
inputs	workflow_dispatch / workflow_call	${{ inputs.NAME }}	Workflow input parameters (only supports string type)

Context and Expressions

AtomGit Action provides 12 contexts, dynamically accessing runtime information in workflows using ${{ context.property }} expression syntax:

Context	Description	Typical Use
atomgit	Platform and event core information	Branch judgment atomgit.ref, event type atomgit.event_name
env	Custom environment variables	Variable reference env.APP_NAME
vars	Configuration variables	Deployment target vars.DEPLOY_ENV
secrets	Encrypted keys	Credential reference secrets.DEPLOY_TOKEN
inputs	Input parameters	Manual trigger parameters inputs.environment
job / jobs	Current / called Job information	Status judgment job.status
steps	Step information and outputs	Cross-step value passing steps.id.outputs.result
runner	Runner environment information	System runner.os, temporary directory runner.temp
matrix / strategy	Matrix variables and strategy information	Matrix parameters matrix.version

Expressions support comparison operations, logical operations, status functions (success/failed/always/cancelled), and string functions (contains/startsWith/format/hashFiles, etc.).

Security and Permissions

Security Capability	Description
Secret Encryption Storage	Keys are encrypted when created in the interface, logs automatically mask them as ***, Fork PRs default to not being able to access project Secrets
Token Minimum Permission	The scope of ATOMGIT_TOKEN permissions is precisely controlled by the permissions field (read/write/none), supporting the minimal permission mode permissions: {}
PR Security Isolation	In the pull_request event, workflows in Fork repositories have only read permissions and cannot access Secrets; pull_request_target uses the workflow file of the target branch, preventing malicious PRs from tampering with execution logic
Concurrency Control	Limit the number of parallel runs for the same workflow through concurrency, supporting the IGNORE (ignore) and QUEUE (queue) strategies

Artifacts and Cache

Capability	Description
Artifacts	Transfer build artifacts across Jobs, supports upload/download, can set retention days
Cache	File-based dependency caching mechanism, accelerates dependency installation for npm, Maven, pip, Gradle, etc., through key + restore-keys prefix matching

Overview of Workflow File Structure

A complete AtomGit Action workflow file includes the following core fields:

name: Example Pipeline                   # Workflow name

on:                                    # Trigger event
  push:
    branches: [main]
  workflow_dispatch:
    inputs:
      environment:
        type: string

env:                                   # Workflow-level environment variables
  APP_NAME: my-app

defaults:                              # Default settings
  run:
    shell: bash

concurrency:                           # Concurrency control
  enable: true
  max: 3
  exceed-action: QUEUE

permissions:                           # Permission declaration
  repository: read
  pr: write

stages:                                # Stage definition (optional)
  - name: build-stage
    fail_fast: true
    jobs:
      build:
        runs-on: [ubuntu-latest, x64, small]
        steps:
          - uses: checkout
          - run: make build

  - name: deploy-stage
    jobs:
      deploy:
        runs-on: [ubuntu-latest, x64, small]
        steps:
          - run: make deploy

post:                                  # Post-processing stage
  run_always: true
  steps:
    - run: echo "notification"