Workflow File Location and Basic Structure

Applicable scenarios: When you need to create the first AtomGit Action pipeline in a repository, or when you need to understand 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 permissions.
• The AtomGit Action feature is enabled.
• The repository can use a hosted Runner or has a self-hosted Runner configured.

Quick Example

name: ci

on:
  push:
    branches:
      - main

jobs:
  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	Explanation
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 for 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 conditions, 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 ATOMGIT_TOKEN
stages	No	Stage definition, configured only when stage-level 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 data 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:
        runs-on: [ubuntu-latest, x64, small]
        steps:
          - uses: checkout
          - run: echo "build"

post:
  run_always: true
  steps:
    - run: echo "notification"

Stages Mechanism

• Sequential Execution Between Stages: Multiple stages are executed in the defined order. 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 run by default in parallel.

name: staged-pipeline

on:
  push:
    branches:
      - main

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

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

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

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

post Post-Processing Stage

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

• run_always defaults to true, meaning it will execute regardless of whether the workflow succeeds or fails.
• It is suitable for placing logic such as notification pushing (e.g., email, IM messages), temporary file cleanup, and result back-writing.

name: ci-with-post

on:
  push:
    branches:
      - main

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

post:
  run_always: true
  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 policy
    enable: true # Whether to enable, default is true
    events: [mr_id] # Preemption events, limited to no more than 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 concurrency limit: IGNORE (ignore new requests) or QUEUE (queue and wait)
preemption.enable	Whether to enable preemption policy, default is true
preemption.events	Preemption events, limited to no more than 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
  hook: none

Permission Item	Description	Optional Levels
project	Project access permission	read / write / none
pr	Pull Request permission	read / write / none
issue	Issue permission	read / write / none
note	Comment/Note permission	read / write / none
repository	Repository permission	read / write / none
hook	Webhook permission	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 Issues

Q: When can the stages field be omitted?

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

Q: Can the run_always of the post stage be set to false?

A: Yes, but it defaults to true. If set to false, the post stage will only execute when the workflow is successful.