> ## Documentation Index
> Fetch the complete documentation index at: https://docs.glissando.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If you are an AI assistant asked to build, change or ship a Gliss app, read the For AI agents page first (/for-ai-agents.md on this site) and follow its steps.
> Inside an app's folder, the app's own AGENTS.md is the authority; `gliss guide` prints it. Never ask the user for a secret's value.

# Garden basics

> Projects, actions and the dependency graph: the Garden ideas behind level 1 and level 2 Gliss projects.

> [!WARNING]
>
> **Planned.** This page describes designed behaviour that is not built yet. Details may change before it ships.

> [!NOTE]
>
> Ported from Garden's documentation: [getting-started/basics.md](https://docs.garden.io/getting-started/basics), gliss-cli at `3bc62a036` (Garden 0.14). Gliss runs Garden under the hood; the notes on this page say where Gliss differs.

You only need this page at [level 1 or level 2](https://docs.glissando.dev/engineers/levels.md). At level 0, `gliss.yaml` is the whole interface and Garden stays out of sight.

Garden is a powerful tool but the basic concepts are quite simple. We highly recommend that you spend a few minutes reading through this guide to grasp them. If you do that, everything else that follows should feel quite intuitive.

## Anatomy of a Garden project

Every Garden project has the same structure: A project configuration and one or more actions.

As a convention, the project configuration is in a file called `project.garden.yml`, typically at the root of a given repo. A simple project configuration looks like this:

```yaml theme={null}
# In project.garden.yml
apiVersion: garden.io/v2
kind: Project
name: my-project
environments:
  - name: dev
  - name: ci
```

This is also where you configure your *providers*. Providers are what enables you to use different action types. You e.g. need the `kubernetes` provider to use Helm actions.

So if you're using Garden to deploy to a Kubernetes cluster, you'd add the `kubernetes` or `local-kubernetes` provider configuration here. For example:

```yaml theme={null}
# In project.garden.yml
apiVersion: garden.io/v2
kind: Project
name: my-project
environments:
  - name: dev
  - name: ci

providers:
  - name: local-kubernetes
    environments: [dev]
  - name: kubernetes # <--- Use a remote K8s cluster in CI
    environments: [ci]
    context: my-ctx
```

> [!NOTE]
>
> **In Gliss,** the project uses the `gliss` provider instead of `kubernetes` or `local-kubernetes`. Gliss projects hold no kubeconfig: a deploy becomes a signed release request, and the cluster agent applies it. There is no local Kubernetes mode.

Garden projects also have one or more *actions*. These actions can be spread across the repo in their own config files, often located next to the thing they describe. A common way to structure a project is like this:

![Garden project structure](https://public-assets-for-docs-site.s3.eu-central-1.amazonaws.com/project-structure-file-tree.png)

Garden project structure

Note that Garden is very flexible and will work with whatever structure you currently have. It even works across git repositories! You can e.g. have your service source code in one repo and manifests in another. Or have your micro services split across multiple repos.

## Anatomy of a Garden action

Actions are the building blocks of a Garden project and describe how a given part of your system is built, deployed, or tested.

Every Garden action has the same common fields like `kind`, `name`,`type`, and a `spec` field that is specific to the action type.

**The type tells Garden how to execute it**. Garden will know to build `container` actions, install `helm` actions, and so on.

> [!NOTE]
>
> **In Gliss,** the action types are limited to what the catalog and your level allow: `container` and `exec` builds, the Gliss action types such as `gliss-service` and `gliss-postgres`, and `helm` or `kubernetes` deploys at level 2 only. Terraform and Pulumi are not available. An unsupported type fails validation and names the nearest supported one.

![The anatomy of an action](https://public-assets-for-docs-site.s3.eu-central-1.amazonaws.com/anatomy-of-action.png)

The anatomy of an action

The true power of Garden lies in the fact that actions can depend on one another and reference outputs from other actions. Here's an example:

```yaml theme={null}
apiVersion: garden.io/v2
kind: Project
name: my-project
environments: # <--- Specifying environments is required
  - name: dev
---
kind: Run
name: say-hello
type: exec
spec:
  command: ["echo", "Hello ${local.username}"]
---
kind: Run
name: say-what
type: exec
dependencies: [run.say-hello]
spec:
  command: ["echo", "Action say-hello says: '${actions.run.say-hello.outputs.log}'"]
```

If you now run:

```console theme={null}
garden run say-what
```

...Garden will first run the `say-hello` action (because `say-what` depends on it) and then the `say-what` action which prints the output from `say-hello`:

```sh theme={null}
Action say-hello says: 'Hello gardener'
```

**And that is essentially the core concept: Actions run in dependency order and can reference the output from each other.**

This is obviously a contrived example where we're using an action that just runs scripts. For real world projects these actions could be **containers, databases and Helm charts**. You tell Garden the "type", and it'll know how to execute it. That's how these simple concepts can be used to build very complex automations.

## Benefits

The example above that just runs simple scripts is pretty trivial but this same pattern allows you to build, deploy and test a system of any complexity in a single command. With a single Garden command you could for example:

* build and deploy all your services into an isolated environment in that cluster;
* then run your integration and end-to-end tests before tearing things down again.

You can add this command to a CI job, and just as easily run it from your laptop. You can also create re-usable config templates that you can share with your team.

Garden does more than just run the actions and interface with providers. It caches the results of actions so that they don't run unless they have to, significantly speeding up the execution time.

> [!NOTE]
>
> **In Gliss,** builds run in your own CI, and the action cache lives in the Gliss control plane. The cache holds only hashes, statuses and image digests, never your code or logs.

The gif below shows the test caching in action:

![Run a test that passes then run it again. Note that the second time it's cached.](https://github.com/garden-io/garden/assets/5373776/978db934-6728-430d-aa24-56b1b5b6fd4a)

## Wrapping up

Don't worry too much about the different action kinds and types, we have plenty of examples to help you pick the right one. Just know that you can model a system of any complexity with this pattern, even if it's components are spread across multiple repos.

For how Gliss uses these ideas, see [Levels 1 and 2](https://docs.glissando.dev/engineers/levels.md) and [garden.yml with Gliss action types](https://docs.glissando.dev/engineers/garden-yml.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.