> For the complete documentation index, see [llms.txt](https://docs.terrakube.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.terrakube.io/2.34.0/how-it-works/run-lifecycle.md).
# Run Lifecycle
A **run** (a *job* in the API) is one execution of a [template](/2.34.0/set-up/organizations/templates.md) against a workspace. It starts from the UI, a [VCS webhook](/2.34.0/run-terraform/workspaces/webhooks.md), a [schedule](/2.34.0/run-terraform/workspaces/workspace-scheduler.md), a [run trigger](/2.34.0/run-terraform/workspaces/run-triggers.md), the [CLI](/2.34.0/run-terraform/workspaces/cli-driven-workflow.md) or the [API](/2.34.0/run-terraform/workspaces/api-driven-workflow.md).
### Status of a run
```mermaid
flowchart LR
A[pending] --> B[queue] --> C["running
(plan)"] --> D[waitingApproval] --> E[approved] --> F["running
(apply)"] --> G([completed])
C -.->|nothing to change| H([noChanges])
C -.->|a step fails| I([failed])
D -.->|discarded| J([rejected])
```
| Status | Meaning |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `pending` | Created and waiting to be admitted. |
| `queue` | Admitted and sent to an executor. |
| `running` | A step is executing. |
| `waitingApproval` | The plan is done and the template, or a soft-mandatory [policy](/2.34.0/govern/policy-enforcement-opa.md), needs a person to approve. |
| `approved` | Approved; the apply step follows. |
| `completed` | All steps finished. |
| `noChanges` | The plan found nothing to change, so there is nothing to approve or apply. |
| `failed` | A step failed, or a hard-mandatory policy blocked the run. |
| `rejected` | Someone discarded the run at approval. |
| `cancelled` | Cancelled before it finished. |
`pending`, `queue`, `running`, `approved` and `waitingApproval` are **active**: a workspace runs one job at a time, so later runs wait behind an active one. A run that is waiting for approval holds the workspace queue until someone approves, discards or cancels it.
### From click to plan
```mermaid
sequenceDiagram
autonumber
actor U as User or trigger
participant API
participant S as Scheduler
participant R as Redis
participant E as Executor
participant ST as Object storage
U->>API: create run (workspace, template)
API->>S: schedule dispatch
S->>R: take lock for this run
S->>S: workspace free? oldest eligible run?
S->>E: dispatch step
E-->>S: 202 Accepted
S->>R: release lock
Note over S,R: the lock is held only while dispatching,
never while Terraform runs
E->>ST: write plan, output
E-->>API: status, live output
API-->>U: status and logs in the UI
```
Two queues apply. Runs are serialized **per workspace**, and across the cluster they are admitted in **first-in, first-out** order, so a busy workspace never lets a newer run overtake an older eligible one, and it does not block other workspaces. If no executor is ready, the run stays `pending` and is retried; it does not fail. Runs that stay open too long are closed by [run limits](/2.34.0/getting-started/deployment/executor-log-output.md#run-limits).
### Steps in a run
A template is a list of steps. The common *Plan and Apply* template is:
```mermaid
flowchart LR
A[Plan
step 100] --> B{Policy checks}
B -->|hard violation| F([failed])
B -->|soft violation| C[Approval
step 150, if the template has one]
B -->|pass| C
C -->|approved| D[Apply
step 200]
C -->|discarded| X([rejected])
D --> E([completed])
```
Each step runs in a **fresh clone** of the repository, usually on a different executor. The apply step therefore applies the **saved plan** from the plan step. Files the plan built can be carried across with [plan artifacts](/2.34.0/run-terraform/workspaces/plan-artifacts.md). The executor's working directory and extension handling are described in [Terraform Execution Flow](/2.34.0/reference/executor/terraform-execution-flow.md).
### Output and state
* **State** is written to your storage backend through the backend configuration Terrakube generates for each run. See [Terraform State](/2.34.0/run-terraform/workspaces/terraform-state.md).
* **Logs** stream live through Redis while a step runs and are saved to storage when it ends. Final structured results survive an API outage. See [Job Output](/2.34.0/run-terraform/workspaces/job-output.md).
* **After an apply that changed state**, [run triggers](/2.34.0/run-terraform/workspaces/run-triggers.md) queue runs in dependent workspaces and [notifications](/2.34.0/run-terraform/workspaces/notifications.md) are sent.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.terrakube.io/2.34.0/how-it-works/run-lifecycle.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.