Workflow File Location and Basic Structure

This document introduces the directory where AtomGit Action workflow files are stored, naming conventions, YAML structure fields, and configuration items such as stages, post, concurrency, and permissions.

When you need to create your first AtomGit Action pipeline in a repository or want to know where the workflow file should be placed, how to name it, and what the basic YAML structure looks like.

Prerequisites

• A existing AtomGit repository with write access.
• The AtomGit Action feature is enabled.
• The repository can use a managed Runner or has a self-hosted Runner configured.

Quick Example

name: ci

on:
  push:
    branches:
      - main

jobs:
  build:
    name: Build
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - name: Checkout source code
        uses: checkout
      - name: Run build
        run: echo "build success"

Configuration Description

File Storage Directory

The directory for AtomGit Action workflow files is:

.gitcode/workflows/<workflow-name>.yml

Only files with .yml and .yaml extensions are recognized as workflow files; other extensions will be ignored.

Naming Suggestions

Scenario	Recommended Filename	Description
Continuous Integration	ci.yml	Build and test on push or PR
Pull Request Check	pr-check.yml	Automatic check when PR is submitted
Release	release.yml	Trigger release process on Tag
Docker Image Build	docker-build.yml	Build and push image
Scheduled Task	nightly.yml	Daily scheduled build
Manual Deployment	deploy.yml	Manual trigger deployment

Basic Structure Fields

A minimal workflow file includes the following core fields:

Field	Required	Description
name	No	Display name of the workflow, defaults to the filename if not specified
on	Yes	Trigger condition, defines which events trigger the workflow
env	No	Workflow-level environment variables, visible to all jobs and steps
defaults	No	Default settings, such as default shell and working directory
concurrency	No	Concurrency control, limits the number of parallel executions of the same workflow
permissions	No	Permission declaration, controls the scope of the ATOMGIT_TOKEN
stages	No	Stage definition, configured only when stage serial control is needed
jobs	Yes	Task collection (top-level field when no stages, nested within stages when stages exist)
post	No	Post-processing stage, used for notifications, cleanup, and writing back

Complete Basic Structure Example

name: Example Pipeline

on:
  push:
    branches:
      - main

env:
  APP_NAME: my-app

defaults:
  run:
    shell: bash

concurrency:
  enable: true
  max: 3
  exceed-action: QUEUE

permissions:
  repository: read
  pr: write

stages:
  build_stage:
    name: Build
    jobs:
      build:
        name: Build
        runs-on: [ubuntu-latest, x64, small]
        steps:
          - name: Checkout source code
            uses: checkout
          - name: Run build
            run: echo "build"

post:
  jobs:
    post-process:
      name: Notification
      runs-on: [ubuntu-latest, x64, small]
      steps:
        - name: Send notification
          run: echo "notification"

Stages Mechanism

• Serial Execution Between Stages: Multiple stages are executed in the defined order, and the next stage starts only after all jobs in the previous stage are completed.
• fail_fast: When a job in a stage fails, you can configure whether to terminate subsequent stages immediately.
• Optional: When a workflow has only one stage, the stages field can be omitted. In this case, all jobs are executed in parallel by default.

name: staged-pipeline

on:
  push:
    branches:
      - main

stages:
  build-stage:
    name: Build Stage
    fail_fast: true
    jobs:
      build:
        name: Build
        runs-on: [ubuntu-latest, x64, small]
        steps:
          - name: Run build
            run: echo "build"

  test-stage:
    name: Test Stage
    fail_fast: false
    jobs:
      unit-test:
        name: Unit Test
        runs-on: [ubuntu-latest, x64, small]
        steps:
          - name: Run unittest
            run: echo "unit test"

      integration-test:
        name: Integration Test
        runs-on: [ubuntu-latest, x64, small]
        steps:
          - name: Run integration test
            run: echo "integration test"

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

post Post-Processing Stage

post is a unique post-processing stage in AtomGit Action, used to perform operations such as notifications, resource cleanup, and status writing after the workflow execution ends.

• It is suitable for placing logic such as notification pushing (e.g., email, IM message), temporary file cleanup, and result writing.

name: ci-with-post

on:
  push:
    branches:
      - main

jobs:
  build:
    name: Build
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - name: Run build
        run: echo "build"

post:
  jobs:
    post-process:
      name: Notification
      runs-on: [ubuntu-latest, x64, small]
      steps:
        - name: Send notification
          run: echo "workflow finished, send notification"

Concurrency Control

Concurrency control configuration for AtomGit Action:

concurrency:
  enable: true
  max: 3
  exceed-action: QUEUE
  preemption: # Preemption strategy
    enable: true # Whether to enable, default is true
    events: [mr_id] # Preemption events

Field	Description
enable	Whether to enable concurrency control
max	Maximum number of concurrent runs, range 1-5
exceed-action	Strategy when exceeding the concurrency limit: IGNORE (ignore new requests) or QUEUE (queue and wait)
preemption.enable	Whether to enable the preemption strategy, default is true
preemption.events	Preemption events, supports mr_id

Permissions

The permission system of AtomGit Action, using the corresponding permission items from the atomgit context:

permissions:
  project: read
  pr: write
  issue: read
  note: write
  repository: read

Permission Item	Description	Optional Levels
project	Project access rights	read / write / none
pr	Pull Request rights	read / write / none
issue	Issue rights	read / write / none
note	Comment/Note rights	read / write / none
repository	Repository rights	read / write / none

Quick syntax:

• read-all: Set all permissions to read
• write-all: Set all permissions to write
• permissions: {}: Set all permissions to none (principle of least privilege)

permissions: read-all

permissions: {}

Frequently Asked Questions

Q: When can the stages field be omitted?

A: When the workflow has only one logical stage (or no need for stage serial control), the stages field can be omitted. After omission, all jobs are executed in parallel by default, and dependency relationships can be configured through needs.