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 all 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 verification
pull_request_target	Secure PR trigger (target branch context)	Fork PR auto-tagging, commenting (can access Secret)
issue_comment	Issue comment trigger	/deploy command-based deployment
pull_request_comment	PR comment trigger (supports regular expression filtering)	Execute specific actions in PR comments
workflow_dispatch	Manual trigger (supports input parameters)	Release specific versions, emergency hotfix
workflow_call	Reusable workflow call	Organizational-level standardized process orchestration
schedule	Scheduled trigger (cron expression)	Daily build, regular inspection

Each event supports branches, paths, tags etc. filter 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 (sequential) → Jobs (parallel within stage) → Steps (sequential)
                                                                ├─ run (Shell command)
                                                                └─ uses (Action plugin)

• Stages Mechanism: Unique to AtomGit Action, stages are executed sequentially, jobs within a stage are parallel by default, supports fail_fast fast failure strategy, suitable for delivery processes requiring strict gate control
• Needs Dependency Mechanism: DAG dependency orchestration at the job level, achieving flexible topological relationships
• Post Processing: A unique post-processing stage in AtomGit Action, used for notifications, cleanup, reports, etc.
• Matrix Strategy: Achieve parallel builds and tests for 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 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 toolchain	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 runtime environment via the container field.

Variables and Secrets: Four-Level Configuration System

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

Contexts and Expressions

AtomGit Action provides 12 contexts, dynamically accessing runtime information in workflows using the ${{ 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/invoked 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 parameter matrix.version

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

Security and Permissions

Security Capability	Description
Secret Encryption Storage	Keys are encrypted when created in the interface, logs are automatically desensitized to ***, Fork PRs cannot access project Secrets by default
Minimum Permission for Token	The scope of ATOMGIT_TOKEN permissions is precisely controlled by the permissions field (read/write/none), supports permissions: {} minimal permission mode
PR Security Isolation	In pull_request events, workflows in Fork repositories only have 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 IGNORE (ignore) and QUEUE (queue) strategies

Artifacts and Cache

Capability	Description
Artifacts	Transfer build products across Jobs, supports upload/download, can set retention days
Cache	File-based dependency cache 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 events
  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)
  build-stage:
    name: Build Stage
    fail_fast: true
    jobs:
      build:
        runs-on: [ubuntu-latest, x64, small]
        steps:
          - uses: checkout
          - run: make build

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

post:                                    # Post-processing stage
  jobs:
    post-process:
      runs-on: [ubuntu-latest, x64, small]
      steps:
        - run: echo "notification"