> For the complete documentation index, see [llms.txt](https://spacelift-io.gitbook.io/spacelift/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://spacelift-io.gitbook.io/spacelift/concepts/run/tracked.md). # Tracked run (deployment) Tracked runs represent the actual changes to your infrastructure caused by changes to your infrastructure definitions and/or configuration. In that sense, they can be also called deployments. Tracked runs are effectively an extension of proposed runs - instead of stopping at the [planning](/spacelift/concepts/run/proposed.md#planning) phase, they also allow you to apply the previewed changes. They are presented on the *Runs* screen, which is the main screen of the Stack view: ![](/files/-MRy2KyWkvxeAuiLoml3) Each of the tracked runs is represented by a separate element containing some information about the attempted deployment: ![](/files/-MRy3aTiJ8Yv4RizGLQf) Also worth noting is the colorful strip present on some runs - as long as the [planning](/spacelift/concepts/run/proposed.md#planning) phase was successful this visually represents the resources and outputs diff introduced by the change: ![](/files/-LuPOzB-znQxnx1_xkhe) ## Triggering tracked runs Tracked runs can be triggered in of the three ways - manually by the user, by a Git push or by a [trigger policy](/spacelift/concepts/policy/trigger-policy.md). ### Triggering manually Any account admin or stack [writer](/spacelift/concepts/policy/stack-access-policy.md) can trigger a tracked run on a stack: ![](/files/-MRy6wid4WgbO3vxPhfM) Runs triggered by individuals and [machine users](/spacelift/integrations/api.md#api-key-management) are marked accordingly: ![Run triggered by an individual](/files/-MRy7Gpkhv0JYeCjQSey) ![Run triggered by a machine user](/files/-MRy7UZ0FgBHFhdcxj3s) ### Triggering from Git events Tracked runs can also be triggered by Git push and tag events. By default, whenever a push occurs to the [tracked branch](/spacelift/concepts/stack/stack-settings.md#repository-and-branch), a tracked run is started - one for each of the affected stacks. This default behavior can be extensively customized using our [push policies](/spacelift/concepts/policy/git-push-policy.md). Runs triggered by Git push and/or tag events can are marked accordingly: ![](/files/-MRy8NtoiQtPbsOEBF0I) ### Triggering from policies Trigger policies can be used to create sophisticated workflows representing arbitrarily complex processes like staged rollouts or cascading updates. This is an advanced topic, which is described in more detail in its [dedicated section](/spacelift/concepts/policy/trigger-policy.md). But if you see something like this, be aware of the fact that a trigger policy must have been involved: ![](/files/-MRy9RJZC6No2B1KdlDT) ## Handling no-op changes If the planning phase detects no changes to the resources and outputs managed by the stack, the tracked run is considered a no-op. In that case it transitions directly from [planning](/spacelift/concepts/run/proposed.md#planning) to [finished](/spacelift/concepts/run.md#finished) state, just like a [proposed run](/spacelift/concepts/run/proposed.md). Otherwise, it will go through the [approval flow](/spacelift/concepts/run/tracked.md#approval-flow). ## Approval flow If the tracked run detects a change to its managed resources or outputs, it goes through the approval flow. This can be automated or manual. The automated flow involves a direct transition between the [planning](/spacelift/concepts/run/proposed.md#planning) and [applying](/spacelift/concepts/run/tracked.md#applying) phase, without an extra human intervention. This is a convenient but not always the safest option. Changes can be automatically applied if both these conditions are met: * [autodeploy](/spacelift/concepts/stack/stack-settings.md#autodeploy) is turned "on" for the Stack; * if [plan policies](/spacelift/concepts/policy/terraform-plan-policy.md) are attached, none of them returns any warnings; Otherwise, the change will go through the manual flow described below. ### Unconfirmed If a change is detected and human approval is required, a tracked run will transition from the [planning](/spacelift/concepts/run/proposed.md#planning) state to *unconfirmed*. At that point the worker node encrypts uploads the entire workspace to a dedicated S3 location and finishes its involvement with the run. The resulting changes are shown to the user for the final approval: ![](/files/-LuPIsWDObsuzh3NzBfv) If the user approves (confirms) the plan, the run transitions to the temporary [Confirmed](/spacelift/concepts/run/tracked.md#confirmed) state and waits for a worker node to pick it up. If the user doesn't like the plan and discards it, the run transitions to the terminal [Discarded](/spacelift/concepts/run/tracked.md#discarded) state. Unconfirmed is a *passive state* meaning no operations are performed while a run is in this state. ### Discarded Discarded state follows [Unconfirmed](/spacelift/concepts/run/tracked.md#unconfirmed) and indicates that the user did not like the changes detected by the [Planning](/spacelift/concepts/run/proposed.md#planning) phase. Discarded is a *passive state* meaning no operations are performed while a run is in this state. It's also a *terminal state* meaning that no further state can supersede it. ### Confirmed Confirmed state follows [Unconfirmed](/spacelift/concepts/run/tracked.md#unconfirmed) indicates that a user has accepted the plan generated in the Planning phase and wants to [apply](/spacelift/concepts/run/tracked.md#applying) it but no worker has picked up the job yet. This state is similar to [Queued](/spacelift/concepts/run.md#queued) in a sense that shows only temporarily until one of the workers picks up the associated job and changes the state to [Applying](/spacelift/concepts/run.md#applying). On the other hand, there is no way to [stop](/spacelift/concepts/run.md#stopped) a run once it's confirmed. Confirmed is a *passive state* meaning no operations are performed while a run is in this state. ## Applying If the run required a manual approval step, this phase is preceded by another handover ([preparing](/spacelift/concepts/run.md#preparing) phase) since the run again needs to be yielded to a worker node. This preparing phase is subtly different internally but ultimately serves the same purpose from the user perspective. Here's an example: ![](/files/-MRyEsxrJS39vbPkiiKx) This preparation phase is very unlikely to fail, but if it does (eg. the worker node becomes unavailable during the transition), the run will transition to the terminal [failed](/spacelift/concepts/run.md#failed) state. If the handover succeeds, or the run does not go through the manual approval process, the applying phase begins and attempts to deploy the changes. Here's an example: ![](/files/-MRyJHdKNWiS-BDKqhVf) ## Success criteria If the run is a [no-op](/spacelift/concepts/run/tracked.md#handling-no-op-changes) or the applying phase succeeds, the run transitions to the [finished](/spacelift/concepts/run.md#finished) state. On the other hand, if anything goes wrong, the run is marked as [failed](/spacelift/concepts/run.md#failed). ## Reporting The results of tracked runs are reported in multiple ways: * as deployments in VCS unless the change is a [no-op](/spacelift/concepts/run/tracked.md#handling-no-op-changes) - please refer to [GitHub](/spacelift/integrations/source-control/github.md) and [GitLab](/spacelift/integrations/source-control/gitlab.md) documentation for the exact details; * through [Slack notifications](/spacelift/integrations/slack.md) - if set up; * through [webhooks](/spacelift/integrations/webhooks.md) - if set up; --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://spacelift-io.gitbook.io/spacelift/concepts/run/tracked.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.