Builds and CI

You don't have to bring your own pipeline. Point a Component at a git repo and a build Workflow, and DevsPortal clones your source, builds a container image, pushes it to the internal registry, and generates the Workload that gets deployed — all inside the platform.

note

DevsPortal is built on the Control Plane Operator engine. Workflows run on the Control Plane Operator workflow plane (Argo Workflows by default). The occ CLI and openchoreo.dev/v1alpha1 resources below are unchanged engine internals.

Portal first, CLI second

The portal UI is the recommended path; the equivalent occ CLI commands follow for scripting.

How CI works

A Workflow is a build template your platform engineers publish and allow for a given ComponentType. You reference one from your Component, then a WorkflowRun executes it: it clones the repo, builds the image, pushes it to the Fedshi registry at https://registry.idp.fedshi.com, and produces a Workload. If your repo contains a workload.yaml descriptor, the generated Workload gets its endpoints, env vars, and dependencies from it; otherwise you get a minimal Workload with just the image.

Configure a component for CI

In the portal: in the Create Component wizard, on the Build & Deploy step choose Build from Source. Enter the repository URL, the branch, and the application path (appPath) within the repo, then pick a build Workflow from the list your ComponentType allows (for example dockerfile-builder) and fill its parameters — the Dockerfile context and path, or a buildpack's optional build env. Turn Auto Deploy on to ship each successful build to the first environment automatically. Click Create and the platform writes exactly the spec.workflow block shown below.

Or with the occ CLI, reference a build workflow in the Component's spec.workflow:

apiVersion: openchoreo.dev/v1alpha1
kind: Component
metadata:
  name: cart-api
  namespace: fedshi
spec:
  owner:
    projectName: checkout
  componentType:
    kind: ClusterComponentType
    name: deployment/service
  autoDeploy: true
  workflow:
    kind: ClusterWorkflow
    name: dockerfile-builder
    parameters:
      repository:
        url: "https://github.com/fedshi/checkout"
        revision:
          branch: "main"
        appPath: "/cart-api"
      docker:
        context: "/cart-api"
        filePath: "/cart-api/Dockerfile"

Key fields:

• workflow.name — the build workflow to use. It must be in your ComponentType's allowed list, or the component lands in a WorkflowNotAllowed state.
• workflow.parameters.repository — the repo URL, branch, and appPath (the directory within the repo to build).
• autoDeploy: true — deploys the generated Workload automatically after a successful build.

Available build workflows

Control Plane Operator ships four builders; your platform engineers may add more or restrict which a ComponentType allows. The Build & Deploy wizard step shows the workflows your ComponentType permits in its picker; to list them from the CLI, run occ clusterworkflow list.

Workflow	Builds	Builder parameters
dockerfile-builder	Any Dockerfile/Containerfile	docker.context, docker.filePath
gcp-buildpacks-builder	Go, Java, Node.js, Python, .NET	buildEnv (optional)
paketo-buildpacks-builder	Java, Node.js, Python, Go, .NET, Ruby, PHP	buildEnv (optional)
ballerina-buildpack-builder	Ballerina	buildEnv (optional)

All share the common repository parameters: repository.url, repository.revision.branch (default main), repository.revision.commit (optional pin), repository.appPath (default .), and repository.secretRef for private repos.

Trigger a build

In the portal: open the component and its Builds view, then click Run Build (or Trigger Build) to run the workflow your component already references.

Or with the occ CLI:

occ component workflow run cart-api -n fedshi -p checkout

Monitor a build

In the portal: the component's Builds view shows each run, its steps (checkout-source, build, publish-image, generate-workload-cr), live logs, and the run status. This is the easiest way to watch a build progress.

Or with the occ CLI:

occ component workflowrun list cart-api -n fedshi          # all runs for this component
occ workflowrun get <run-name> -n fedshi                   # status of one run
occ component workflow logs cart-api -n fedshi -f          # follow live build logs

The run reports conditions — WorkflowRunning, then WorkflowSucceeded or WorkflowFailed — and a status.tasks breakdown of each step (Pending/Running/Succeeded/Failed).

Auto-build on git push

