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 storing 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 on PR submission
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 runs for 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 are present, nested within stages when stages are present)
post	No	Post-processing stage, used for notifications, cleanup, and writing back data

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 order defined, 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 immediately terminate the execution of subsequent stages.
• 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: Deployment Stage
    jobs:
      deploy:
        name: Deployment
        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 for notifications, resource cleanup, and status writing after the workflow execution.

• Suitable for placing logic such as notification pushing (e.g., email, IM messages), 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, can only configure up to 10, refer to the usage of 'on'

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 preemption strategy, default is true
preemption.events	Preemption events, can only configure up to 10

Permissions

AtomGit Action's permission system, 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

Shortcut 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: {}

Common Questions

Q: When can the stages field be omitted?

A: When the workflow has only one logical stage (or does not require 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 via needs.