GitHub Actions Workflows API

openapi: 3.1.0
info:
  title: GitHub Actions Artifacts Workflows API
  description: REST API for managing GitHub Actions workflows, runs, artifacts, secrets, runners, caches, variables, permissions, and OIDC.
  version: 1.0.0
  contact:
    name: GitHub Support
    url: https://support.github.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://api.github.com
  description: GitHub REST API
security:
- bearerAuth: []
- personalAccessToken: []
tags:
- name: Workflows
  description: Manage workflow files and workflow runs
paths:
  /repos/{owner}/{repo}/actions/workflows:
    get:
      operationId: listRepoWorkflows
      summary: Github Actions List Repository Workflows
      description: Lists the workflows in a repository. Anyone with read access to the repository can use this endpoint.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/perPage'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Successfully retrieved workflows
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_count:
                    type: integer
                  workflows:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workflow'
              examples:
                Listrepoworkflows200Example:
                  summary: Default listRepoWorkflows 200 response
                  x-microcks-default: true
                  value:
                    total_count: 10
                    workflows:
                    - id: abc123
                      node_id: '500123'
                      name: Example Title
                      path: example_value
                      state: active
                      created_at: '2026-01-15T10:30:00Z'
                      updated_at: '2026-01-15T10:30:00Z'
                      url: https://www.example.com
                      html_url: https://www.example.com
                      badge_url: https://www.example.com
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/actions/workflows/{workflow_id}:
    get:
      operationId: getWorkflow
      summary: Github Actions Get a Workflow
      description: Gets a specific workflow. You can replace workflow_id with the workflow file name.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/workflowId'
      responses:
        '200':
          description: Successfully retrieved workflow
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
              examples:
                Getworkflow200Example:
                  summary: Default getWorkflow 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    node_id: '500123'
                    name: Example Title
                    path: example_value
                    state: active
                    created_at: '2026-01-15T10:30:00Z'
                    updated_at: '2026-01-15T10:30:00Z'
                    url: https://www.example.com
                    html_url: https://www.example.com
                    badge_url: https://www.example.com
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/actions/workflows/{workflow_id}/disable:
    put:
      operationId: disableWorkflow
      summary: Github Actions Disable a Workflow
      description: Disables a workflow and sets the state of the workflow to disabled_manually.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/workflowId'
      responses:
        '204':
          description: Successfully disabled workflow
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/actions/workflows/{workflow_id}/enable:
    put:
      operationId: enableWorkflow
      summary: Github Actions Enable a Workflow
      description: Enables a workflow and sets the state of the workflow to active.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/workflowId'
      responses:
        '204':
          description: Successfully enabled workflow
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches:
    post:
      operationId: createWorkflowDispatch
      summary: Github Actions Create a Workflow Dispatch Event
      description: Manually triggers a GitHub Actions workflow run. The workflow must be configured to support the workflow_dispatch event.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/workflowId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - ref
              properties:
                ref:
                  type: string
                  description: The git reference for the workflow. The reference can be a branch or tag name.
                inputs:
                  type: object
                  description: Input keys and values configured in the workflow file. The maximum number of properties is 10.
                  additionalProperties:
                    type: string
            examples:
              CreateworkflowdispatchRequestExample:
                summary: Default createWorkflowDispatch request
                x-microcks-default: true
                value:
                  ref: example_value
                  inputs: example_value
      responses:
        '204':
          description: Successfully dispatched workflow
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/actions/workflows/{workflow_id}/runs:
    get:
      operationId: listWorkflowRuns
      summary: Github Actions List Workflow Runs for a Workflow
      description: List all workflow runs for a workflow. You can replace workflow_id with the workflow file name.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/workflowId'
      - name: actor
        in: query
        schema:
          type: string
        example: example_value
      - name: branch
        in: query
        schema:
          type: string
        example: example_value
      - name: event
        in: query
        schema:
          type: string
        example: example_value
      - name: status
        in: query
        schema:
          type: string
          enum:
          - completed
          - action_required
          - cancelled
          - failure
          - neutral
          - skipped
          - stale
          - success
          - timed_out
          - in_progress
          - queued
          - requested
          - waiting
          - pending
        example: completed
      - $ref: '#/components/parameters/perPage'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Successfully retrieved workflow runs
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_count:
                    type: integer
                  workflow_runs:
                    type: array
                    items:
                      $ref: '#/components/schemas/WorkflowRun'
              examples:
                Listworkflowruns200Example:
                  summary: Default listWorkflowRuns 200 response
                  x-microcks-default: true
                  value:
                    total_count: 10
                    workflow_runs:
                    - id: abc123
                      name: Example Title
                      node_id: '500123'
                      head_branch: example_value
                      head_sha: example_value
                      path: example_value
                      display_title: example_value
                      run_number: 10
                      run_attempt: 10
                      event: example_value
                      status: queued
                      conclusion: success
                      workflow_id: '500123'
                      url: https://www.example.com
                      html_url: https://www.example.com
                      created_at: '2026-01-15T10:30:00Z'
                      updated_at: '2026-01-15T10:30:00Z'
                      run_started_at: '2026-01-15T10:30:00Z'
                      jobs_url: https://www.example.com
                      logs_url: https://www.example.com
                      artifacts_url: https://www.example.com
                      cancel_url: https://www.example.com
                      rerun_url: https://www.example.com
                      workflow_url: https://www.example.com
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/actions/workflows/{workflow_id}/timing:
    get:
      operationId: getWorkflowUsage
      summary: Github Actions Get Workflow Usage
      description: Gets the number of billable minutes used by a specific workflow during the current billing cycle.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/workflowId'
      responses:
        '200':
          description: Successfully retrieved workflow usage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowUsage'
              examples:
                Getworkflowusage200Example:
                  summary: Default getWorkflowUsage 200 response
                  x-microcks-default: true
                  value:
                    billable:
                      UBUNTU:
                        total_ms: 10
                      MACOS:
                        total_ms: 10
                      WINDOWS:
                        total_ms: 10
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    SimpleUser:
      type: object
      properties:
        login:
          type: string
          example: example_value
        id:
          type: integer
          example: abc123
        node_id:
          type: string
          example: '500123'
        avatar_url:
          type: string
          format: uri
          example: https://www.example.com
        url:
          type: string
          format: uri
          example: https://www.example.com
        html_url:
          type: string
          format: uri
          example: https://www.example.com
        type:
          type: string
          example: example_value
    SimpleCommit:
      type: object
      properties:
        id:
          type: string
          example: abc123
        tree_id:
          type: string
          example: '500123'
        message:
          type: string
          example: example_value
        timestamp:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        author:
          type: object
          properties:
            name:
              type: string
            email:
              type: string
              format: email
          example: example_value
        committer:
          type: object
          properties:
            name:
              type: string
            email:
              type: string
              format: email
          example: example_value
    Workflow:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier of the workflow.
          example: abc123
        node_id:
          type: string
          example: '500123'
        name:
          type: string
          description: The name of the workflow.
          example: Example Title
        path:
          type: string
          description: The path of the workflow file relative to the root of the repository.
          example: example_value
        state:
          type: string
          enum:
          - active
          - deleted
          - disabled_fork
          - disabled_inactivity
          - disabled_manually
          - unknown
          example: active
        created_at:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        url:
          type: string
          format: uri
          example: https://www.example.com
        html_url:
          type: string
          format: uri
          example: https://www.example.com
        badge_url:
          type: string
          format: uri
          example: https://www.example.com
    MinimalRepository:
      type: object
      properties:
        id:
          type: integer
          example: abc123
        node_id:
          type: string
          example: '500123'
        name:
          type: string
          example: Example Title
        full_name:
          type: string
          example: example_value
        owner:
          $ref: '#/components/schemas/SimpleUser'
        private:
          type: boolean
          example: true
        html_url:
          type: string
          format: uri
          example: https://www.example.com
        url:
          type: string
          format: uri
          example: https://www.example.com
        description:
          type: string
          nullable: true
          example: A sample description.
    WorkflowRun:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the workflow run.
          example: abc123
        name:
          type: string
          description: The name of the workflow run.
          example: Example Title
        node_id:
          type: string
          example: '500123'
        head_branch:
          type: string
          example: example_value
        head_sha:
          type: string
          description: The SHA of the head commit that points to the version of the workflow being run.
          example: example_value
        path:
          type: string
          example: example_value
        display_title:
          type: string
          description: The title of the workflow run displayed in the UI.
          example: example_value
        run_number:
          type: integer
          description: The auto incrementing run number for the workflow run.
          example: 10
        run_attempt:
          type: integer
          description: Attempt number of the run, 1 for first attempt and higher if the workflow was re-run.
          example: 10
        event:
          type: string
          description: The event that triggered the workflow run.
          example: example_value
        status:
          type: string
          enum:
          - queued
          - in_progress
          - completed
          - waiting
          - requested
          - pending
          example: queued
        conclusion:
          type: string
          nullable: true
          enum:
          - success
          - failure
          - neutral
          - cancelled
          - skipped
          - timed_out
          - action_required
          - stale
          - null
          example: success
        workflow_id:
          type: integer
          example: '500123'
        url:
          type: string
          format: uri
          example: https://www.example.com
        html_url:
          type: string
          format: uri
          example: https://www.example.com
        created_at:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        run_started_at:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        jobs_url:
          type: string
          format: uri
          example: https://www.example.com
        logs_url:
          type: string
          format: uri
          example: https://www.example.com
        artifacts_url:
          type: string
          format: uri
          example: https://www.example.com
        cancel_url:
          type: string
          format: uri
          example: https://www.example.com
        rerun_url:
          type: string
          format: uri
          example: https://www.example.com
        workflow_url:
          type: string
          format: uri
          example: https://www.example.com
        actor:
          $ref: '#/components/schemas/SimpleUser'
        triggering_actor:
          $ref: '#/components/schemas/SimpleUser'
        repository:
          $ref: '#/components/schemas/MinimalRepository'
        head_repository:
          $ref: '#/components/schemas/MinimalRepository'
        head_commit:
          $ref: '#/components/schemas/SimpleCommit'
    WorkflowUsage:
      type: object
      properties:
        billable:
          type: object
          properties:
            UBUNTU:
              type: object
              properties:
                total_ms:
                  type: integer
            MACOS:
              type: object
              properties:
                total_ms:
                  type: integer
            WINDOWS:
              type: object
              properties:
                total_ms:
                  type: integer
          example: example_value
  parameters:
    perPage:
      name: per_page
      in: query
      schema:
        type: integer
        default: 30
        maximum: 100
      description: The number of results per page (max 100).
    repo:
      name: repo
      in: path
      required: true
      schema:
        type: string
      description: The name of the repository without the .git extension.
    workflowId:
      name: workflow_id
      in: path
      required: true
      schema:
        oneOf:
        - type: integer
        - type: string
      description: The ID of the workflow or the workflow file name.
    page:
      name: page
      in: query
      schema:
        type: integer
        default: 1
      description: The page number of the results to fetch.
    owner:
      name: owner
      in: path
      required: true
      schema:
        type: string
      description: The account owner of the repository.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: GitHub personal access token or OAuth token
    personalAccessToken:
      type: http
      scheme: bearer
      description: Fine-grained personal access token with Actions permissions