Trigger Events

This document is the complete reference for AtomGit Action trigger events, including configuration syntax and filter field explanations for all events such as push, pull_request, workflow_dispatch, schedule, etc.

A workflow defines the trigger conditions using the on keyword. AtomGit Action supports the following trigger events, and workflow files are stored in the .gitcode/workflows/ directory of the repository.

1.1 push

Triggers when a push operation occurs, including branch pushes and tag pushes.

on:
  push:
    branches:
      - main
      - 'releases/**'
    tags:
      - v1.*
      - v2.*
    paths:
      - 'src/**'
      - 'package.json'

Filter Fields:

Field	Description	Example
`branches`	Branch name pattern to match	`main`, `releases/**`
`branches-ignore`	Branch name pattern to exclude	`experimental/**`
`tags`	Tag name pattern to match	`v1.*`
`tags-ignore`	Tag name pattern to exclude	`v1.0.*`
`paths`	File path pattern to match	`src/**`
`paths-ignore`	File path pattern to exclude	`docs/**`

Note: branches and branches-ignore cannot be used together; tags and tags-ignore cannot be used together. paths and paths-ignore can be used with branch/tag filtering.

Special Usage:

on:
  push:
    branches:
      - '**'        # All branches
      - '!main'     # Exclude main (exclude pattern starts with !)

1.2 pull_request

Triggers when a Pull Request is created, updated, or merged.

on:
  pull_request:
    types:
      - open
      - reopen
      - update
      - merge
    branches:
      - main
      - 'feature/**'
    paths:
      - 'src/**'
    paths-ignore:
      - 'docs/**'

Event Types (types):

Type	Description
`open`	PR created
`reopen`	PR reopened
`update`	New commit in the source branch of the PR (most common trigger scenario)
`merge`	PR merged

Default Value: When types is not specified, the default is [open, reopen, update], i.e., triggers on PR creation, reopening, and updates, but not on merging.

Filter Fields: Same as push, supporting branches, branches-ignore, paths, paths-ignore.

1.3 pull_request_target

Similar to pull_request, but the workflow runs in the context of the target branch (base branch), allowing reading and writing to the target repository. It is suitable for scenarios requiring access to repository Secrets or performing write operations (e.g., auto-labeling, comments, etc.).

on:
  pull_request_target:
    types:
      - open
      - update
      - merge
    branches:
      - main

Security Note: pull_request_target uses the workflow file and permissions of the target branch. PRs from forked repositories can also trigger it. Please handle code execution from forked PRs carefully to avoid security risks.

Default Value: When types is not specified, the default is [open, reopen, update], same as pull_request.

1.4 issue_comment

Triggers when an Issue or PR comment is created, edited, or deleted.

on:
  issue_comment:
    types:
      - created
      - edited
      - deleted

Event Types:

Type	Description
`created`	Comment created
`edited`	Comment edited
`deleted`	Comment deleted

Note: issue_comment applies to both Issue comments and PR comments. If you want to filter only PR comments, you can use a conditional expression in the workflow to check if atomgit.event.issue_comment.issue.pull_request exists.

1.5 pull_request_comment

Different from issue_comment, it only triggers when a Pull Request comment is made.

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`	Branch name pattern to match for PR	`main`, `feature/**`
`comments`	Filter comment content based on regular expressions	`/deploy`, `/test`

Comments Filter Explanation: The comments field supports condition filtering based on regular expressions for comment content. Only comments matching the specified regular expression pattern will trigger the workflow. For example, configuring comments: ['/deploy'] means that the workflow will only trigger when the comment contains the /deploy command.

1.6 workflow_dispatch

Manually triggers the workflow and supports custom input parameters.

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

Inputs Type Specifications:

The inputs of AtomGit Action only support the string type. All input values are strings.

type	Description	Optional Fields
`string`	String input	`description`, `required`, `default`

Access input values in the workflow using the inputs context, such as ${{ inputs.environment }}. If you need numeric or boolean semantics, you can perform type conversion using expressions within the workflow.

1.8 workflow_call

Allows one workflow to be called by another workflow (reusable workflow).

on:
  workflow_call:
    inputs:
      config-path:
        description: 'Configuration file path'
        required: false
        default: 'config/default.json'
        type: string
      environment:
        description: 'Deployment environment'
        required: true
        type: string
    secrets:
      deploy-token:
        description: 'Deployment authentication token'
        required: true
      db-password:
        description: 'Database password'
        required: false

Calling Workflow Example:

jobs:
  deploy:
    name: Deployment
    uses: ./.gitcode/workflows/deploy.yml
    with:
      config-path: 'config/production.json'
      environment: production
    secrets:
      deploy-token: ${{ secrets.DEPLOY_TOKEN }}
      db-password: ${{ secrets.DB_PASSWORD }}

1.9 schedule

Triggers the workflow at scheduled times, using POSIX cron syntax.

on:
  schedule:
    - cron: '30 5 * * 1,3'    # Every Monday and Wednesday at 05:30 UTC
    - cron: '0 2 * * *'        # Every day at 02:00 UTC
    - cron: '15 0 1 1 *'       # January 1st at 00:15 UTC every year

Cron Syntax Format: minute hour day month weekday

Position	Range	Description
Minute	0-59	The minute of the hour
Hour	0-23	UTC hour
Day	1-31	The day of the month
Month	1-12	The month
Weekday	0-6	0=Sunday, 1=Monday, ..., 6=Saturday

Special Symbols:

Symbol	Description	Example
`*`	Any value	`* * * * *` — every minute
`,`	List separator	`1,3,5` — 1st, 3rd, 5th
`-`	Range	`1-5` — from 1 to 5
`/`	Step	`*/15` — every 15 units

Note: The shortest interval for schedule is 5 minutes. Cron uses UTC time, please convert to local time.

1.1 push​

1.2 pull_request​

1.3 pull_request_target​

1.4 issue_comment​

1.5 pull_request_comment​

1.6 workflow_dispatch​

1.8 workflow_call​

1.9 schedule​