Manually Trigger a Pipeline

This document introduces how to manually trigger a workflow on the AtomGit interface and pass input parameters using the workflow_dispatch event.

When you need to actively execute a pipeline in non-automatic triggering scenarios — for example, debugging a branch, validating temporary parameters, or releasing a specific version — you can manually trigger it using the workflow_dispatch event.

Configuration Instructions

Define a workflow_dispatch workflow

Create or edit a workflow file in the .gitcode/workflows/ directory and add the workflow_dispatch trigger event:

# .gitcode/workflows/manual-deploy.yml
name: Manual Deploy

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 only validate without deployment'
        type: string
        required: false
        default: "false"
        
stages:
  validate:
    name: Validation
    jobs:
      Check:
        name: check-version
        runs-on: [ubuntu-latest, x64, small]
        steps:
          - name: Run deploy
            run: echo "Deploy version ${{ inputs.version }} to ${{ inputs.environment }}"
          - name: Run dry
            run: echo "Dry run mode = ${{ inputs.dry-run }}"

Detailed Explanation of the inputs Field

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 supports string, boolean, choice, and number types for inputs.

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

Trigger Operation

1. Go to the Actions tab of the project.
2. Select the target workflow name on the left.
3. Click the Run workflow button on the right.
4. A form pops up, select or enter each inputs parameter, and choose the target branch.
5. Click Run to submit the trigger.

Note: Only workflows that include workflow_dispatch in the on field will display the Run workflow button.

Reference inputs in a workflow

steps:
  - run: echo "Environment = ${{ inputs.environment }}"
  - run: echo "Version = ${{ inputs.version }}"
  - if: ${{ inputs.dry-run == 'true' }}
    run: echo "This is a dry run"

The inputs context is available only in runs triggered by workflow_dispatch; referencing inputs in other triggering events will cause an error.

Common Issues

Q: Why is there no run button for the corresponding workflow on the Action page?

A: The on field of the workflow does not include the workflow_dispatch event. Please modify the .gitcode/workflows/{file}.yml file to add this trigger type.

Q: Why is there no corresponding workflow on the Action page?

A: When the on field of the workflow contains only the workflow_dispatch event, the yml file must be in the default branch to generate the corresponding workflow.

Q: Can workflow_dispatch coexist with other triggering events?

A: Yes. The on field supports multiple events:

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:
    inputs:
      environment:
        type: string

Q: How to specify a branch when triggering manually?

A: There is a branch selection dropdown in the trigger form. By default, it is set to the repository's default branch, but you can switch to any branch. Switching branches requires that the branch has a .gitcode/workflows/ file, and it will be executed based on that version.