Configure Trigger Conditions

This document introduces how to configure workflow trigger events using the on field, including push, pull_request, workflow_dispatch, schedule, and branch/path/tag filtering rules.

When you need to control when a workflow is triggered, on which branch, path, or tag.

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:
    name: Test
    runs-on: [ubuntu-latest, x64, small]
    steps:
      - name: Checkout source code
        uses: checkout
      - name: Run build and test
        run: npm ci && npm test

Configuration Instructions

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. The branches filter refers to the target branch (base branch), not the source branch:

on:
  pull_request:
    branches:
      - main

Important: The branches filter refers to 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 configuration of activity types:

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

types values: The types value for pull_request is [merge, open, reopen, update]. If not specified, the default is [open, reopen, update].

Pull Request Comment Trigger

Triggered when a Pull Request comment is created, edited, or deleted.

on:
  pull_request_comment:
    types:
      - created
      - edited
      - deleted
    branches:
      - main
    comments:
      - '/deploy'
      - '/test'

Event Types:

Type	Description
created	Comment created
edited	Comment edited
deleted	Comment deleted

Filter Fields:

Field	Description	Example
branches	Match pattern of PR target branch name	main, feature/**
comments	Filter comment content based on regular expressions	/deploy, /test

Comments Filter Explanation: The comments field supports conditional filtering based on regular expressions for comment content. Only comments that match the specified regular expression pattern will trigger the workflow. For example, if configured as comments: ['/deploy'], the workflow will only be triggered when the comment contains the /deploy command.

Pipeline Echo Result: When triggering a pipeline through a PR comment, using the associate-pr-comment plugin in the pipeline can synchronize the pipeline execution details to the PR comment area and the PR check page.

Modified to: "When triggering a pipeline through a PR comment, using the associate-pr-comment plugin in the pipeline can synchronize the pipeline execution details to the PR comment area and the PR check page."

workflow_dispatch Manual Trigger

workflow_dispatch supports manually triggering a workflow in the AtomGit interface, and allows defining 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"

The workflow_dispatch.inputs of AtomGit Action 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

Due to performance considerations, workflow_call currently only supports one level of nested calls, meaning a reusable workflow cannot call another reusable workflow.

Schedule 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:

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

branches / branches-ignore Filter

• branches: Whitelist mode, only branches that match will trigger.
• branches-ignore: Blacklist mode, branches that do not match 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, any beyond that will not participate in the matching decision.

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"

Negative Pattern (!)

The ! prefix can be used in branches, paths, and tags to denote negative matching:

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

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