OpenShift BuildConfigs API

openapi: 3.1.0
info:
  version: 4.17.0
  title: openshift-rest-api BuildConfigs API
  description: 'The OpenShift REST API provides programmatic access to Red Hat OpenShift

    Container Platform resources. This specification covers the core

    OpenShift-specific API groups including Routes (route.openshift.io/v1),

    Builds (build.openshift.io/v1), DeploymentConfigs (apps.openshift.io/v1),

    and Projects (project.openshift.io/v1). These APIs extend the Kubernetes

    API with capabilities for application routing, source-to-image builds,

    deployment strategies, and multi-tenant project management.'
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  termsOfService: https://www.redhat.com/en/about/terms-use
  contact:
    name: Red Hat OpenShift Support
    url: https://access.redhat.com/support
    email: openshift-dev@redhat.com
servers:
- url: https://api.openshift.com
  description: OpenShift API Server
security:
- BearerToken: []
tags:
- name: BuildConfigs
  description: Manage build configuration templates that define how to transform source code into container images using Source, Docker, or Custom build strategies with configurable triggers.
paths:
  /apis/build.openshift.io/v1/buildconfigs:
    get:
      operationId: listBuildConfigForAllNamespaces
      summary: Openshift List Build Configs Across All Namespaces
      description: List or watch BuildConfig objects across all namespaces.
      tags:
      - BuildConfigs
      parameters:
      - $ref: '#/components/parameters/allowWatchBookmarks'
      - $ref: '#/components/parameters/continue'
      - $ref: '#/components/parameters/fieldSelector'
      - $ref: '#/components/parameters/labelSelector'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/pretty'
      - $ref: '#/components/parameters/resourceVersion'
      - $ref: '#/components/parameters/watch'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildConfigList'
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /apis/build.openshift.io/v1/namespaces/{namespace}/buildconfigs:
    get:
      operationId: listNamespacedBuildConfig
      summary: Openshift List Build Configs in a Namespace
      description: List or watch BuildConfig objects in the specified namespace.
      tags:
      - BuildConfigs
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/allowWatchBookmarks'
      - $ref: '#/components/parameters/continue'
      - $ref: '#/components/parameters/fieldSelector'
      - $ref: '#/components/parameters/labelSelector'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/pretty'
      - $ref: '#/components/parameters/resourceVersion'
      - $ref: '#/components/parameters/watch'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildConfigList'
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createNamespacedBuildConfig
      summary: Openshift Create a Build Config
      description: Create a BuildConfig in the specified namespace. A BuildConfig defines the build strategy and source to produce container images.
      tags:
      - BuildConfigs
      parameters:
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/pretty'
      - $ref: '#/components/parameters/dryRun'
      - $ref: '#/components/parameters/fieldManager'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildConfig'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildConfig'
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildConfig'
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildConfig'
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /apis/build.openshift.io/v1/namespaces/{namespace}/buildconfigs/{name}:
    get:
      operationId: readNamespacedBuildConfig
      summary: Openshift Read a Build Config
      description: Read the specified BuildConfig in the given namespace.
      tags:
      - BuildConfigs
      parameters:
      - $ref: '#/components/parameters/name'
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/pretty'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildConfig'
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: replaceNamespacedBuildConfig
      summary: Openshift Replace a Build Config
      description: Replace the specified BuildConfig in the given namespace.
      tags:
      - BuildConfigs
      parameters:
      - $ref: '#/components/parameters/name'
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/pretty'
      - $ref: '#/components/parameters/dryRun'
      - $ref: '#/components/parameters/fieldManager'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildConfig'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildConfig'
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildConfig'
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteNamespacedBuildConfig
      summary: Openshift Delete a Build Config
      description: Delete the specified BuildConfig from the given namespace.
      tags:
      - BuildConfigs
      parameters:
      - $ref: '#/components/parameters/name'
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/pretty'
      - $ref: '#/components/parameters/dryRun'
      - $ref: '#/components/parameters/gracePeriodSeconds'
      - $ref: '#/components/parameters/propagationPolicy'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /apis/build.openshift.io/v1/namespaces/{namespace}/buildconfigs/{name}/instantiate:
    post:
      operationId: createNamespacedBuildConfigInstantiate
      summary: Openshift Instantiate a Build From a Build Config
      description: Trigger a new build from the specified BuildConfig.
      tags:
      - BuildConfigs
      parameters:
      - $ref: '#/components/parameters/name'
      - $ref: '#/components/parameters/namespace'
      - $ref: '#/components/parameters/pretty'
      - $ref: '#/components/parameters/dryRun'
      - $ref: '#/components/parameters/fieldManager'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Build'
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    BuildConfigList:
      type: object
      description: A list of BuildConfig objects.
      required:
      - items
      properties:
        apiVersion:
          type: string
          default: build.openshift.io/v1
          example: example_value
        kind:
          type: string
          default: BuildConfigList
          example: example_value
        metadata:
          $ref: '#/components/schemas/ListMeta'
        items:
          type: array
          items:
            $ref: '#/components/schemas/BuildConfig'
          example: []
    DockerBuildStrategy:
      type: object
      description: Docker build strategy that uses a Dockerfile to build images.
      properties:
        from:
          $ref: '#/components/schemas/ObjectReference'
        dockerfilePath:
          type: string
          description: Path of the Dockerfile relative to the context directory.
          example: example_value
        env:
          type: array
          items:
            $ref: '#/components/schemas/EnvVar'
          example: []
        noCache:
          type: boolean
          description: If true, Docker build caching is disabled.
          example: true
        forcePull:
          type: boolean
          description: Forces a pull of the base image before the build.
          example: true
        buildArgs:
          type: array
          items:
            $ref: '#/components/schemas/EnvVar'
          description: Specifies build arguments to pass to Docker.
          example: []
    ObjectReference:
      type: object
      description: A reference to a Kubernetes object.
      properties:
        apiVersion:
          type: string
          example: example_value
        kind:
          type: string
          example: example_value
        name:
          type: string
          example: Example Title
        namespace:
          type: string
          example: example_value
    BuildSource:
      type: object
      description: Specifies the source code location and type for the build input.
      properties:
        type:
          type: string
          description: The type of source input.
          enum:
          - Git
          - Dockerfile
          - Binary
          - Image
          - None
          example: Git
        git:
          type: object
          description: Git source location.
          properties:
            uri:
              type: string
              format: uri
              description: The URL of the Git repository.
            ref:
              type: string
              description: The Git branch, tag, or commit to build.
          example: example_value
        dockerfile:
          type: string
          description: The Dockerfile content used as build input.
          example: example_value
        contextDir:
          type: string
          description: The subdirectory within the source repository used as the context for the build.
          example: example_value
        sourceSecret:
          type: object
          description: Secret holding credentials for accessing the source repository.
          properties:
            name:
              type: string
          example: example_value
    BuildOutput:
      type: object
      description: Specifies where the resulting container image is pushed.
      properties:
        to:
          $ref: '#/components/schemas/ObjectReference'
        pushSecret:
          type: object
          description: Secret holding credentials for pushing to the output registry.
          properties:
            name:
              type: string
          example: example_value
    BuildSpec:
      type: object
      description: Specification of the desired build behavior.
      properties:
        serviceAccount:
          type: string
          description: The name of the ServiceAccount to use to run the build pod.
          default: builder
          example: example_value
        source:
          $ref: '#/components/schemas/BuildSource'
        strategy:
          $ref: '#/components/schemas/BuildStrategy'
        output:
          $ref: '#/components/schemas/BuildOutput'
        resources:
          $ref: '#/components/schemas/ResourceRequirements'
        completionDeadlineSeconds:
          type: integer
          format: int64
          description: Optional duration in seconds the build may run before the system terminates it. The countdown starts from the time the build pod is scheduled.
          example: 10
        nodeSelector:
          type: object
          additionalProperties:
            type: string
          description: Selector which must match a node's labels for the build pod to be scheduled on that node.
          example: example_value
        triggeredBy:
          type: array
          description: Describes which triggers started the most recent build.
          items:
            $ref: '#/components/schemas/BuildTriggerCause'
          example: []
    ResourceRequirements:
      type: object
      description: Compute resource requirements for a container.
      properties:
        limits:
          type: object
          additionalProperties:
            type: string
          description: Maximum compute resources allowed (e.g., cpu, memory).
          example: example_value
        requests:
          type: object
          additionalProperties:
            type: string
          description: Minimum compute resources required (e.g., cpu, memory).
          example: example_value
    OwnerReference:
      type: object
      description: Contains information to identify an owning object.
      required:
      - apiVersion
      - kind
      - name
      - uid
      properties:
        apiVersion:
          type: string
          example: example_value
        kind:
          type: string
          example: example_value
        name:
          type: string
          example: Example Title
        uid:
          type: string
          example: '500123'
        controller:
          type: boolean
          example: true
        blockOwnerDeletion:
          type: boolean
          example: true
    BuildTriggerPolicy:
      type: object
      description: A policy that causes a new build to be created.
      properties:
        type:
          type: string
          description: The type of build trigger.
          enum:
          - GitHub
          - GitLab
          - Bitbucket
          - Generic
          - ImageChange
          - ConfigChange
          example: GitHub
        github:
          type: object
          properties:
            secret:
              type: string
              description: Secret value for the webhook URL.
            secretReference:
              type: object
              properties:
                name:
                  type: string
          example: example_value
        generic:
          type: object
          properties:
            secret:
              type: string
            secretReference:
              type: object
              properties:
                name:
                  type: string
            allowEnv:
              type: boolean
          example: example_value
        imageChange:
          type: object
          properties:
            from:
              $ref: '#/components/schemas/ObjectReference'
            lastTriggeredImageID:
              type: string
          example: example_value
    EnvVar:
      type: object
      description: An environment variable to set in a container.
      required:
      - name
      properties:
        name:
          type: string
          description: The environment variable name.
          example: Example Title
        value:
          type: string
          description: The environment variable value.
          example: example_value
    BuildRequest:
      type: object
      description: A request to instantiate a new build from a BuildConfig.
      properties:
        apiVersion:
          type: string
          default: build.openshift.io/v1
          example: example_value
        kind:
          type: string
          default: BuildRequest
          example: example_value
        metadata:
          $ref: '#/components/schemas/ObjectMeta'
        triggeredBy:
          type: array
          items:
            $ref: '#/components/schemas/BuildTriggerCause'
          example: []
        env:
          type: array
          items:
            $ref: '#/components/schemas/EnvVar'
          example: []
    Status:
      type: object
      description: Status is a return value for calls that do not return other objects.
      properties:
        apiVersion:
          type: string
          default: v1
          example: example_value
        kind:
          type: string
          default: Status
          example: example_value
        metadata:
          $ref: '#/components/schemas/ListMeta'
        status:
          type: string
          enum:
          - Success
          - Failure
          example: Success
        message:
          type: string
          example: example_value
        reason:
          type: string
          example: example_value
        code:
          type: integer
          format: int32
          example: 10
    BuildConfigStatus:
      type: object
      description: Status of the BuildConfig.
      properties:
        lastVersion:
          type: integer
          format: int64
          description: The version of the last build created from this config.
          example: 10
        imageChangeTriggers:
          type: array
          items:
            type: object
            properties:
              lastTriggeredImageID:
                type: string
              from:
                $ref: '#/components/schemas/ObjectReference'
          example: []
    ListMeta:
      type: object
      description: Metadata for list responses including pagination tokens.
      properties:
        selfLink:
          type: string
          example: example_value
        resourceVersion:
          type: string
          example: example_value
        continue:
          type: string
          example: example_value
        remainingItemCount:
          type: integer
          format: int64
          example: 10
    CustomBuildStrategy:
      type: object
      description: Custom build strategy that uses a custom builder image to execute an arbitrary build process.
      required:
      - from
      properties:
        from:
          $ref: '#/components/schemas/ObjectReference'
        env:
          type: array
          items:
            $ref: '#/components/schemas/EnvVar'
          example: []
        exposeDockerSocket:
          type: boolean
          description: If true, the Docker socket is exposed inside the build container.
          example: true
        forcePull:
          type: boolean
          description: Forces a pull of the custom builder image before the build.
          example: true
    BuildStrategy:
      type: object
      description: Describes how to perform the build.
      properties:
        type:
          type: string
          description: The type of build strategy.
          enum:
          - Source
          - Docker
          - Custom
          example: Source
        sourceStrategy:
          $ref: '#/components/schemas/SourceBuildStrategy'
        dockerStrategy:
          $ref: '#/components/schemas/DockerBuildStrategy'
        customStrategy:
          $ref: '#/components/schemas/CustomBuildStrategy'
    BuildConfig:
      type: object
      description: A BuildConfig defines the build strategy and source used to produce new container images. Builds can be triggered automatically by webhooks, image changes, or configuration changes.
      required:
      - spec
      properties:
        apiVersion:
          type: string
          default: build.openshift.io/v1
          example: example_value
        kind:
          type: string
          default: BuildConfig
          example: example_value
        metadata:
          $ref: '#/components/schemas/ObjectMeta'
        spec:
          $ref: '#/components/schemas/BuildConfigSpec'
        status:
          $ref: '#/components/schemas/BuildConfigStatus'
    BuildConfigSpec:
      type: object
      description: Specification of the desired BuildConfig behavior.
      properties:
        source:
          $ref: '#/components/schemas/BuildSource'
        strategy:
          $ref: '#/components/schemas/BuildStrategy'
        output:
          $ref: '#/components/schemas/BuildOutput'
        resources:
          $ref: '#/components/schemas/ResourceRequirements'
        triggers:
          type: array
          description: Triggers that cause new builds to be created.
          items:
            $ref: '#/components/schemas/BuildTriggerPolicy'
          example: []
        runPolicy:
          type: string
          description: Controls how builds from this config run concurrently.
          enum:
          - Serial
          - Parallel
          - SerialLatestOnly
          default: Serial
          example: Serial
        serviceAccount:
          type: string
          description: The ServiceAccount to run the build pod as.
          default: builder
          example: example_value
        completionDeadlineSeconds:
          type: integer
          format: int64
          description: Optional duration in seconds builds may be active before being terminated.
          example: 10
        successfulBuildsHistoryLimit:
          type: integer
          format: int32
          description: Number of successful builds to retain.
          example: 10
        failedBuildsHistoryLimit:
          type: integer
          format: int32
          description: Number of failed builds to retain.
          example: 10
        nodeSelector:
          type: object
          additionalProperties:
            type: string
          example: example_value
    SourceBuildStrategy:
      type: object
      description: Source-to-Image (S2I) build strategy that combines application source with a builder image to produce a runnable image.
      required:
      - from
      properties:
        from:
          $ref: '#/components/schemas/ObjectReference'
        env:
          type: array
          items:
            $ref: '#/components/schemas/EnvVar'
          example: []
        scripts:
          type: string
          description: URL of S2I scripts to use instead of the ones in the builder image.
          example: example_value
        incremental:
          type: boolean
          description: Attempt to perform an incremental build reusing artifacts from a prior build.
          example: true
        forcePull:
          type: boolean
          description: Overrides the default pull behavior and forces a pull of the builder image before the build.
          example: true
    BuildStatus:
      type: object
      description: Status of the build execution.
      properties:
        phase:
          type: string
          description: The current phase of the build.
          enum:
          - New
          - Pending
          - Running
          - Complete
          - Failed
          - Error
          - Cancelled
          example: New
        cancelled:
          type: boolean
          description: Whether the build was cancelled.
          example: true
        message:
          type: string
          description: Human-readable message about the build status.
          example: example_value
        reason:
          type: string
          description: Brief machine-readable reason for the build status.
          example: example_value
        startTimestamp:
          type: string
          format: date-time
          description: Timestamp when the build started running.
          example: '2026-01-15T10:30:00Z'
        completionTimestamp:
          type: string
          format: date-time
          description: Timestamp when the build completed.
          example: '2026-01-15T10:30:00Z'
        duration:
          type: integer
          format: int64
          description: Duration of the build in nanoseconds.
          example: 10
        outputDockerImageReference:
          type: string
          description: The Docker image reference of the built image.
          example: example_value
        config:
          $ref: '#/components/schemas/ObjectReference'
        output:
          type: object
          description: Build output details.
          properties:
            to:
              type: object
              properties:
                imageDigest:
                  type: string
                  description: The image digest of the pushed image.
          example: example_value
        logSnippet:
          type: string
          description: The last few lines of the build log for failed builds.
          example: example_value
    Build:
      type: object
      description: A Build represents a single execution of a build process that transforms source code into a runnable container image. Builds are created from BuildConfigs or instantiated directly.
      required:
      - spec
      properties:
        apiVersion:
          type: string
          default: build.openshift.io/v1
          example: example_value
        kind:
          type: string
          default: Build
          example: example_value
        metadata:
          $ref: '#/components/schemas/ObjectMeta'
        spec:
          $ref: '#/components/schemas/BuildSpec'
        status:
          $ref: '#/components/schemas/BuildStatus'
    BuildTriggerCause:
      type: object
      description: Records which event triggered the build.
      properties:
        message:
          type: string
          description: Short human-readable description of the trigger.
          example: example_value
    ObjectMeta:
      type: object
      description: Standard Kubernetes object metadata. Every resource includes metadata such as name, namespace, labels, and annotations.
      properties:
        name:
          type: string
          description: The name of the resource, unique within a namespace.
          example: Example Title
        namespace:
          type: string
          description: The namespace in which the resource resides.
          example: example_value
        uid:
          type: string
          format: uuid
          description: A unique identifier for the resource set by the server.
          example: '500123'
        resourceVersion:
          type: string
          description: An opaque value representing the internal version of the object.
          example: example_value
        generation:
          type: integer
          format: int64
          description: A sequence number representing a specific generation of the desired state.
          example: 10
        creationTimestamp:
          type: string
          format: date-time
          description: Timestamp representing when the object was created.
          example: '2026-01-15T10:30:00Z'
        deletionTimestamp:
          type: string
          format: date-time
          description: Timestamp at which the object will be deleted.
          example: '2026-01-15T10:30:00Z'
        labels:
          type: object
          additionalProperties:
            type: string
          description: Map of string keys and values that can be used to organize and categorize objects.
          example: example_value
        annotations:
          type: object
          additionalProperties:
            type: string
          description: Unstructured key-value map stored with a resource for arbitrary metadata.
          example: example_value
        ownerReferences:
          type: array
          items:
            $ref: '#/components/schemas/OwnerReference'
          description: List of objects depended by this object.
          example: []
        finalizers:
          type: array
          items:
            type: string
          description: Must be empty before the object is deleted from the registry.
          example: []
  parameters:
    name:
      name: name
      in: path
      required: true
      description: Name of the resource.
      schema:
        type: string
    allowWatchBookmarks:
      name: allowWatchBookmarks
      in: query
      description: Allow watch bookmarks. Bookmarks report the resourceVersion to which the set of watched resources is synced.
      schema:
        type: boolean
    continue:
      name: continue
      in: query
      description: The continue token for paging through large result sets.
      schema:
        type: string
    watch:
      name: watch
      in: query
      description: Watch for changes to the described resources and return them as a stream of add, update, and remove notifications.
      schema:
        type: boolean
    pretty:
      name: pretty
      in: query
      description: If true, the output is pretty-printed.
      schema:
        type: string
    namespace:
      name: namespace
      in: path
      required: true
      description: The namespace (project) scope for the resource.
      schema:
        type: string
    propagationPolicy:
      name: propagationPolicy
      in: query
      description: Whether and how garbage collection will be performed. Either Orphan, Background, or Foreground.
      schema:
        type: string
        enum:
        - Orphan
        - Background
        - Foreground
    fieldManager:
      name: fieldManager
      in: query
      description: A name associated with the actor or entity making the change. Used for server-side apply to track field ownership.
      schema:
        type: string
    labelSelector:
      name: labelSelector
      in: query
      description: A selector to restrict the list of returned objects by their labels.
      schema:
        type: string
    dryRun:
      name: dryRun
      in: query
      description: When present, indicates that modifications should not be persisted. Valid values are All (all dry run stages will be processed).
      schema:
        type: string
    resourceVersion:
      name: resourceVersion
      in: query
      description: Specifies the resource version to match or list from.
      schema:
        type: string
    fieldSelector:
      name: fieldSelector
      in: query
      description: A selector to restrict the list of returned objects by their fields.
      schema:
        type: string
    gracePeriodSeconds:
      name: gracePeriodSeconds
      in: query
      description: The duration in seconds before the object should be deleted. The value zero indicates delete immediately.
      schema:
        type: integer
        format: int64
    limit:
      name: limit
      in: query
      description: Maximum number of responses to return for a list call.
      schema:
        type: integer
        format: int64
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth bearer token obtained from the OpenShift OAuth server. Use 'oc whoami -t' to retrieve a token, or configure an OAuth client for programmatic access.
externalDocs:
  description: OpenShift Container Platform REST API Reference
  url: https://docs.openshift.com/container-platform/4.17/rest_api/index.html