Instead of triggering each build by hand, enable auto-build so pushes to the configured branch create a WorkflowRun automatically. In the portal, turn on Auto Build on the Build & Deploy step (or the component's build settings); with the CLI, set autoBuild: true:

spec:
  autoBuild: true
  autoDeploy: true
  workflow:
    kind: ClusterWorkflow
    name: dockerfile-builder
    parameters:
      repository:
        url: "https://github.com/fedshi/checkout"
        revision:
          branch: "main"
        appPath: "/cart-api"

A push triggers a build when all three match: the repository URL, the branch, and a change within the appPath. That last condition means a monorepo only rebuilds the components whose directories actually changed.

Platform setup required

Auto-build relies on a webhook your platform engineers configure once on the instance. If pushes aren't triggering builds on Fedshi, confirm with them that the webhook is wired to your repository — see the operator container registry and CI configuration.

Verify after a push — in the portal, a new run appears in the component's Builds view; or with the occ CLI:

occ workflowrun list -n fedshi          # a new run should appear
occ workflowrun logs <run-name> -n fedshi -f

Private repositories

For private repos, the build needs git credentials. DevsPortal stores them in an external secret store (OpenBao on Fedshi) and never keeps them in the control plane.

The easiest path is the console: when creating a component that uses a private repo, choose Create New Git Secret from the secret-reference field, enter a personal access token (for HTTPS) or an SSH key (for SSH URLs), and the new secret is selected automatically. You can also pre-create reusable secrets on the Secret Management page.

Declaratively, create a SecretReference and point your workflow's repository.secretRef at it:

apiVersion: openchoreo.dev/v1alpha1
kind: SecretReference
metadata:
  name: github-credentials
  namespace: fedshi
spec:
  targetPlane:
    kind: ClusterWorkflowPlane
    name: default
  template:
    type: kubernetes.io/basic-auth
  data:
    - secretKey: username
      remoteRef:
        key: secret/git/github-token
        property: username
    - secretKey: password
      remoteRef:
        key: secret/git/github-token
        property: token
  refreshInterval: 1h

workflow:
  parameters:
    repository:
      url: https://github.com/fedshi/private-repo.git
      secretRef: github-credentials
      revision:
        branch: main
      appPath: /

Auth method	Use for
Basic auth (PAT)	HTTPS URLs — https://github.com/org/repo.git
SSH key	SSH URLs — git@github.com:org/repo.git

The workload descriptor

By default a build produces a minimal Workload — just the image. To give the generated Workload endpoints, environment variables, files, and dependencies, add a workload.yaml to your application directory (the appPath you configured).

# cart-api/workload.yaml
apiVersion: openchoreo.dev/v1alpha1
metadata:
  name: cart-api
endpoints:
  - name: cart-api
    type: HTTP
    port: 8080
    basePath: /api/v1
    visibility:
      - external
    schemaFile: docs/openapi.yaml
configurations:
  env:
    - name: LOG_LEVEL
      value: info
    - name: DB_PASSWORD
      valueFrom:
        secretKeyRef:
          name: cart-db-secrets
          key: password
dependencies:
  endpoints:
    - component: shared-auth
      name: http
      visibility: namespace
      project: platform-services
      envBindings:
        address: AUTH_SERVICE_URL

The build looks for workload.yaml at the root of appPath. A typical layout:

checkout/
  cart-api/
    workload.yaml        ← descriptor
    Dockerfile
    docs/openapi.yaml    ← referenced by schemaFile

The descriptor mirrors the hand-authored Workload you'd write for a prebuilt image (see Workloads and endpoints) — the difference is the build supplies container.image for you. Endpoints, dependencies, and visibility all behave exactly as documented on the Workloads and Dependencies pages.

External CI

If you'd rather keep your existing pipeline (Jenkins, GitHub Actions, GitLab CI), choose External CI when creating the component. The component is created with no build workflow, and your pipeline creates the Workload when its build finishes by calling the DevsPortal Workload API. Your platform engineers set up the credentials and optional build-visibility integration.

Troubleshooting

Symptom	Likely cause	Fix
Component WorkflowNotAllowed	The workflow isn't in your ComponentType's allowed list	Ask your platform engineer to allow it, or use a permitted workflow
ComponentValidationFailed on a run	Missing/incorrect openchoreo.dev/project or openchoreo.dev/component labels, or a workflow mismatch	These are permanent — fix and create a new run
WorkflowPlaneNotFound	The workflow plane is temporarily unavailable	Transient; retried automatically
Push doesn't trigger a build	Webhook not wired, or push didn't touch appPath	Confirm the webhook with your platform engineer; check the changed paths

What's next

• Deploy and promote — once built, ship it across environments.
• Workloads and endpoints — the descriptor's full field reference.
• Observability — watch the built component run.