/s2i-build Skill

Create the necessary OpenShift resources (BuildConfig, ImageStream) and trigger a Source-to-Image build on the cluster.

Prerequisites

Before running this skill, ensure:

User is logged into OpenShift cluster
Target namespace/project exists or can be created
Git repository URL is available (or will use binary build)

When to Use This Skill

Use this skill after /detect-project to build container images from source code on OpenShift using Source-to-Image. It creates BuildConfig and ImageStream resources, triggers the build, and monitors progress with log streaming.

Critical: Human-in-the-Loop Requirements

See Human-in-the-Loop Requirements for mandatory checkpoint behavior.

Workflow

Step 1: Check OpenShift Connection

Use kubernetes MCP to verify connection:

## Checking OpenShift Connection...

**Cluster:** [cluster-url from kubeconfig]
**User:** [current user]
**Current Namespace:** [current namespace]

Is this the correct cluster and namespace for the build?
- yes - Continue
- no - Let me switch context

WAIT for user confirmation before proceeding.

Step 2: Gather Build Information

Collect required information (from /detect-project or ask user):

## S2I Build Configuration

I need the following information:

| Setting | Current Value | Source |
|---------|---------------|--------|
| App Name | `[name]` | [from detect-project / folder name] |
| Git URL | `[url]` | [from .git/config / needs input] |
| Git Branch | `main` | [default] |
| S2I Builder | `[image]` | [from detect-project / needs input] |
| Namespace | `[ns]` | [from current context] |

[For Python projects only - include these rows if PYTHON_ENTRY_FILE is set]
| Entry Point | `[PYTHON_ENTRY_FILE]` | [from detect-project] |
| APP_MODULE | `[PYTHON_APP_MODULE]` | [Python only - required if entry point != app.py] |
| gunicorn | [Found / Missing] | [from detect-project] |

Please confirm these values or tell me what to change.

Python Entry Point Warning:

If PYTHON_ENTRY_FILE is NOT app.py AND PYTHON_HAS_GUNICORN is false:

## Python Configuration Issue

Your application uses `[PYTHON_ENTRY_FILE]` as entry point, but `gunicorn` is not in your requirements.

