Cloud Build API

openapi: 3.1.0
info:
  title: Google Cloud Build API
  description: >-
    The Cloud Build API provides programmatic access to create, manage, and
    monitor builds on Google Cloud infrastructure. It supports build triggers,
    worker pools, source repository connections, and build configuration
    management for CI/CD workflows.
  version: v1
  contact:
    name: Google Cloud Support
    url: https://cloud.google.com/build/docs/support
  termsOfService: https://cloud.google.com/terms
externalDocs:
  description: Cloud Build API Documentation
  url: https://cloud.google.com/build/docs/api/reference/rest
servers:
  - url: https://cloudbuild.googleapis.com/v1
    description: Production Server
tags:
  - name: Builds
    description: Operations for creating and managing builds
  - name: Triggers
    description: Operations for managing build triggers
  - name: WorkerPools
    description: Operations for managing worker pools
security:
  - oauth2: []
paths:
  /projects/{projectId}/builds:
    get:
      operationId: listBuilds
      summary: Google Cloud Build List builds
      description: Lists previously requested builds for a project.
      tags:
        - Builds
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/pageToken'
        - name: filter
          in: query
          description: The raw filter text to constrain the results
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBuildsResponse'
    post:
      operationId: createBuild
      summary: Google Cloud Build Create a build
      description: Starts a build with the specified configuration.
      tags:
        - Builds
      parameters:
        - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Build'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
  /projects/{projectId}/builds/{buildId}:
    get:
      operationId: getBuild
      summary: Google Cloud Build Get a build
      description: Returns information about a previously requested build.
      tags:
        - Builds
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/buildId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'
  /projects/{projectId}/builds/{buildId}:cancel:
    post:
      operationId: cancelBuild
      summary: Google Cloud Build Cancel a build
      description: Cancels a build in progress.
      tags:
        - Builds
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/buildId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'
  /projects/{projectId}/triggers:
    get:
      operationId: listTriggers
      summary: Google Cloud Build List build triggers
      description: Lists existing build triggers for a project.
      tags:
        - Triggers
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTriggersResponse'
    post:
      operationId: createTrigger
      summary: Google Cloud Build Create a build trigger
      description: Creates a new build trigger.
      tags:
        - Triggers
      parameters:
        - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildTrigger'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildTrigger'
  /projects/{projectId}/triggers/{triggerId}:
    get:
      operationId: getTrigger
      summary: Google Cloud Build Get a build trigger
      description: Returns information about a build trigger.
      tags:
        - Triggers
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/triggerId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildTrigger'
    patch:
      operationId: updateTrigger
      summary: Google Cloud Build Update a build trigger
      description: Updates a build trigger by its project ID and trigger ID.
      tags:
        - Triggers
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/triggerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildTrigger'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildTrigger'
    delete:
      operationId: deleteTrigger
      summary: Google Cloud Build Delete a build trigger
      description: Deletes a build trigger by its project ID and trigger ID.
      tags:
        - Triggers
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/triggerId'
      responses:
        '200':
          description: Successful response
  /projects/{projectId}/locations/{location}/workerPools:
    get:
      operationId: listWorkerPools
      summary: Google Cloud Build List worker pools
      description: Lists worker pools for a given project.
      tags:
        - WorkerPools
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/location'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorkerPoolsResponse'
    post:
      operationId: createWorkerPool
      summary: Google Cloud Build Create a worker pool
      description: Creates a new worker pool.
      tags:
        - WorkerPools
      parameters:
        - $ref: '#/components/parameters/projectId'
        - $ref: '#/components/parameters/location'
        - name: workerPoolId
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkerPool'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Operation'
components:
  parameters:
    projectId:
      name: projectId
      in: path
      required: true
      schema:
        type: string
    buildId:
      name: buildId
      in: path
      required: true
      schema:
        type: string
    triggerId:
      name: triggerId
      in: path
      required: true
      schema:
        type: string
    location:
      name: location
      in: path
      required: true
      schema:
        type: string
    pageSize:
      name: pageSize
      in: query
      schema:
        type: integer
    pageToken:
      name: pageToken
      in: query
      schema:
        type: string
  schemas:
    Build:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the build
        projectId:
          type: string
        status:
          type: string
          enum: [STATUS_UNKNOWN, PENDING, QUEUED, WORKING, SUCCESS, FAILURE, INTERNAL_ERROR, TIMEOUT, CANCELLED, EXPIRED]
        source:
          type: object
          properties:
            storageSource:
              type: object
              properties:
                bucket:
                  type: string
                object:
                  type: string
                generation:
                  type: string
            repoSource:
              type: object
              properties:
                projectId:
                  type: string
                repoName:
                  type: string
                branchName:
                  type: string
                tagName:
                  type: string
                commitSha:
                  type: string
        steps:
          type: array
          items:
            $ref: '#/components/schemas/BuildStep'
          description: The operations to be performed on the workspace
        results:
          type: object
          properties:
            images:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  digest:
                    type: string
            buildStepImages:
              type: array
              items:
                type: string
        createTime:
          type: string
          format: date-time
        startTime:
          type: string
          format: date-time
        finishTime:
          type: string
          format: date-time
        timeout:
          type: string
          description: Amount of time that this build should be allowed to run
        images:
          type: array
          items:
            type: string
          description: List of images to be pushed upon successful completion
        logUrl:
          type: string
          description: URL to logs for this build in Cloud Console
        substitutions:
          type: object
          additionalProperties:
            type: string
        tags:
          type: array
          items:
            type: string
    BuildStep:
      type: object
      properties:
        name:
          type: string
          description: The name of the container image for this build step
        args:
          type: array
          items:
            type: string
          description: Command-line arguments for the step's container
        dir:
          type: string
          description: Working directory to use when running the step's container
        id:
          type: string
          description: Unique identifier for the build step
        waitFor:
          type: array
          items:
            type: string
          description: The IDs of steps that must complete before this step starts
        entrypoint:
          type: string
          description: Entrypoint to use when running the step's container
        env:
          type: array
          items:
            type: string
          description: Environment variables for the step
        timeout:
          type: string
    BuildTrigger:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        disabled:
          type: boolean
        triggerTemplate:
          type: object
          properties:
            projectId:
              type: string
            repoName:
              type: string
            branchName:
              type: string
            tagName:
              type: string
        github:
          type: object
          properties:
            owner:
              type: string
            name:
              type: string
            pullRequest:
              type: object
              properties:
                branch:
                  type: string
            push:
              type: object
              properties:
                branch:
                  type: string
                tag:
                  type: string
        build:
          $ref: '#/components/schemas/Build'
        filename:
          type: string
          description: Path to the build configuration file
        substitutions:
          type: object
          additionalProperties:
            type: string
        tags:
          type: array
          items:
            type: string
        createTime:
          type: string
          format: date-time
    WorkerPool:
      type: object
      properties:
        name:
          type: string
        displayName:
          type: string
        state:
          type: string
          enum: [CREATING, RUNNING, DELETING, DELETED]
        privatePoolV1Config:
          type: object
          properties:
            workerConfig:
              type: object
              properties:
                machineType:
                  type: string
                diskSizeGb:
                  type: integer
            networkConfig:
              type: object
              properties:
                peeredNetwork:
                  type: string
                peeredNetworkIpRange:
                  type: string
        createTime:
          type: string
          format: date-time
        updateTime:
          type: string
          format: date-time
    Operation:
      type: object
      properties:
        name:
          type: string
        done:
          type: boolean
    ListBuildsResponse:
      type: object
      properties:
        builds:
          type: array
          items:
            $ref: '#/components/schemas/Build'
        nextPageToken:
          type: string
    ListTriggersResponse:
      type: object
      properties:
        triggers:
          type: array
          items:
            $ref: '#/components/schemas/BuildTrigger'
        nextPageToken:
          type: string
    ListWorkerPoolsResponse:
      type: object
      properties:
        workerPools:
          type: array
          items:
            $ref: '#/components/schemas/WorkerPool'
        nextPageToken:
          type: string
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.google.com/o/oauth2/auth
          tokenUrl: https://oauth2.googleapis.com/token
          scopes:
            https://www.googleapis.com/auth/cloud-platform: Full access to Google Cloud