GitHub Actions Dispatch and Track a Workflow Run

arazzo: 1.0.1
info:
  title: GitHub Actions Dispatch and Track a Workflow Run
  summary: Manually dispatch a workflow, find the run it created, poll until it completes, then list its jobs.
  description: >-
    The canonical end-to-end automation pattern for GitHub Actions. The workflow
    triggers a workflow_dispatch event, lists the recent runs for that workflow
    to discover the run that was just created, polls the run until it reaches a
    terminal status, and finally enumerates the jobs that executed. Every step
    spells out its request inline so the flow can be read and executed without
    opening the underlying OpenAPI description.
  version: 1.0.0
  x-realizes-capability-ids:
  - BC-4210.10
  x-capability-derivation:
    method: 'deterministic join: sourceDescriptions -> per-tag OpenAPI -> tag/capability edge. No classification at this step.'
    min_confidence: 0.7
    sources:
    - capability_id: BC-4210.10
      capability_name: Continuous Integration Management
      spec: github-actions-workflows-api-openapi.yml
      confidence: 0.85
    model: Turbo EA Capabilities by Vincent Verdet — Turbo EA, https://github.com/vincentmakes/turbo-ea-capabilities, CC BY 4.0
sourceDescriptions:
- name: jobsApi
  url: ../openapi/github-actions-jobs-api-openapi.yml
  type: openapi
- name: workflowRunsApi
  url: ../openapi/github-actions-workflow-runs-api-openapi.yml
  type: openapi
- name: workflowsApi
  url: ../openapi/github-actions-workflows-api-openapi.yml
  type: openapi
workflows:
- workflowId: dispatch-and-track-run
  summary: Dispatch a workflow and follow the resulting run to completion.
  description: >-
    Triggers a workflow_dispatch event on the named workflow, lists the
    workflow's runs to capture the newest run id, polls that run until its
    status is completed, and then lists the jobs that ran.
  inputs:
    type: object
    required:
    - accessToken
    - owner
    - repo
    - workflowId
    - ref
    properties:
      accessToken:
        type: string
        description: GitHub bearer token (PAT or OAuth) with Actions write access.
      owner:
        type: string
        description: The account owner of the repository.
      repo:
        type: string
        description: The name of the repository without the .git extension.
      workflowId:
        type: string
        description: The workflow id or workflow file name (e.g. ci.yml).
      ref:
        type: string
        description: The git branch or tag the workflow should run against.
      inputs:
        type: object
        description: Optional workflow_dispatch input key/value pairs.
  steps:
  - stepId: dispatchWorkflow
    description: >-
      Trigger the workflow_dispatch event for the named workflow on the supplied
      git ref. Returns 204 with no body on success.
    operationId: createWorkflowDispatch
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    - name: owner
      in: path
      value: $inputs.owner
    - name: repo
      in: path
      value: $inputs.repo
    - name: workflow_id
      in: path
      value: $inputs.workflowId
    requestBody:
      contentType: application/json
      payload:
        ref: $inputs.ref
        inputs: $inputs.inputs
    successCriteria:
    - condition: $statusCode == 204
  - stepId: findRun
    description: >-
      List the most recent runs for the workflow to capture the id of the run
      that the dispatch just created (the newest entry).
    operationId: listWorkflowRuns
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    - name: owner
      in: path
      value: $inputs.owner
    - name: repo
      in: path
      value: $inputs.repo
    - name: workflow_id
      in: path
      value: $inputs.workflowId
    - name: per_page
      in: query
      value: 1
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      runId: $response.body#/workflow_runs/0/id
      runStatus: $response.body#/workflow_runs/0/status
  - stepId: pollRun
    description: >-
      Fetch the run and check whether it has reached the terminal completed
      status. Branch back to itself while it is still in progress.
    operationId: getWorkflowRun
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    - name: owner
      in: path
      value: $inputs.owner
    - name: repo
      in: path
      value: $inputs.repo
    - name: run_id
      in: path
      value: $steps.findRun.outputs.runId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      status: $response.body#/status
      conclusion: $response.body#/conclusion
    onSuccess:
    - name: stillRunning
      type: goto
      stepId: pollRun
      criteria:
      - context: $response.body
        condition: $.status != "completed"
        type: jsonpath
    - name: runCompleted
      type: goto
      stepId: listJobs
      criteria:
      - context: $response.body
        condition: $.status == "completed"
        type: jsonpath
  - stepId: listJobs
    description: >-
      List the jobs executed by the completed run, returning the latest attempt
      for each job.
    operationId: listJobsForWorkflowRun
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    - name: owner
      in: path
      value: $inputs.owner
    - name: repo
      in: path
      value: $inputs.repo
    - name: run_id
      in: path
      value: $steps.findRun.outputs.runId
    - name: filter
      in: query
      value: latest
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      totalJobs: $response.body#/total_count
      jobs: $response.body#/jobs
  outputs:
    runId: $steps.findRun.outputs.runId
    conclusion: $steps.pollRun.outputs.conclusion
    jobs: $steps.listJobs.outputs.jobs