**This build will FAIL** because:
- The S2I Python builder requires `gunicorn` to use `APP_MODULE`
- Without gunicorn, it looks for `app.py` (which doesn't exist)

**Please choose:**
1. **Add gunicorn** - Add `gunicorn` to requirements.txt and retry
2. **Rename entry point** - Rename `[main.py]` to `app.py`
3. **Continue anyway** - Proceed (build will likely fail)

WAIT for user confirmation before proceeding.

To detect Git URL:

Read .git/config and extract [remote "origin"] url

Step 3: Verify Namespace

Use kubernetes MCP resources_list to check if namespace exists:

## Namespace Check

Checking if namespace `[namespace]` exists...

[If exists]
Namespace `[namespace]` exists and you have access.

[If not exists]
Namespace `[namespace]` does not exist.

Would you like me to create it? (yes/no)

WAIT for user confirmation before proceeding.

If creating namespace, use resources_create_or_update:

apiVersion: v1
kind: Namespace
metadata:
  name: [namespace]

Step 4: Create ImageStream

Show the ImageStream that will be created:

## Step 1 of 3: Create ImageStream

An ImageStream stores references to your built container images.

```yaml
apiVersion: image.openshift.io/v1
kind: ImageStream
metadata:
  name: [app-name]
  namespace: [namespace]
  labels:
    app: [app-name]
    app.kubernetes.io/name: [app-name]
spec:
  lookupPolicy:
    local: false

Proceed with creating this ImageStream? (yes/no)


**WAIT for user confirmation before proceeding.**

### Step 5: Create BuildConfig

Show the BuildConfig:

**For non-Python projects OR Python with app.py entry point:**

```markdown
## Step 2 of 3: Create BuildConfig

A BuildConfig defines how to build your application using S2I.

```yaml
apiVersion: build.openshift.io/v1
kind: BuildConfig
metadata:
  name: [app-name]
  namespace: [namespace]
  labels:
    app: [app-name]
    app.kubernetes.io/name: [app-name]
spec:
  source:
    type: Git
    git:
      uri: [git-url]
      ref: [git-branch]
  strategy:
    type: Source
    sourceStrategy:
      from:
        kind: DockerImage
        name: [builder-image]
  output:
    to:
      kind: ImageStreamTag
      name: [app-name]:latest
  triggers:
    - type: ConfigChange
    - type: ImageChange
  runPolicy: Serial

This BuildConfig will:

Pull source from: [git-url] (branch: [git-branch])
Build using S2I with: [builder-image]
Push result to: [app-name]:latest ImageStream

Proceed with creating this BuildConfig? (yes/no)


**For Python projects with non-default entry point (e.g., main.py):**

```markdown
## Step 2 of 3: Create BuildConfig

A BuildConfig defines how to build your application using S2I.

```yaml
apiVersion: build.openshift.io/v1
kind: BuildConfig
metadata:
  name: [app-name]
  namespace: [namespace]
  labels:
    app: [app-name]
    app.kubernetes.io/name: [app-name]
spec:
  source:
    type: Git
    git:
      uri: [git-url]
      ref: [git-branch]
  strategy:
    type: Source
    sourceStrategy:
      from:
        kind: DockerImage
        name: [builder-image]
      # Python S2I: Required when entry point is not app.py
      env:
        - name: APP_MODULE
          value: "[PYTHON_APP_MODULE]"  # e.g., "main:app"
  output:
    to:
      kind: ImageStreamTag
      name: [app-name]:latest
  triggers:
    - type: ConfigChange
    - type: ImageChange
  runPolicy: Serial

This BuildConfig will:

Pull source from: [git-url] (branch: [git-branch])
Build using S2I with: [builder-image]
Push result to: [app-name]:latest ImageStream

Python Entry Point Configuration:

Entry point file: [PYTHON_ENTRY_FILE]
APP_MODULE: [PYTHON_APP_MODULE]
This tells the S2I Python builder how to start your application with gunicorn.

Proceed with creating this BuildConfig? (yes/no)


**WAIT for user confirmation before proceeding.**

### Step 6: Start Build

```markdown
## Step 3 of 3: Start Build

Resources created successfully!

| Resource | Name | Status |
|----------|------|--------|
| ImageStream | [app-name] | Created |
| BuildConfig | [app-name] | Created |

**Would you like me to start a build now?** (yes/no)

(You can also trigger builds later with: oc start-build [app-name])

WAIT for user confirmation before proceeding.

If yes, create a Build resource:

apiVersion: build.openshift.io/v1
kind: Build
metadata:
  generateName: [app-name]-
  namespace: [namespace]
  labels:
    app: [app-name]
    buildconfig: [app-name]
  annotations:
    openshift.io/build-config.name: [app-name]
spec:
  serviceAccount: builder
  source:
    type: Git
    git:
      uri: [git-url]
      ref: [git-branch]
  strategy:
    type: Source
    sourceStrategy:
      from:
        kind: DockerImage
        name: [builder-image]
  output:
    to:
      kind: ImageStreamTag
      name: [app-name]:latest
  triggeredBy:
    - message: Manually triggered

Step 7: Monitor Build

Stream build logs using kubernetes MCP pod_logs:

## Build Progress

**Build:** [app-name]-1
**Status:** Running
**Phase:** [current phase]

---
[Streaming build logs here]
---

[When complete]

## Build Complete!

**Build:** [app-name]-1
**Status:** Complete
**Duration:** [X]m [Y]s
**Image:** image-registry.openshift-image-registry.svc:5000/[namespace]/[app-name]:latest

**CRITICAL: Ensure the build status is 'Complete' before proceeding to deployment.**

The image is ready for deployment.
Run `/deploy` to create Deployment, Service, and Route.

Step 8: Handle Build Failure

If build fails:

## Build Failed

**Build:** [app-name]-1
**Status:** Failed
**Phase:** [phase where it failed]

**Error:**

[Last 20 lines of build log]


**Common causes for [phase] failure:**
- [relevant troubleshooting tips]

**Options:**
1. **Debug Build** (`/debug-build`) - Full build diagnosis
   - Analyzes BuildConfig, build logs, source access, registry auth
   - Identifies root cause and suggests remediation
2. View full build logs
3. Delete failed build and retry
4. Update BuildConfig and retry
5. Cancel and troubleshoot

What would you like to do?

If user selects "Debug Build" → Invoke /debug-build skill with build name
After debugging → Offer to retry build

Dependencies

Required MCP Servers

openshift - Kubernetes/OpenShift resource access for BuildConfigs, ImageStreams, and build monitoring

Related Skills

/debug-build - Build failures (source access, dependencies, registry issues)
/deploy - After successful build, to deploy the image

Reference Documentation

docs/builder-images.md - S2I builder image selection, version mapping
docs/python-s2i-entrypoints.md - Python APP_MODULE configuration, entry point troubleshooting
docs/debugging-patterns.md - Common build error patterns and troubleshooting
docs/prerequisites.md - Required tools (oc)