Projects

A project is the top-level container in Lucity. It groups services, environments, databases, and deployments under a single name. Source repositories are connected per-service, so a single project can pull from multiple GitHub repos.

Create a project

Creating a project is straightforward: give it a name.

mutation {
  createProject(input: {
    name: "myapp"
  }) {
    id
    name
  }
}

The project name becomes the project ID. No UUIDs, no auto-generated slugs. Just a human-readable name that makes sense. Project names are scoped to your workspace, so there's no collision risk.

Behind the scenes, Lucity creates a GitOps repository and a development environment. You then add services, each one pointing to a source repo, and deploy from there.

Understand the repository model

Every Lucity project involves two kinds of repositories:

1. Your source repos on GitHub: Lucity reads from these to build images and detect services. It never writes to them. Not a commit, not a file, not a webhook config. Your repos are sacred. Each service has its own source repo, so a project can span multiple GitHub repositories.
2. The GitOps repo (managed by Lucity): This holds Helm values for each environment. Lucity owns and manages this entirely. When you deploy, the platform updates image tags here. When you add a service, it modifies the values here.

This separation means your source repos stay clean. No platform-generated CI configs, no deployment manifests cluttering your codebase. And if you ever eject from Lucity, the GitOps repo is yours to keep.

View your projects

The dashboard shows all your projects at a glance, each one with its services, environments, and current sync status. You can drill into any project to see its service canvas, recent deployments, and environment health.

The GraphQL API gives you the same visibility programmatically:

query {
  projects {
    id
    name
    environments {
      name
      syncStatus
    }
    services {
      name
      sourceUrl
      framework
    }
  }
}

Delete a project

Deleting a project removes the GitOps repository and cleans up associated Kubernetes resources (namespaces, ArgoCD Applications, the works). This is a destructive operation.

Your source repositories on GitHub are never touched. They were read-only before and they stay exactly as they were.

See how it maps to Kubernetes

There's no magic database table tracking which projects exist. Projects are discovered through Kubernetes labels:

apiVersion: v1
kind: Namespace
metadata:
  name: myapp-production
  labels:
    lucity.dev/project: "myapp"
    lucity.dev/environment: "production"

A "project" is simply the set of namespaces carrying the lucity.dev/project label. No custom CRDs, no proprietary resources. Standard kubectl queries find everything:

kubectl get namespaces -l lucity.dev/project=myapp

This is discovery over definition. The platform doesn't maintain a mapping table. It queries Kubernetes for truth.