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 by an event, 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. branches filters 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 that the PR is merged into. If the PR's target branch is not in the branches list, it will not be triggered.

The pull_request supports configuring activity types:

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

types values: The types value of pull_request can be [merge, open, reopen, update]. If not filled, 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 the target branch name pattern of PR	main, feature/**, *
comments	Filter based on regular expressions for comment content	/deploy, /test

Branches Filter Explanation: If the branches field is set to *, it will not match branches in formats like feature/**. Use ** to match any level of directory branches.

Comments Filter Explanation: The comments field supports conditional filtering based on regular expressions for comment content. Only comments matching the specified regular expression pattern will trigger the workflow. For example, if configured as comments: ['/deploy'], only comments containing the /deploy instruction will trigger.

Pipeline Echo Result: When triggering the pipeline through a PR comment, using the associate-pr-comment plugin in the pipeline allows the pipeline execution details to be synchronized and displayed under the PR comment area and the PR check page.

Modified to: "When triggering the pipeline through a PR comment, using the associate-pr-comment plugin in the pipeline allows the pipeline execution details to be synchronized and displayed under the PR comment area and the PR check page."

workflow_dispatch Manual Trigger

workflow_dispatch supports manually triggering the 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 supports string, boolean, choice, and number types.

Inputs Attribute Fields:

Field	Description	Example Value
type	Input type	string, boolean, choice, number
required	Whether it is required	true, false
description	Description	env_type, port_number
default	Default value	true, false
options	Single choice, applicable only for choice type	info, warning, error

AtomGit Action's inputs supports string, boolean, choice, and number types.

type	Description	Example Value
string	String input	test, prod, dev
boolean	Boolean input	true, false
choice	Single choice input, configured via the options field	info, warning, error
number	Number input	8080, 50

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

For performance considerations, workflow_call currently only supports one level of nested calls; 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 Events Combination

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, only 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 the matched path.
• paths-ignore: Triggers only when changes occur in the unmatched path.
• Both cannot be used at the same time.
• paths match the first 300 changed files, the rest 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 (!)

The ! prefix can be used in branches, paths, and tags for 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 be triggered.