Configure Trigger Conditions

Applicable Scenarios: When you need to control when a workflow is triggered by specific events, branches, paths, or tags.

Prerequisites

• The workflow file has been placed in the .gitcode/workflows/ directory.
• Familiar with basic YAML syntax.

Quick Example

name: ci

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  test:
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - uses: checkout
      - run: npm ci && npm test

Configuration Explanation

Push Trigger

The push event is triggered when code is pushed to the repository:

on:
  push:
    branches:
      - main
      - develop

Pull Request Trigger

The pull_request event is triggered when a Pull Request is created, updated, or merged. branches filters the target branch (base branch), not the source branch:

on:
  pull_request:
    branches:
      - main

Important: branches filter the PR's target branch (base branch), i.e., the branch into which the PR is merged. If the PR's target branch is not in the branches list, it will not trigger.

pull_request supports configuring activity types:

on:
  pull_request:
    types:
      - open
      - update
      - reopen
    branches:
      - main

types value range: The types of pull_request can be [merge, open, reopen, update]. If not specified, the default is [open, reopen, update].

workflow_dispatch Manual Trigger

workflow_dispatch supports manually triggering a workflow in the AtomGit interface and can define input parameters:

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deployment target environment'
        required: true
        default: 'staging'
        type: string
      version:
        description: "Release version number"
        type: string
        required: false
        default: "1.0.0"
      deploy_count:
        description: 'Number of parallel deployments'
        type: string
        required: false
        default: "1"
      dry_run:
        description: 'Whether to validate without deployment'
        type: string
        required: false
        default: "false"

AtomGit Action's workflow_dispatch.inputs only supports string type parameters. All input values are strings; if you need numeric or boolean semantics, you can perform type conversion using expressions within the workflow.

workflow_call Reusable Workflow Trigger

workflow_call is used to define a reusable workflow that can be called by other workflows:

on:
  workflow_call:
    inputs:
      config-path:
        description: "Configuration file path"
        type: string
        required: false
        default: "config/default.json"
    secrets:
      deploy-token:
        description: "Deployment token"
        required: true

Nested calls support up to 2 layers, meaning a reusable workflow cannot call another reusable workflow.

schedule Scheduled Trigger

schedule uses POSIX cron syntax:

on:
  schedule:
    - cron: "0 2 * * *"

Note:

• cron uses UTC time zone.
• Scheduled tasks may have a delay of several minutes.
• schedule only takes effect on the default branch of the repository.
• The five parts of cron mean: minute hour day month weekday.

Multiple Event Combinations

A single workflow can respond to multiple events simultaneously:

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:
  schedule:
    - cron: "0 2 * * *"

branches / branches-ignore Filter

• branches: whitelist pattern, only matching branches will trigger.
• branches-ignore: blacklist pattern, only non-matching branches will trigger.
• Both cannot be used at the same time.

on:
  push:
    branches:
      - main
      - develop
      - 'feature/**'

on:
  push:
    branches-ignore:
      - experimental

paths / paths-ignore Filter

• paths: triggers only when changes occur in matching paths.
• paths-ignore: triggers only when changes occur in non-matching paths.
• Both cannot be used at the same time.
• paths match the first 300 changed files, changes beyond this limit are not considered for matching.

on:
  push:
    branches:
      - main
    paths:
      - "src/**"
      - "package.json"
      - "!src/docs/**"

on:
  push:
    branches:
      - main
    paths-ignore:
      - "docs/**"
      - "**.md"

tags / tags-ignore Filter

on:
  push:
    tags:
      - "v*"
      - "release-*"

on:
  push:
    tags-ignore:
      - "v*-alpha"

Negation Pattern (!)

In branches, paths, and tags, you can use the ! prefix to indicate negation matching:

on:
  push:
    branches:
      - "feature/**"
      - "!feature/experimental"
    paths:
      - "src/**"
      - "!src/docs/**"

Note: Negation patterns must be used in combination with positive patterns. If there is only a negation pattern (e.g., branches: ["!main"]), the workflow will not trigger.