Implementation Walkthrough¶

Follow this guide to stand up a production-ready Kiket deployment for a new customer. It covers repository setup, workflow definitions, sync pipelines, AI configuration, usage controls, and extension delivery with a real-world example (Acme Robotics).

1. Prerequisites¶

Kiket environment with GitHub app + Stripe credentials installed.
Redis + Sidekiq online.
Two GitHub repositories:
kiket-definitions for reusable .kiket assets.
acme-delivery (or similar) for the customer project.
Stripe price IDs verified through the Stripe plan verification workflow in the admin console.

Tip: Require pull requests for any .kiket/** changes—treat configuration as production code.

2. Create the Definitions Repository¶

Initialize the following structure:

definitions/
  release/
    .kiket/
      workflows/
      boards/
      issue_templates/
      extensions/

Add a README describing ownership and branching strategy.
Protect main and tag releases (e.g., v2025.10.15) so projects can pin versions.

Sample Workflow (release-management.yaml)¶

model_version: 1.0
workflow:
  key: release_management
  name: Release Management
  states:
    - key: backlog
      name: Backlog
      initial: true
    - key: triage
      name: Triage
    - key: in_progress
      name: In Progress
    - key: ready_for_review
      name: Ready for Review
      wip_limit: 6
    - key: qa_validation
      name: QA Validation
      wip_limit: 4
    - key: release_ready
      name: Release Ready
    - key: releasing
      name: Releasing
    - key: monitoring
      name: Monitoring
    - key: done
      name: Done
  transitions:
    - from: backlog
      to: triage
      guards:
        - type: extension
          id: release_transition_guard
    - from: triage
      to: in_progress
    - from: in_progress
      to: ready_for_review
    - from: ready_for_review
      to: qa_validation

Sample Board (release-board.yaml)¶

model_version: 1.0
board:
  key: release_default
  workflow: release_management
  views:
    - key: kanban
      type: kanban
      lanes:
        - backlog
        - triage
        - in_progress
        - ready_for_review
        - qa_validation
        - release_ready
        - releasing
        - monitoring
        - done
      settings:
        show_dependencies: true
        compact_mode: true
    - key: table
      type: table
      columns:
        - type: status
        - type: assignee
        - type: due_date
        - type: labels
    - key: calendar
      type: calendar
      due_date_field: release_window

Sample Issue Template¶

model_version: 1.0
issue_template:
  key: release_readiness
  name: Release Readiness Checklist
  issue_type: release_task
  description: >
    Track readiness criteria before promoting a release candidate.
  fields:
    - key: release_window
      type: datetime
      required: true
    - key: rollback_plan_link
      type: url
    - key: risk_level
      type: enum
      options: [low, medium, high]
      required: true
  default_custom_fields:
    owner: release_manager
    risk_level: medium

Commit and push the repository once these files exist.

3. Prepare the Customer Project Repository¶

Add storage/workflow_sources/acme-release/.kiket/ to mirror synced assets.
Provide the Kiket service account with read/write access (deploy key or GitHub App).
Document how to switch branches (the UI allows selecting main, staging, etc.).

4. Attach and Sync in Kiket¶

In Admin → Workflow Sources, add the kiket-definitions repository (path definitions/release, branch main).
Link the source to the Acme project.
Run a sync from the Workflow Sync Status card (or via the admin sync action).
Resolve any validation errors (missing model_version, duplicate keys, etc.). The sync card lists errors and retry counts.

The Workflow Sync Status card on the project board surfaces errors and retry counts.

5. Enable AI Services¶

Configure workflow metadata to point at custom prompts if needed:

workflow:
  metadata:
    task_generator_prompt: release_management

Task generation returns template-aligned issues; assignment hooks call extensions for workload balancing when available.

6. Usage Limits & Billing¶

Confirm the organization’s subscription tier in Billing → Current Subscription.
Configure quota overrides via Billing → Usage Policies when customers buy higher limits.
Remind finance teams to monitor Stripe dunning notifications (email + in-app alerts).

7. Deploy Extensions¶

Manifest¶

model_version: 1.0
extension:
  id: release_transition_guard
  name: Release Deployment Approval
  delivery:
    type: webhook
    method: POST
    url: https://hooks.acme.com/kiket/release-approvals
    headers:
      X-Kiket-Extension-Key: "{{ secrets.release_approvals_key }}"
  events:
    - workflow.transition.guard
  retries:
    max_attempts: 3
    backoff_seconds: 60

FastAPI Example¶

from fastapi import FastAPI, Header, HTTPException
from pydantic import BaseModel

SECRET = "replace-me"

class GuardPayload(BaseModel):
    event: str
    workflow: dict
    issue: dict
    transition: dict

app = FastAPI()

@app.post("/kiket/release-approvals")
def guard(payload: GuardPayload, x_kiket_extension_key: str = Header(...)):
    if x_kiket_extension_key != SECRET:
        raise HTTPException(status_code=401, detail="Unauthorized")

    approvals = payload.issue.get("approvals", [])
    has_sre = any(a["role"] == "sre_lead" and a["status"] == "approved" for a in approvals)

    if not has_sre:
        return {"status": "pending_approval", "message": "SRE approval required"}

    return {"status": "allow"}

Deploy the API (Cloud Run, ECS, etc.) and store the shared secret in Extensions → Secrets.

Test the flow 1. Transition to Release Ready without approvals → expect Pending approval. 2. Approve via the workflow approvals UI/API. 3. Retry the transition → expect success, and confirm in Admin → Extension Events (CSV export + charts).

8. Build Boards & Dashboards¶

Create the project in Kiket and pick the acme-release workflow source.
Validate Kanban/Table/Calendar views.
Add analytics widgets: usage limits, release cadence, approval latency.

9. Seed Issue Types & Templates¶

Use Admin → Issue Types to confirm release_task and any other custom types exist.
Seed starter issues through the issue template UI or by importing via the REST API (POST /api/v1/issues with the template key).

10. Deployment Checklist¶

11. Operational Practices¶

Lint .kiket assets in CI before merging.
Monitor ExtensionInvocation failures and configure alerts.
Rotate extension secrets regularly.
Stage configuration changes in a sandbox project before pushing to production.

With these steps, Acme Robotics gains a secure, automated release workflow powered by Kiket’s configuration-as-code, Vertex AI services, usage-aware billing, and customer-owned extensions.