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 is defined by the on keyword to specify the trigger conditions. 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'
    paths-ignore:
      - 'docs/**'
      - '**.md'

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 on 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], meaning it triggers on PR creation, reopening, and updates, but not on merging.

Filter Fields: Same as push, supporting branches, branches-ignore, paths, and 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 read and write access to the target repository. It is suitable for scenarios requiring access to repository Secrets or performing write operations (such as automatic tagging, 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, and forked PRs can also trigger it. Please handle code execution from fork PRs carefully to avoid security risks.

Default Value: If types is not specified, the default is [open, reopen, update], which is consistent with 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 comments based on regular expressions	`/deploy`, `/test`

Comments Filter Explanation: The comments field supports filtering comments based on regular expressions. 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 a workflow, supporting 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:

AtomGit Action's inputs 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 within the workflow using expressions.

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

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 a 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 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	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` — 1, 3, 5
`-`	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 it 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​