[feat] Skip stages when the commit is not important (Analysis,WaitApproval,Wait,ScriptRun)

[t-kikuc]

What would you like to be added

• A new feature of skipping the ANALYSIS or WAIT_APPROVAL stages when the commit diff is not important.

• The configurable conditions of skipping the stage:

  • changed file path patterns (cf. GitHub Actions > paths)
  • commit message (prefix)

Why is it needed

• Some users would like to skip the ANALYSIS or WAIT_APPROVAL stages for faster and automatic deployment when the commit diff does not deserve analysis or approval.

• use cases:
  (a) When you modify only the HorizontalPodAutoscaler of K8s resources in your config repo, skip the WAIT_APPROVAL stage.
  (b) When you modify only go.mod dependencies in your source repo(not pipecd's config repo), skip the ANALYSIS stage.
  (c) Skip the WAIT_APPROVAL stage when the change in your source repo is small, but skip both the WAIT_APPROVAL and ANALYSIS stages when the change is tiny.

How to realize it

• Add the skip configuration to app.pipecd.yaml.

spec:
  pipeline:
    stages:
      # When changes are only `autoscaler.yaml` in any directory, skip this WAIT_APPROVAL.
      - name: WAIT_APPROVAL
        skip:
           paths:
              - "**/autoscaler.yaml"
      # When the commit message starts with "[skip analysis]", skip this ANALYSIS.
      - name: ANALYSIS
        skip:
            commitMessagePrefixes:
             - "[skip analysis]"

Example1. How to realize the use case (b)

1. Configure eventWatcher and pipeline in your app.pipecd.yaml.

spec:
  eventWatcher:
    - matcher:
        name: skip-analysis
      handler:
        type: GIT_UPDATE
        config:
          commitMessage: "[skip analysis] update xxx"
  pipeline:
      stages:
      - name: ANALYSIS
        skip:
            commitMessagePrefixes:
             - "[skip analysis]"

2. Let your CI publish an event named skip-analysis if only go.mod is changed.

Example2. How to realize the use case (c)

1. Configure eventWatcher and pipeline in your app.pipecd.yaml.

spec:
  eventWatcher:
    - matcher:
        name: small-change
      handler:
        type: GIT_UPDATE
        config:
          commitMessage: "[small change] update xxx"
    - matcher:
        name: tiny-change
      handler:
        type: GIT_UPDATE
        config:
          commitMessage: "[tiny change] update yyy"
  pipeline:
      stages:
      - name: WAIT_APPROVAL
        skip:
           commitMessagePrefixes:
              - "[small change]"
              - "[tiny change]"
      - name: ANALYSIS
        skip:
            commitMessagePrefixes:
             - "[tiny change]"

2. Let your CI publish an event named small-change to skip only WAIT_APPROVAL, and tiny-change to skip both WAIT_APPROVAL and ANALYSIS.

Possible Extensions

• In addition to commitMessagePrefixes, it would be better to have other options like:
  • skip.commitMessageOrBodyContains: []string
    • It skips the stage when the title or body of the commit contains words you specify.
  • skip.commitMessageOrBodyContainsCommand: bool
    • It skips the stage when the title or body of the commit contains specific commands like [skip analysis], [skip stage], etc.
    • cf. GitHub Actions > Skipping workflow runs

[t-kikuc]

[Acknowledgment]
I made this feature idea with @peaceiris, thanks!

[khanhtc1202]

I would like to add WAIT stage to the supported list, since it similar with the above 2 stages.

[t-kikuc]

I would like to add WAIT stage to the supported list, since it similar with the above 2 stages.

thanks, I agree with you and it's easily possible.

[t-kikuc]

cf. Skipping the ANALYSIS stage manually on the console is already available by:

• Add a dialog for skipping the analysis stage #3528
• Handle skipped stage by piped #3525

[peaceiris]

The SCRIPT_RUN stage is also useful if supported.

In our case, we plan to trigger an e2e testing by a script run stage. The stage should be skipped for quick rollback.

[t-kikuc]

I'll take this PR

[t-kikuc]

(c) Skip the WAIT_APPROVAL stage when the change in your source repo is small, but skip both the WAIT_APPROVAL and ANALYSIS stages when the change is tiny.

Configuration Example:
(Succeeded with #4922)

1. GitHub Actions (CI)

# Example for skipping stages with multiple events
name: skip-stage-example

on:
  workflow_dispatch:
    
jobs:
  publish-event:
    name: Notify PipeCD
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
      # Prepare a variable to judge
      - name: "Count changed files"
        run: echo "DIFF_COUNT=`git diff HEAD..HEAD~1 --name-only | wc -l`" >> $GITHUB_ENV
      # Pattern-A
      - name: "Register an event 'change-XS' to skip WAIT_APPROVAL and ANALYSIS stages"
        uses: pipe-cd/actions-event-register@v1
        if : env.DIFF_COUNT == 1
        with:
          api-address: ${{ secrets.PIPECD_API_ADDRESS }}
          api-key: ${{ secrets.PIPECD_PLAN_PREVIEW_API_KEY }}
          event-name: change-XS # important
          labels: app=foo,env=dev
          data: ${{ github.sha }} # Any data
          pipectl-version: v0.47.2
      # Pattern-B
      - name: "Register an event 'change-S' to skip only ANALYSIS stage"
        uses: pipe-cd/actions-event-register@v1
        if : env.DIFF_COUNT == 2
        with:
          api-address: ${{ secrets.PIPECD_API_ADDRESS }}
          api-key: ${{ secrets.PIPECD_PLAN_PREVIEW_API_KEY }}
          event-name: change-S # important
          labels: app=foo,env=dev
          data: ${{ github.sha }} # Any data
          pipectl-version: v0.47.2

2. app.pipecd.yaml

apiVersion: pipecd.dev/v1beta1
kind: KubernetesApp
spec:
  name: skip-stage-example
  eventWatcher:
    - matcher:
        name: change-S # Any name
        labels:
          app: foo
          env: dev
      handler:
        type: GIT_UPDATE
        config: 
          commitMessage: "[change-s] update xxx" # Any message
          replacements:
            - file: deployment.yaml # Any file
              yamlField: $.metadata.labels.gitsha # Any field
    - matcher:
        name: change-XS # Any name
        labels:
          app: foo
          env: dev
      handler:
        type: GIT_UPDATE
        config:
          commitMessage: "[change-xs] update yyy" # Any message
          replacements:
            - file: deployment.yaml # Any file
              yamlField: $.metadata.labels.gitsha # Any field

  pipeline:
    stages:
      - name: K8S_CANARY_ROLLOUT
        with:
          replicas: 10%
      - name: WAIT_APPROVAL
        with:
          skipOn:
            commitMessagePrefixes:
              - "[change-s]"
              - "[change-xs]"
          # ...
      - name: ANALYSIS
        with:
          skipOn:
            commitMessagePrefixes:
              - "[change-xs]"
          # ...
      - name: K8S_PRIMARY_ROLLOUT
      - name: K8S_CANARY_CLEAN

[peaceiris]

Amazing magic!