# Harness 3.0 Documentation
Product documentation for Harness 3.0 — the next generation of the Harness CI/CD platform. Covers Pipeline YAML v1, Connectors, Secrets, Navigation, Delegate 2.0, and more.
Built with Next.js 16, React 19, TypeScript 5.7, Tailwind CSS v4, and Radix UI.
## Getting started
```bash
npm install
npm run dev
```
Open [http://localhost:3000](http://localhost:3000) to view the site.
### Commands
| Command | Description |
|---------|-------------|
| `npm run dev` | Start dev server |
| `npm run build` | Production build |
| `npm run start` | Start production server |
| `npm run lint` | Run ESLint |
| `npx tsc --noEmit` | Type check |
## Architecture
Single-page application with client-side navigation and URL hash routing. All documentation content lives in React components — no MDX or markdown files at runtime.
```
app/
page.tsx # Root SPA — state management, URL hash routing
layout.tsx # Metadata, fonts (Inter + JetBrains Mono), dark theme
globals.css # Tailwind v4 imports, OKLCH design tokens
components/
docs/
pages/ # 45 individual page components
page-content.tsx # Routes activeItem slug → page component
sidebar-nav.tsx # Left sidebar navigation
table-of-contents.tsx # Right sticky TOC (IntersectionObserver)
header.tsx # Top header with mobile toggle
doc-breadcrumbs.tsx # Clickable breadcrumbs
search-dialog.tsx # Search dialog
code-block.tsx # Syntax-highlighted code blocks
callout.tsx # Info/warning/tip/success callout boxes
ui/ # 55 Radix UI wrapper components
lib/
docs-data.ts # Central registry — sections, items, TOC entries
utils.ts # Utility functions
hooks/ # use-mobile, use-toast
```
### Navigation
- Hash format: `#page-slug` or `#page-slug/section-id`
- `handleNavigate(sectionSlug, itemSlug)` updates state and pushes to browser history
- Cross-page links use the `onNavigate` prop passed to every page component
- All headings with `id` + `scroll-mt-20` get auto-injected copyable anchor links
### Documentation sections
| Section | Pages |
|---------|-------|
| Getting Started | Introduction, What's New, Migration Guide, Compatibility |
| Pipeline Specification | Pipeline YAML v1 Overview, Stages, Steps, Services & Environments, Infrastructure, Inputs & Variables, Expression Mapping, Advanced Features |
| Connectors | Overview, Connector Types, Managing Connectors, Configuration Reference, Troubleshooting |
| Secrets Management | Overview, Secret Types, Managing Secrets, Best Practices, Troubleshooting |
| Platform & Navigation | Navigation, Scope Selector, Settings, AI Assistant, Delegate 2.0 |
| Harness Code | Harness Code Overview |
| Step Library | Overview, CI Steps, Kubernetes & Helm, Cloud Deployment, IaCM, Integration Steps, Step Templates |
| Agents | Overview, Code Quality, Security, Developer Productivity, Building Custom Agents |
| Dashboards | Overview, HQL Reference |
| Roadmap & Status | Features in Progress, Module Status, Feature Flags |
## Adding a new page
Every new page requires changes in three files:
### 1. Register in `lib/docs-data.ts`
Add to the appropriate section in `docSections`:
```typescript
{
title: "Page Title",
slug: "page-slug",
description: "Short description",
badge: "new", // optional: "new" | "updated" | "beta" | "coming-soon"
}
```
Add TOC entries in `tocByPage`:
```typescript
"page-slug": [
{ title: "Overview", id: "overview" },
{ title: "Section Name", id: "section-id" },
],
```
### 2. Register in `components/docs/page-content.tsx`
```typescript
import { PageNamePage } from "@/components/docs/pages/page-name"
// In pageComponents record:
"page-slug": PageNamePage,
```
### 3. Create `components/docs/pages/page-name.tsx`
```tsx
import { Separator } from "@/components/ui/separator"
import { CodeBlock } from "@/components/docs/code-block"
import { Callout } from "@/components/docs/callout"
import { Badge } from "@/components/ui/badge"
import { Clock } from "lucide-react"
interface PageNamePageProps {
onNavigate?: (section: string, item: string) => void
}
export function PageNamePage({ onNavigate }: PageNamePageProps) {
return (
<div className="space-y-0">
<header id="overview" className="mt-6 scroll-mt-20">
<div className="flex items-center gap-3">
<Badge variant="secondary" className="text-xs">Category</Badge>
<div className="flex items-center gap-1.5 text-xs text-muted-foreground">
<Clock className="h-3 w-3" />
<span>Last updated Mar 2026</span>
</div>
</div>
<h1 className="mt-3 text-balance text-3xl font-bold tracking-tight text-foreground lg:text-4xl">
Page Title
</h1>
<p className="mt-3 max-w-2xl text-pretty text-base leading-relaxed text-muted-foreground lg:text-lg">
Description.
</p>
</header>
<Separator className="my-8" />
<section id="section-id" className="scroll-mt-20">
<h2 className="text-xl font-semibold text-foreground">Section Title</h2>
<p className="mt-2 text-sm leading-relaxed text-muted-foreground">Content.</p>
</section>
<Separator className="my-8" />
</div>
)
}
```
Every section must have `id` + `scroll-mt-20`. TOC entry IDs must match section `id` attributes exactly.
## Claude Code skills
This project includes Claude Code skills in `.claude/skills/` to automate common workflows:
| Skill | Usage | Description |
|-------|-------|-------------|
| `/new-doc-page` | `/new-doc-page <slug> <section> [title]` | Scaffolds a new doc page with all three registrations |
| `/validate-docs` | `/validate-docs [slug]` | Validates pages against conventions (registrations, TOC consistency, YAML schema) |
| `/doc-conventions` | `/doc-conventions [component]` | Quick reference for component patterns and styling rules |
| `/sync-branches` | `/sync-branches` | Cherry-picks commits to both `main` and `v0` branches |
## YAML conventions
All Harness pipeline YAML examples must use the v1 schema:
```yaml
pipeline:
name: Deploy App
stages:
- name: Deploy to Dev
type: deploy
service: my_service
environment:
name: dev
deploy-to: k8s_dev
steps:
- name: Rolling Deploy
with:
skip_dry_run: false
```
- No `projectIdentifier`, `orgIdentifier`, or `identifier` fields
- Flat stage types: `type: deploy` (not `type: Deployment`)
- Steps use `with:` (not `spec:`)
- Expressions: `${{ snake_case }}` (not `<+camelCase>`)
## Git workflow
Both `main` and `v0/rohangupta-dec27c78` must stay in sync:
```bash
git add <files> && git commit -m "message"
git checkout v0/rohangupta-dec27c78 && git cherry-pick <hash> && git checkout main
git push origin main && git push origin v0/rohangupta-dec27c78
```
Or use the `/sync-branches` Claude Code skill.
## Tech stack
- [Next.js 16](https://nextjs.org/) — React framework
- [React 19](https://react.dev/) — UI library
- [TypeScript 5.7](https://www.typescriptlang.org/) — Type safety
- [Tailwind CSS v4](https://tailwindcss.com/) — Utility-first CSS
- [Radix UI](https://www.radix-ui.com/) — Accessible component primitives
- [Lucide React](https://lucide.dev/) — Icons
- [Recharts](https://recharts.org/) — Dashboard charts
- [Vercel Analytics](https://vercel.com/analytics) — Usage analytics
## Pre-commit checklist
1. `npx tsc --noEmit` passes
2. New pages registered in all three locations
3. TOC entries match section `id` attributes
4. All sections use `id` + `scroll-mt-20`
5. YAML examples use v1 pipeline schema