Product Overview

What is AtomGit Action

AtomGit Action is the native automation pipeline engine of the AtomGit platform, adopting the Pipeline as Code philosophy, 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, reducing 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	Triggered by code push	Automatically build and deploy after merging into the main branch
pull_request	Triggered on PR creation, update, or merge	PR code check, build validation
pull_request_target	Secure mode PR trigger (target branch context)	Automatic tagging, comments for Fork PRs (can access Secrets)
issue_comment	Triggered by issue comment	/deploy command-based deployment
pull_request_comment	Triggered by PR comment (supports regular expression 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 builds, regular inspections

Each event supports branches, paths, tags, and other filtering rules, precisely controlling the scope of triggers. 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, used for notifications, cleanup, reporting, etc.
• Matrix Strategy: Achieve parallel builds and tests for multiple OS, versions, and architectures through strategy.matrix

Runners: Managed + Self-Hosted

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	Custom infrastructure, supports GPU, internal network, custom toolchains	self-hosted + custom tags

The official resource pool provides 6 specifications ranging 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 }}	Shared configuration across pipelines
secrets	Organization / Project	${{ secrets.NAME }}	Sensitive information (passwords, Tokens) (log auto-redaction)
inputs	workflow_dispatch / workflow_call	${{ inputs.NAME }}	Workflow input parameters (only supports string type)

Context and Expressions

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

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 transfer 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 (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 automatically redact to ***, Fork PRs cannot access project secrets by default
Minimum Token Permissions	The scope of ATOMGIT_TOKEN permissions is precisely controlled by the permissions field (read/write/none), supports permissions: {} minimum permission mode
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 from the target branch, preventing malicious PRs from tampering with execution logic
Concurrency Control	Limit the number of concurrent runs of the same workflow through concurrency, supporting IGNORE (ignore) and QUEUE (queue) strategies

Artifacts and Cache

Capability	Description
Artifacts	Pass 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., via 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"