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, and schedule.

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 patterns to match	`main`, `releases/**`
`branches-ignore`	Branch name patterns to exclude	`experimental/**`
`tags`	Tag name patterns to match	`v1.*`
`tags-ignore`	Tag name patterns to exclude	`v1.0.*`
`paths`	File path patterns to match	`src/**`
`paths-ignore`	File path patterns 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: If types is not specified, the default is [open, reopen, update], which triggers on PR creation, reopening, and updating, but not 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 write operations (e.g., auto-tagging, comments).

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, and can be triggered by PRs from forked repositories. Be cautious when handling code execution from fork PRs to avoid security risks.

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

1.4 issue_comment

Triggers when an Issue 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

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

Comments Filter Explanation: The comments field supports condition 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 trigger when the comment contains the /deploy instruction.

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
      deploy_count:
        description: 'Number of parallel deployments'
        required: false
        default: "1"
        type: number
      dry_run:
        description: 'Whether to validate without deployment'
        required: false
        default: "false"
        type: boolean
      log_level:
        description: 'Log level'
        required: false
        default: 'info'
        type: choice
        options:
          - 'info'
          - 'error'
          - 'warning'

Inputs Property 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 option, 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 selection input, configured via `options` field	`info`, `warning`, `error`
`number`	Number input	`8080`, `50`

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

1.8 workflow_call

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

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

Example of Calling Workflow:

jobs:
  deploy:
    name: Deploy
    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 a scheduled time 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 every year at 00:15 UTC

Cron Syntax Format: minutes hours day month weekday

Position	Range	Description
Minutes	0-59	The minute of the hour
Hours	0-23	Hour in UTC time
Day	1-31	The day of the month
Month	1-12	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` — 1 to 5
`/`	Step	`*/15` — every 15 units

Note: The minimum interval for schedule is 5 minutes. Cron uses UTC time, so 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​