{"id":118,"date":"2026-10-12T08:52:12","date_gmt":"2026-10-12T08:52:12","guid":{"rendered":"http:\/\/www.scmgalaxy.com\/tutorials\/2009\/01\/30\/writing-trigger-in-perforce\/"},"modified":"2026-10-12T08:52:12","modified_gmt":"2026-10-12T08:52:12","slug":"writing-trigger-in-perforce","status":"publish","type":"post","link":"https:\/\/www.devopsschool.com\/blog\/writing-trigger-in-perforce\/","title":{"rendered":"Perforce Triggers Guide: Types, Execution Order, and Practical Patterns"},"content":{"rendered":"\n

Originally published on 2009-01-30; fully revised and updated.<\/em><\/p>\n\n\n\n

Perforce triggers are server-side scripts that run on repository events, making them one of the strongest ways to enforce workflow policy in a centralized way. This guide distills and modernizes the concepts from the original article<\/a> so you can choose the right trigger type, understand execution order, and implement safer automation.<\/p>\n\n\n

\n
\"Perforce<\/figure>\n<\/div>\n\n\n

What a Perforce trigger is<\/h2>\n\n\n\n

A trigger is a program executed by the Perforce server when a defined event occurs. Because execution happens on the server, trigger-based checks are enforceable regardless of whether users submit via CLI, GUI, or other client integrations.<\/p>\n\n\n\n

  • Pre-submit triggers<\/strong> react to changelist submission events.<\/li>
  • Form triggers<\/strong> react to form lifecycle events (create\/edit\/save\/delete flows).<\/li><\/ul>\n\n\n\n

    Trigger types and execution points<\/h2>\n\n\n\n

    The source material describes a historical rollout: Perforce 99.1 introduced the first server-side pre-submit trigger, release 2004.2 added five more types, and release 2005.1 added the delete form trigger.<\/p>\n\n\n\n

    Trigger type<\/th>When it runs<\/th>Can inspect file content<\/th>Can modify form text<\/th>Can reject operation<\/th>Typical use<\/th><\/tr><\/thead>
    submit<\/td>After changelist creation, before file transfer<\/td>No<\/td>No<\/td>Yes<\/td>Validate changelist metadata and file relationships<\/td><\/tr>
    content<\/td>After file transfer, before commit<\/td>Yes<\/td>No<\/td>Yes<\/td>Inspect submitted content for policy checks<\/td><\/tr>
    commit<\/td>After commit completes<\/td>Yes<\/td>No<\/td>No<\/td>Start follow-on automation such as CI signals<\/td><\/tr>
    out<\/td>When a form is generated<\/td>N\/A<\/td>Yes<\/td>Yes<\/td>Prepopulate required form sections<\/td><\/tr>
    in<\/td>When a form is returned, before parse<\/td>N\/A<\/td>Yes<\/td>Yes<\/td>Normalize or validate incoming form text<\/td><\/tr>
    save<\/td>After parse, before save<\/td>N\/A<\/td>No<\/td>Used for validation\/authorization in many setups<\/td>Fine-grained policy controls on form updates<\/td><\/tr>
    delete<\/td>Before form deletion<\/td>N\/A<\/td>No<\/td>Yes<\/td>Protect important specs from deletion<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

    Triggers vs other Perforce automation contexts<\/h2>\n\n\n\n

    The original paper contrasts triggers with wrapper scripts, review daemons, and journal tailers. The main differences are enforceability, timing, and feedback behavior.<\/p>\n\n\n\n

    Context<\/th>Execution model<\/th>Enforceable across all clients<\/th>User feedback path<\/th>Best fit<\/th><\/tr><\/thead>
    Server triggers<\/td>Synchronous with server event<\/td>Yes<\/td>Direct on error<\/td>Policy gates and mandatory checks<\/td><\/tr>
    Wrapper scripts<\/td>Synchronous when wrapper is used<\/td>No<\/td>Direct on success and error<\/td>Team-local convenience workflows<\/td><\/tr>
    Review daemons<\/td>Asynchronous polling\/event processing<\/td>Yes<\/td>Indirect (logs, notifications)<\/td>Bulk or delayed post-processing<\/td><\/tr>
    Journal tailers<\/td>Asynchronous near-real-time processing<\/td>Yes<\/td>Indirect (external systems)<\/td>Broad repository event observation<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

    Trigger execution flow and ordering<\/h2>\n\n\n\n

    The source lists this execution order: out<\/strong>, in<\/strong>, save<\/strong>, submit<\/strong>, content<\/strong>, commit<\/strong>. Not every operation runs every type. For example, form lifecycle hooks apply to form operations, while submit\/content\/commit apply to changelist submission.<\/p>\n\n\n\n

    \nflowchart TD\n    A[User action in Perforce] --> B{Action type}\n    B -- Form edit --> C[Out trigger]\n    C --> D[In trigger]\n    D --> E[Save trigger]\n    E --> F[Form operation completes]\n    B -- Submit --> G[Submit trigger]\n    G --> H[Content trigger]\n    H --> I[Commit trigger]\n    I --> J[Submit completes]\n<\/pre>\n\n\n\n
    Configuring triggers in Perforce<\/h2>\n\n\n\n
    In practice, administrators define trigger entries in the server trigger table. Start by checking local syntax and supported variables in your server version.<\/p>\n\n\n
    p4 help triggers\np4 triggers<\/code><\/span><\/pre>\n\n
    Triggers:\n    require_tests submit \/\/depot\/main\/... \"python3 \/p4\/triggers\/require_tests.py %change% %user%\"<\/span>\n    check_headers content \/\/depot\/...\/*.h \"python3 \/p4\/triggers\/check_headers.py %change%\"<\/span>\n    enqueue_ci commit \/\/depot\/main\/... \"bash \/p4\/triggers\/enqueue_ci.sh %change%\"<\/span>\n    add_review_tag out change \"python3 \/p4\/triggers\/add_review_tag.py\"<\/span>\n    protect_rel_labels delete<\/span> label \"python3 \/p4\/triggers\/protect_labels.py %formname% %user%\"<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Use this as a pattern, then validate exact trigger names, form spec tokens, and substitution variables against your installed Perforce\/Helix Core documentation.<\/p>\n\n\n\n
    Exit status and error feedback<\/h3>\n\n\n\n
    Trigger success\/failure is communicated through exit code. A zero exit code allows the operation; a non-zero code blocks it (where that trigger type is blocking) and returns the error message to the user.<\/p>\n\n\n
    #!\/usr\/bin\/env bash<\/span>\nchange_id=\"$1\"<\/span>\nif<\/span> \/p4\/triggers\/validate_change.sh \"$change_id\"<\/span>; then\n  exit<\/span> 0<\/span>\nelse<\/span>\n  echo<\/span> \"Validation failed: update related test files before submit.\"<\/span> 1<\/span>>&2<\/span>\n  exit<\/span> 1<\/span>\nfi<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
    Multiple trigger entries and ordering<\/h3>\n\n\n\n
    You can define multiple triggers on the same object\/path. They run in listed order until one fails.<\/p>\n\n\n
    success1 submit \/\/... \"ruby submit_trigger.rb\"<\/span>\nfailure1 submit \/\/... \"ruby always_fails.rb\"<\/span>\nsuccess2 submit \/\/... \"ruby another_trigger.rb\"<\/span><\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
    Tagged output for form transformation<\/h3>\n\n\n\n
    The original article highlights tagged\/marshaled output as a safer alternative to ad-hoc text parsing when reading and rewriting forms.<\/p>\n\n\n
    p4 -G client -o | python3 transform_client.py | p4 -G client -i<\/code><\/span><\/pre>\n\n\n
    Common trigger use cases<\/h2>\n\n\n\n
    • Require related files to be submitted together (for example, source and tests).<\/li>
    • Enforce copyright\/banner rules in header files through content inspection.<\/li>
    • Reject zero-content deltas during submit.<\/li>
    • Signal CI\/build processing after commit without long blocking runtime.<\/li>
    • Auto-propagate integration from release branches to forward branches (with safeguards).<\/li>
    • Protect critical labels\/branches\/client specs from unauthorized form edits or deletion.<\/li><\/ul>\n\n\n\n
      Best practices and common pitfalls<\/h2>\n\n\n\n
      • Keep trigger runtime short; long-running logic should be queued to background workers.<\/li>
      • Fail with clear, actionable messages so users can self-correct quickly.<\/li>
      • Avoid brittle text parsing; prefer structured\/tagged output where available.<\/li>
      • Order triggers intentionally, because one failing trigger prevents later ones from running.<\/li>
      • Test in a non-production server first, especially for content and form-modifying hooks.<\/li>
      • Document ownership and rollback steps for every trigger script in production.<\/li><\/ul>\n\n\n\n
        References and attribution<\/h2>\n\n\n\n
        This article is based on the original DevOpsSchool post and its cited conference\/admin-guide references. Original author attribution in the source: S. Vance<\/strong> and J. Bowles<\/strong>, with references to [Baum2005], [Bowles2005], [Goldstone2005], and [Perforce2004.2].<\/p>\n","protected":false},"excerpt":{"rendered":"
        Perforce triggers let you enforce workflow rules and launch automation directly from the server. This revised guide explains trigger types, execution order, trade-offs, and practical configuration patterns.<\/p>\n","protected":false},"author":1,"featured_media":3976,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_joinchat":[],"footnotes":""},"categories":[370],"tags":[350,545,1467,2942,373,2945,2946,2941,1097,818,2939,2948,2940,2943,2973,2944,1049,2938,2947],"class_list":["post-118","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-perforce","tag-create","tag-how","tag-implement","tag-p4-triggers","tag-perforce","tag-perforce-trigger-build","tag-perforce-trigger-types","tag-perforce-triggers","tag-tips","tag-trigger","tag-trigger-in-perforce","tag-trigger-techniques","tag-trigger-types","tag-triggers-guide","tag-triggers-tips","tag-triggers-tutorial","tag-write","tag-writing-trigger","tag-writing-trigger-in-perforce"],"_links":{"self":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/118","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/comments?post=118"}],"version-history":[{"count":3,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/118\/revisions"}],"predecessor-version":[{"id":78967,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/posts\/118\/revisions\/78967"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/media\/3976"}],"wp:attachment":[{"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/media?parent=118"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/categories?post=118"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.devopsschool.com\/blog\/wp-json\/wp\/v2\/tags?post=118"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}