GitHub Copilot Provision Seats for Users

arazzo: 1.0.1
info:
  title: GitHub Copilot Provision Seats for Users
  summary: Check organization billing capacity, assign Copilot seats to selected users, and verify a seat was granted.
  description: >-
    A safe seat-provisioning flow for GitHub Copilot. The workflow first reads
    the organization's Copilot billing information to confirm seat management is
    enabled, then purchases seats for the supplied list of organization members,
    and finally reads back the seat assignment details for one of those users to
    confirm the seat is active. 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-4240.40
  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-4240.40
      capability_name: Subscription Modification
      spec: github-copilot-copilot-user-management-api-openapi.yml
      confidence: 0.7
    model: Turbo EA Capabilities by Vincent Verdet — Turbo EA, https://github.com/vincentmakes/turbo-ea-capabilities, CC BY 4.0
sourceDescriptions:
- name: copilotBillingApi
  url: ../openapi/github-copilot-copilot-billing-api-openapi.yml
  type: openapi
- name: copilotSeatsApi
  url: ../openapi/github-copilot-copilot-seats-api-openapi.yml
  type: openapi
- name: copilotUserManagementApi
  url: ../openapi/github-copilot-copilot-user-management-api-openapi.yml
  type: openapi
workflows:
- workflowId: provision-users
  summary: Confirm billing, assign Copilot seats to users, and verify one seat.
  description: >-
    Reads org Copilot billing to confirm seat management is active, branches to
    abort when seat management is disabled, adds seats for the supplied
    usernames, then fetches the seat detail for the verification username.
  inputs:
    type: object
    required:
    - org
    - selectedUsernames
    - verifyUsername
    properties:
      org:
        type: string
        description: The organization name (case-insensitive).
      selectedUsernames:
        type: array
        items:
          type: string
        description: GitHub usernames (org members) to assign Copilot seats to.
      verifyUsername:
        type: string
        description: A username from the list whose seat assignment is read back.
  steps:
  - stepId: getBilling
    description: >-
      Read the organization's Copilot billing information to confirm seat
      management is enabled before purchasing seats. Returns the seat breakdown
      and management setting.
    operationId: getCopilotBillingForOrganization
    parameters:
    - name: org
      in: path
      value: $inputs.org
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      seatManagementSetting: $response.body#/seat_management_setting
      totalSeats: $response.body#/seat_breakdown/total
    onSuccess:
    - name: seatManagementEnabled
      type: goto
      stepId: addUsers
      criteria:
      - context: $response.body
        condition: $.seat_management_setting != 'disabled'
        type: jsonpath
    - name: seatManagementDisabled
      type: end
      criteria:
      - context: $response.body
        condition: $.seat_management_setting == 'disabled'
        type: jsonpath
  - stepId: addUsers
    description: >-
      Purchase Copilot seats for the supplied organization members. Billing is
      applied per the organization's plan. Responds 201 with the number of new
      seats created.
    operationId: addUsersToCopilotSubscription
    parameters:
    - name: org
      in: path
      value: $inputs.org
    requestBody:
      contentType: application/json
      payload:
        selected_usernames: $inputs.selectedUsernames
    successCriteria:
    - condition: $statusCode == 201
    outputs:
      seatsCreated: $response.body#/seats_created
  - stepId: verifySeat
    description: >-
      Read the Copilot seat assignment details for one of the provisioned users
      to confirm the seat is active, including plan type and assignment origin.
    operationId: getCopilotSeatForUser
    parameters:
    - name: org
      in: path
      value: $inputs.org
    - name: username
      in: path
      value: $inputs.verifyUsername
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      createdAt: $response.body#/created_at
      planType: $response.body#/plan_type
      pendingCancellationDate: $response.body#/pending_cancellation_date
  outputs:
    seatsCreated: $steps.addUsers.outputs.seatsCreated
    verifiedPlanType: $steps.verifySeat.outputs.planType
    totalSeats: $steps.getBilling.outputs.totalSeats