flowmarkup:
  title: Private Git Flow Patterns
  version: 1
  documentation: |
    Demonstrates all git-backed flow reference patterns with authentication:
    github://, gitlab://, bitbucket://, and HTTPS .git// for self-hosted servers.

    Key points:
    - Credentials are engine-managed (never appear in YAML)
    - ?ref= pins to a branch, tag, or commit SHA
    - Mutable refs (branches/tags) require integrity: to prevent supply-chain attacks
    - Commit SHAs are immutable — no integrity: needed
    - The // separator is optional for github:// and bitbucket://
    - The // separator is required for gitlab:// (nested groups) and .git// URLs
    - SA-RUN-12 (INFO, non-blocking): git URL without ?ref= uses default branch

  input:
    payload: JSON
    environment: STRING
  output:
    result: JSON
  requires:
    SECRET: [deploy_token]
    SUBFLOWS: true
    CONTEXT: [correlation_id]
    SERVICES: [slack, logger]

  examples:
    production_deploy:
      _notes_: Deploy validated payload to production environment
      input:
        payload:
          service: order-service
          version: 2.3.1
          artifact: s3://builds/order-service-2.3.1.jar
        environment: production
      output:
        result:
          status: deployed
          environment: production
          version: 2.3.1
    staging_deploy:
      _notes_: Deploy to staging with different payload
      input:
        payload:
          service: payment-service
          version: 1.0.0-rc1
          artifact: s3://builds/payment-service-1.0.0-rc1.jar
        environment: staging
      output:
        result:
          status: deployed
          environment: staging
          version: 1.0.0-rc1

  vars:
    validated_data:
    env_config:
    deploy_result:

  do:
    # github:// — private org, tag ref (mutable) + integrity hash to pin content
  - run:
      _id_: validate_payload
      flow: "github://acme-corp/shared-flows/validate/check.flowmarkup.yaml?ref=v2.1.0"
      integrity: "sha256-T4dHFevlpYrh+1sNm3VJzA4f/aKKlIEF3h3kS+bQbM="
      cap:
        CONTEXT: { read: [correlation_id] }
      params: {data: =payload}
      result: {validated_data: =RESULT.data}   # object form — extract specific field
  - run:
      _id_: transform_payload
      flow: "github://acme-corp/shared-flows//transform/normalize.flowmarkup.yaml?ref=a1b2c3d4e5f6a1b2"
      cap:
        CONTEXT: { read: [correlation_id] }
      params: {data: =validated_data}
      result: normalized_payload               # string form — bind entire RESULT

    # gitlab:// — nested groups, branch ref + integrity
    # // separator is required (project path has variable depth: platform/infra/deploy-tools)
  - run:
      _id_: load_env_config
      flow: "gitlab://platform/infra/deploy-tools//config/env-loader.flowmarkup.yaml?ref=main"
      integrity: "sha256-xK9mNpQrSvWbYcZe2fHjLtRuOwMkJiHgEfDcBaZyXwV="
      cap:
        ENV: [DEPLOY_ENV, REGION]
        CONTEXT: { read: [correlation_id] }
      params: {env: =environment}
      result: {env_config: =RESULT.config}
  - run:
      _id_: run_policy_check
      flow: "bitbucket://acme-workspace/compliance-flows/policy/gate.flowmarkup.yaml?ref=v1.0.0"
      integrity: "sha256-uH3kLmNwOxPyQzRsTuVvWwXxYyZzAaBbCcDdEeFfGgHh=="
      cap:
        CONTEXT: { read: [correlation_id] }
      params: {artifact: =normalized_payload, config: =env_config}
      result: deploy_result

    # bitbucket:// — with optional // separator (equivalent to above pattern)
  - run:
      _id_: send_notification
      flow: "bitbucket://acme-workspace/notifier-flows//notify/slack.flowmarkup.yaml?ref=stable"
      integrity: "sha256-vW4lMnOxPyQzRsTuVvWwXxYyZzAaBbCcDdEeFfGgHhIi=="
      cap:
        SERVICES: [slack]
        REQUEST: ["hooks.slack.com"]
      params:
        message: "Deployment {{deploy_result}} for env {{environment}}"

    # HTTPS .git// — self-hosted GitHub Enterprise, semver tag ref + integrity
    # Use this for any on-premise git server: GHE, self-hosted GitLab, Bitbucket Server, Gitea
  - run:
      _id_: run_audit
      flow: "https://git.corp.example.com/platform/audit-flows.git//compliance/record.flowmarkup.yaml?ref=release/3.0"
      integrity: "sha256-yX5mNoOpQrRsTtUuVvWwYyZzAaBbCcDdEeFfGgHhIiJj=="
      cap:
        CONTEXT: { read: [correlation_id] }
        SECRET: [deploy_token]
        REQUEST: ["audit.corp.example.com"]
      params:
        correlation_id: =CONTEXT.correlation_id
        status: =deploy_result

    # github:// — no ?ref= intentionally (always-latest internal utility, SA-RUN-12 info non-blocking)
    # This pattern is valid when you deliberately want the latest version of a low-risk utility.
    # WARNING: Production flows MUST include integrity: hash for supply-chain protection
  - run:
      _id_: log_completion
      flow: "github://acme-corp/shared-flows/util/log-event.flowmarkup.yaml"
      integrity: sha256-a4f0d7b25e1c9836f2d08ae7c3b54e6f19d2a0c8b7e3f15d946a82c0e1b73f49  # illustrative; compute from actual flow content
      cap:
        SERVICES: [logger]
        CONTEXT: { read: [correlation_id] }
      params: {event: =deploy_result}
  - return:
      _id_: return_result
      result: =deploy_result
