Understand what project namespaces are, how they organize projects by user or group, and why namespaces matter for project management and build processes.

Table of Contents

1. What is a Project Namespace?
2. Namespace Ownership: User vs Group
3. How Projects are Organized in a Namespace
4. Impact of Namespaces on Project Builds and Usage
5. Managing Namespaces
6. Best Practices
7. Glossary

---

What is a Project Namespace?

A namespace is a logical container or scope that groups a set of projects under a common owner. It acts like a folder or space that isolates projects and defines their context within your platform.

Instead of just having standalone projects, namespaces help organize projects by their owner or team, enabling better access control, billing, and resource sharing.

---

Namespace Ownership: User vs Group

Namespaces can be owned by:

• Individual Users: A personal namespace holding projects owned by a single user.
• Groups or Organizations: A shared namespace containing projects managed by multiple members.

For example:

• User alice has projects under the namespace alice.
• Team dev-team has projects under the namespace dev-team.

---

How Projects are Organized in a Namespace

Each project name must be unique within its namespace but can be repeated across different namespaces.

Full project identification is usually by the composite:

{namespace}/{project-name}

Examples:

• alice/my-cool-app
• dev-team/backend-service

This means two projects with the same name can coexist as long as they are in different namespaces.

---

Impact of Namespaces on Project Builds and Usage

Namespaces influence build processes and usage patterns in several ways:

• Shared Resources: Projects within a namespace can share build caches, environment variables, and secrets.
• Access Control: Permissions are managed at the namespace level, controlling who can view or modify projects inside.
• Billing: Usage costs can be aggregated and billed per namespace.
• Dependency Management: Some systems support inter-project dependencies within the same namespace, enabling complex build pipelines.
• Naming Collision Prevention: Namespace separation prevents naming conflicts across the entire platform.

---

Managing Namespaces

Users can:

• Create or join namespaces (groups or teams).
• Transfer projects between namespaces if permissions allow.
• View aggregated analytics or billing by namespace.
• Configure namespace-wide settings like default environment variables or CI/CD pipelines.

---

Best Practices

• Enforce unique project names per namespace.
• Use namespaces to model organizational structure (teams, departments).
• Apply consistent permissions at the namespace level.
• Encourage reusing resources within namespaces for efficiency.
• Document namespaces clearly for your users to avoid confusion.

---

Glossary

• Namespace: A container grouping related projects under a single owner or group.
• Project Name: Identifier for a project unique within a namespace.
• Namespace Owner: User or group who controls the namespace.
• Build Cache: Stored intermediate build results shared between projects.
• Access Control: Permissions managing who can access or modify projects.

---

Namespaces provide a scalable way to organize and control projects on your platform, enabling clearer ownership, better resource sharing, and more efficient build workflows.