Projects and Environments
Complete guide to project creation, initialization, environment policies, settings, and access management.
A Project is the primary delivery unit in GitOpsHQ. It groups environments, tenants, workloads, releases, and a hosted Git repository into a single manageable scope. Everything you deploy flows through a project.
Project Concept
Each project encapsulates:
| Component | Purpose |
|---|---|
| Environments | Ordered deployment stages (inherited from org environments) |
| Tenants | Business customers or deployment targets linked from the org tenant registry |
| Workloads | Helm chart-based service definitions |
| Kustomize Bindings | Kustomize base assignments with per-binding overlays |
| Manifest Bindings | Raw manifest bundle assignments with per-binding overlays |
| Releases | Versioned change sets that move through the deploy workflow |
| HQ Variables | Scoped key-value configuration for templating |
| Hosted Git Repo | In-app Git repository storing all delivery manifests |
Creating a Project
Define Project Identity
Navigate to Projects (/projects) and click Create Project. Provide:
- Name: Human-readable project name (e.g., "Payment Gateway")
- Slug: URL-safe identifier (e.g.,
payment-gateway). Used in all URLs and API paths. - Description (optional): A brief description of what this project delivers.
Select Plan Features
Based on your org plan, certain features (promotion pipelines, notifications, approval policies) may be available. These can be configured later in project settings.
Project Created
The project appears in the project list at /projects. It is in an uninitialized state until the hosted Git repository and environments are set up.
Project Initialization
After creation, a project needs to be initialized before it can be used for delivery. The project detail page guides you through these steps:
Initialize Hosted Git Repository
GitOpsHQ creates a Git repository for the project. This repo stores all generated delivery manifests, user-authored overlays, and Helm values. The repo is fully managed — you interact with it through the UI, in-app editor, or API.
Set Up Environments
Project environments are inherited from the organization's environment definitions. Each project environment gets a reference to the org environment and can have project-specific policies (deploy policy, version policy, freeze state).
Configure Workloads
Add workloads by selecting Helm charts from the org chart registry. Each workload represents a deployable service unit.
Link Tenants
Link org tenants to the project. Each tenant can then be assigned to specific environments, creating the tenant-environment matrix where bindings live.
The initialization wizard tracks your progress. You can complete steps in any order, and the project detail page shows which steps are pending.
Project Detail Page
The project detail page (/projects/:slug) is the command center for a project. It surfaces all key information and provides quick access to sub-pages.
Overview Section
The overview shows at a glance:
| Metric | Description |
|---|---|
| Tenants | Count of linked tenants and their status |
| Workloads | Count of workload definitions and their chart versions |
| Bindings | Total binding count across all types (workload, kustomize, manifest) |
| Drift | Number of bindings with detected drift from desired state |
| Pending Updates | Workloads with newer chart versions available |
| Recent Activity | Latest commits, releases, and deployment events |
Quick Actions
| Action | Route | Description |
|---|---|---|
| Editor | /projects/:slug/editor | Monaco-based in-app code editor for the hosted Git repo |
| Git | /projects/:slug/git | File browser, commit history, and blame view |
| Compare | /projects/:slug/compare | Diff viewer for comparing branches or commits |
| Charts | /projects/:slug/charts | Manage chart references and versions |
| Delivery | /projects/:slug/delivery | View generated delivery outputs and sync status |
| Variables | /projects/:slug/variables | Manage HQ Variables at all scope levels |
| Settings | /projects/:slug/settings | Project configuration and policies |
Access Sub-Pages
| Sub-Page | Route | Description |
|---|---|---|
| IAM | /projects/:slug/access | Resource permissions, API keys, webhooks |
| Approvals | /projects/:slug/approvals | Pending and historical approval requests |
Environments
Environments define the ordered stages through which deployments progress. They are the backbone of the promotion pipeline.
Organization vs Project Environments
| Level | Definition | Management |
|---|---|---|
| Org Environments | Global stage definitions (e.g., dev, staging, production) | Managed in Org Settings |
| Project Environments | Inherited from org + project-specific policies | Managed in Project Settings |
Org environments define the canonical set of stages. When a project is created, it inherits these environments. Project environments then add configuration specific to this project's delivery needs.
Per-Environment Policies
Each project environment has three configurable policies:
Controls how deployments reach this environment.
| Policy | Behavior |
|---|---|
auto-deploy | Changes are deployed automatically after generation |
manual-deploy | Changes require explicit deploy action from an operator |
approval-required | Changes require approval from designated approvers before deploy |
Recommended configuration:
dev:auto-deploy(fast iteration)staging:manual-deploy(controlled validation)production:approval-required(governed releases)
Controls which chart versions are eligible for deployment.
| Policy | Behavior |
|---|---|
latest | Always use the latest chart version available in the registry |
pinned | Lock to a specific chart version; ignore newer versions |
semver-range | Accept versions matching a semver range (e.g., ^2.0.0) |
Recommended configuration:
dev:latest(always test newest)staging:semver-range(controlled updates within major version)production:pinned(explicit version control)
Environment freeze blocks all deployments to this environment.
| State | Effect |
|---|---|
| Unfrozen | Normal operations; deployments proceed according to deploy policy |
| Frozen | All deployments are blocked; release creation and promotion into this environment are rejected |
When freezing, you must provide a reason (e.g., "Holiday code freeze", "Incident investigation"). The freeze reason is visible on the environment card and in API responses.
Freezing an environment affects all tenants in that environment. There is no per-tenant freeze; it is an environment-wide lock.
Environment Ordering
Environments are ordered. This order defines the promotion direction:
You can reorder environments in the project settings. The order affects:
- Which environment a release can be promoted to (always the next in order)
- How the promotion pipeline is visualized in the UI
- The default sequence for bulk operations
Project Settings
Project settings are available at /projects/:slug/settings and organized into tabs.
General Tab
| Setting | Description |
|---|---|
| Name | Edit the project display name |
| Description | Edit the project description |
| Delete Project | Permanently delete the project and all its resources. May require approval on Enterprise plans. |
Pipeline Tab
The pipeline tab provides a visual pipeline editor built with React Flow. It defines the promotion topology:
- Which environments promote to which
- Parallel vs sequential promotion paths
- Gate conditions between stages
The visual editor allows drag-and-drop connections between environment nodes, making it easy to model complex promotion flows.
Notifications Tab (Pro)
Configure notification preferences for project events:
| Event | Channels |
|---|---|
| Release created | Slack, Discord, Microsoft Teams, Webhook |
| Deployment succeeded | Slack, Discord, Microsoft Teams, Webhook |
| Deployment failed | Slack, Discord, Microsoft Teams, Webhook |
| Approval requested | Slack, Discord, Microsoft Teams, Webhook |
| Drift detected | Slack, Discord, Microsoft Teams, Webhook |
| Environment frozen/unfrozen | Slack, Discord, Microsoft Teams, Webhook |
Escalation policies can route critical events (deployment failures, drift) to dedicated channels or on-call integrations.
IAM Tab
| Setting | Description |
|---|---|
| API Keys | Project-scoped API keys for CI/CD integration |
| Webhooks | Outbound webhook targets for project events |
| Project Environments | Per-environment cluster targeting and policy configuration |
| Resource Permissions | Who can read, write, and operate within this project |
Project Access Management
Resource Permissions
Project access is controlled through resource grants (see Organization and Governance). Common grant presets for projects:
| Preset | Typical Assignee | Actions |
|---|---|---|
project.read | Viewers, auditors | View project, environments, releases, git |
project.author | Developers | Read + edit values, commit to git, create workloads |
project.operator | DevOps engineers | Author + create releases, manage bindings, deploy |
project.approver | Tech leads, SREs | Read + approve/reject releases and promotions |
project.admin | Platform leads | Full control including settings and deletion |
API Key Management
Project-scoped API keys allow CI/CD pipelines to interact with the project without a user session:
Create API Key
Navigate to Project Settings > IAM > API Keys and create a new key. Specify a name, expiry date, and allowed actions.
Use in CI/CD
Include the API key in your pipeline configuration:
curl -X POST \
-H "Authorization: Bearer pk_01H5K..." \
-H "Content-Type: application/json" \
-d '{"environment":"staging","tenantId":"tenant_01H5K...","title":"Deploy v2.3.1"}' \
https://app.gitopshq.io/api/v2/projects/{slug}/releasesMonitor Usage
The API key list shows last-used timestamps and IP addresses. Rotate or revoke keys that are no longer needed.
Webhook Configuration
Outbound webhooks notify external systems when project events occur. Each webhook target specifies:
- URL: The endpoint to receive the webhook payload
- Events: Which events trigger the webhook
- Secret: HMAC secret for payload signature verification
- Active: Enable/disable toggle
Project Git Repository
Every project has a hosted Git repository managed by GitOpsHQ. This repo is the source of truth for all delivery configuration.
File Browser
Navigate to /projects/:slug/git to browse the repository contents. The file browser shows:
- Directory tree with file/folder navigation
- File content viewer with syntax highlighting
- Commit history per file
In-App Editor
The in-app editor (/projects/:slug/editor) is a full-featured Monaco-based code editor:
| Feature | Description |
|---|---|
| Syntax highlighting | YAML, JSON, HCL, and Helm template support |
| Schema validation | Real-time validation against Helm chart schemas |
| Multi-file editing | Open multiple files in tabs |
| Batch file writes | Commit changes to multiple files in a single operation |
| Chart scaffolding | Generate chart boilerplate from templates |
| HQ Variable insert | Quick-insert variable placeholders (e.g., {{hq.var.DB_HOST}}) |
Git Operations
| Operation | Description |
|---|---|
| Commit | Create a commit with a message (via editor or API) |
| History | View commit log with author, timestamp, and message |
| Blame (Pro) | See line-by-line attribution for any file |
| Diff | Compare any two commits or branches |
| Batch write | Write multiple files in a single atomic commit |
All changes made through the UI editor, API, or webhooks result in Git commits. The commit history is the complete audit trail of every configuration change.
Common Patterns
| Pattern | Projects | Tenants | Environments | Description |
|---|---|---|---|---|
| Single-Tenant App | 1 | 1 (default) | dev → staging → prod | One workload set, promoted through stages |
| Multi-Tenant SaaS | 1 | Many (per customer) | dev → staging → prod | Same workloads, per-tenant Helm values |
| Platform Team | Multiple | Shared across projects | Shared org environments | Independent projects, centralized governance |
Error Reference
Best Practices
- Name environments consistently across all projects. Use the org environment definitions as the single source of truth.
- Use
approval-requiredfor production. Even if your team is small, approval workflows create an audit trail and a pause point for review. - Freeze early, unfreeze explicitly. Use environment freezes during maintenance windows, holidays, and incident investigations.
- Keep project scope focused. One project per deployable application or bounded service group. Avoid monolithic projects with dozens of unrelated workloads.
- Use the visual pipeline editor to model promotion flows. It makes the deployment topology visible to the entire team.
- Rotate API keys on a regular schedule and scope them to the minimum required actions.