Pipeline.git.commit is undocumented — useful for triggering workflows based on commit message

Feedback & Bug Reports
1

Summary

The pipeline variable pipeline.git.commit.subject is currently undocumented but functional. Request: Either officially document this variable or provide a documented alternative for commit-message-based workflow triggering.

Use case

My codebase has integration unit tests that should only be triggered manually rather than running on every commit since they are expensive. I want them to be triggered when I add the string [run-full-tests] to the commit message so that they can be triggered from the command line (rather than, e.g., approval-based workflows which require switching to the CircleCI website).

This configuration works:

workflows:
  version: 2
  expensive-tests:
    when:
      # Run expensive tests on every commit in `main`, and on every commit whose
      # subject contains "[run-full-tests]".
      or:
        - equal: [ main, << pipeline.git.branch >> ]
        - matches:
            pattern: .*\[run-full-tests\].*
            value: << pipeline.git.commit.subject >>
    jobs:
      - my-integration-tests

However, pipeline.git.commit is not mentioned anywhere in the docs. In the circleci-docs GitHub, it appeared briefly in an example in PR 9046 but it was promptly removed a month later in PR 9154.

Commit-message-based workflow triggering is a popular feature request: CCI-I-763, CCI-I-581.

1 Like