Trigger Events

Workflows are defined using the on keyword for 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 commits in the source branch of the PR (most common trigger scenario)
`merge`	PR merged

Default Value: If types is not specified, it defaults to [open, reopen, update], meaning triggers on PR creation, reopening, and updates, 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 performing 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 forked PRs can also trigger it. Please handle code execution from fork PRs carefully to avoid security risks.

Default Value: When types is not specified, it defaults to [open, reopen, update], 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. 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

Differs from issue_comment and triggers only 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	`main`, `feature/**`
`comments`	Comment content filtered by regular expressions	`/deploy`, `/test`

Comments Filter Explanation: The comments field supports filtering based on regular expressions for comment content. Only comments matching the specified regular expression pattern will trigger the workflow. For example, if comments: ['/deploy'] is configured, 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 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:
    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	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 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​