> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/release-orchestration/use-release-orchestration/release-orchestration-processes/process-modeling.md).

# Process Modeling

Learn how to model release processes using phases, activities, and dependencies.

Process modeling in Release Orchestration lets you define your release workflows with phases, activities, dependencies, and variables. You can create processes using AI-based generation or manual configuration to match your team's specific requirements.

### What you will learn from this topic

* How to [view processes](#view-processes) and the actions available for each
* How to [create a process](#create-a-process) from the UI
* How to [work with the process canvas](#work-with-the-process-canvas) and view execution history
* How to [create a process with Harness AI](#ai-based-process-creation)
* How a [process is structured](#process-structure) into metadata, inputs, variables, phases, activities, and dependencies
* How to [model complex release processes](#modeling-complex-release-processes) with sequential, parallel, and conditional execution
* How Harness resolves activities for [git-backed processes](#git-backed-processes)
* How Harness [syncs changes and automatically creates processes, process inputs, and activities](#sync-from-git-to-harness) when their YAML files are pushed to a connected Git repository
* How to start from a [process blueprint](#process-blueprints) for common release scenarios

### View processes <a href="#view-processes" id="view-processes"></a>

In the left navigation of the Release Orchestration module, select **Processes** to see every process defined for the project.

<figure><img src="https://478177610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwRDYqBolZUj6Rwnqx0mm%2Fuploads%2Fgit-blob-8f8095f32b0bc16610a1eca0b093a4b5ccb64c66%2Fprocess-list-view.png?alt=media" alt="Processes list page showing columns for release process name, description, store type, associated releases, created, and last updated"><figcaption></figcaption></figure>

| Column               | Description                                                                                                                                  |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Release Process Name | The process name and its identifier.                                                                                                         |
| Description          | The optional description entered when the process was created.                                                                               |
| Store Type           | Whether the process definition is **Inline** or **Remote**. Go to [Create a process](#create-a-process) for the difference.                  |
| Associated Releases  | The number of releases generated from this process, with a **View** link to see them. Shows **N.A.** when no release has been generated yet. |
| Created              | Who created the process, and when.                                                                                                           |
| Last Updated         | Who last updated the process, and when.                                                                                                      |

Select the overflow menu (**⋮**) at the end of a row to **Move to Git** or **Delete** the process.

### Create a process <a href="#create-a-process" id="create-a-process"></a>

In the left navigation of the Release Orchestration module, select **Processes**. Select **Create Process with AI** to start building the process with Harness AI, or select the dropdown next to it and select **+ Create Process** to build the process manually. Both options open the process canvas with the same **Create a Process** dialog.

<figure><img src="https://478177610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwRDYqBolZUj6Rwnqx0mm%2Fuploads%2Fgit-blob-115267dc681d2d54bcda0ae86c492bd1c6eb3125%2Fprocess-create-modal-remote.png?alt=media" alt="Create a Process dialog with Process Name, Description, and How do you want to set up your Process toggle, with Remote selected"><figcaption></figcaption></figure>

Enter a **Process Name**. Harness generates the **Id** from it. Optionally, add a **Description**. The **Process Name** is required. If you select **Start** without entering one, Harness shows a **Process Name is required** validation error.

<figure><img src="https://478177610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwRDYqBolZUj6Rwnqx0mm%2Fuploads%2Fgit-blob-a89d2956e0e6891b2b0f898f44c2b4e9df350315%2Fprocess-create-modal-inline-validation.png?alt=media" alt="Create a Process dialog showing the Process Name is required validation error, with Inline selected"><figcaption></figcaption></figure>

Under **How do you want to set up your Process?**, select how Harness stores the process definition:

* **Inline**: The process is stored in Harness. This is the default.
* **Remote**: The process is stored in your Git repository. Select a **Git Connector**, then select or enter the **Repository**, **Git Branch**, and **File Path** for the process definition.

Select **Start** to create the process and open it on the process canvas, where you build phases and activities, either manually or using Harness AI.

### Work with the process canvas <a href="#work-with-the-process-canvas" id="work-with-the-process-canvas"></a>

A process has three tabs at the top of its page: **Canvas**, **Input Store**, and **Execution History**.

The **Canvas** tab is where you build the process. Select **+ New Phase** to add a phase. Go to [Creating phases](https://developer.harness.io/release-orchestration/use-release-orchestration/release-orchestration-phases/creating-phases.md) for how to configure a phase. Each phase appears as a card showing its dependencies, owners, and an **Activities** list with an **+ Add Activity** button. A **Visual/YAML** toggle at the top switches between the visual canvas and the equivalent process YAML. Use **Save** to save your changes, **Discard** to revert them, or **Run** to execute the process as a release.

<figure><img src="https://478177610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwRDYqBolZUj6Rwnqx0mm%2Fuploads%2Fgit-blob-7a693819d456f80c95c63bfeda61fc4554d4ab8f%2Fprocess-canvas-view.png?alt=media" alt="Process canvas showing a phase card with its activities, and the Visual/YAML toggle, Save, Discard, and Run buttons"><figcaption></figcaption></figure>

The **Input Store** tab lists the process input sets defined for this process, and lets you create new ones with global, phase, and activity variables. Go to [Input Store](https://developer.harness.io/release-orchestration/use-release-orchestration/release-orchestration-inputs-variables/input-store.md#view-process-input-sets) for more information.

The **Execution History** tab lists every execution of this process.

<figure><img src="https://478177610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwRDYqBolZUj6Rwnqx0mm%2Fuploads%2Fgit-blob-d1f5a360627f285195bb4cd86ba88084048cb81c%2Fprocess-execution-history.png?alt=media" alt="Execution History tab with columns for execution ID, status, execution type, process inputs, triggered by, started at, and ended at"><figcaption></figcaption></figure>

| Column         | Description                                                                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Execution ID   | The execution name. Shows the release version for a **Release** execution type, or a generated identifier for a **Process** execution type. |
| Status         | The execution status, such as **Success** or **In Progress**.                                                                               |
| Execution Type | **Release** when the process ran as part of a release, or **Process** when it ran independently.                                            |
| Process Inputs | The input values provided for that execution.                                                                                               |
| Triggered By   | Who triggered the execution.                                                                                                                |
| Started At     | When the execution started.                                                                                                                 |
| Ended At       | When the execution ended.                                                                                                                   |

Select **Run** to start a new execution, or use the **Date Range**, **Execution Type**, and **Status** filters to narrow the list.

### Create a process with AI <a href="#ai-based-process-creation" id="ai-based-process-creation"></a>

Harness supports creating processes using Harness AI. Release processes are often documented in various sources as text. Release Orchestration lets you provide that documentation and create the process in Harness Release Orchestration.

To create a process with Harness AI, navigate to **Processes**, then select **Create Process with AI**. Enter a **Process Name** and select **Start** in the [Create a Process](#create-a-process) dialog to open the process canvas.

<figure><img src="https://478177610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwRDYqBolZUj6Rwnqx0mm%2Fuploads%2Fgit-blob-7121adfa7c5ea78472a677b2ed7f021fcff98088%2Fcreate-process-ai.png?alt=media" alt=""><figcaption><p>Click to view full size image</p></figcaption></figure>

Enter instructions that define your release process. Use the following example:

**Example prompt:**

```
Create a multi-service release process, from release planning and coordination through monitoring in production. The process includes the following phases:
- Release planning and coordination (Owner: Release Manager)
- Build and artifact creation
- Testing and validation
- Feature flag enablement
- Production deployment
- Monitoring and rollback
```

After you submit the prompt, Harness AI performs the following actions:

* **Creates phases:** Identifies logical groups of activities as phases.
* **Assigns owners:** Assigns owners from the prompt or asks you to provide them.
* **Creates activities:** Generates activities within each phase.
* **Infers dependencies:** Determines execution order and dependencies.

<figure><img src="https://478177610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwRDYqBolZUj6Rwnqx0mm%2Fuploads%2Fgit-blob-68013e1ebd331013ff53b0e931666ea50b1a9cfe%2Fharness-ai-process-creation.png?alt=media" alt=""><figcaption><p>Click to view full size image</p></figcaption></figure>

Harness AI asks you to provide owners for each phase. After you select owners, Harness AI creates YAML for the release process. The YAML appears as a step-by-step release process.

<figure><img src="https://478177610-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwRDYqBolZUj6Rwnqx0mm%2Fuploads%2Fgit-blob-af3b410e65245847ab8c3db4f2fc757907004b13%2Fharness-ai-process-created.png?alt=media" alt=""><figcaption><p>Click to view full size image</p></figcaption></figure>

You can define phases, activities, and dependencies manually to match your release process. Use Harness AI to generate a starting process.

### Process structure <a href="#process-structure" id="process-structure"></a>

### Basic structure <a href="#basic-structure" id="basic-structure"></a>

A process has the following elements:

1. **Metadata**: Name and description
2. **Inputs**: Required parameters (captured using an Input Store when executing)
3. **Variables**: Process-wide variables
4. **Phases**: Major stages
5. **Activities**: Tasks within phases
6. **Dependencies**: Execution order rules

### YAML example <a href="#example-yaml" id="example-yaml"></a>

The following example uses the same YAML shape as a real process created in Release Orchestration (nested `phase` and `activity` blocks, `depends-on`, `owners`, and optional `if` and `data` fields).

To fetch the YAML schema for a process, go to the [YAML Schema API](https://developer.harness.io/api-reference/software-delivery-agent-apis/release-orchestration/yaml-schema) and use the `GET /yamlSchema` endpoint with `entityType` set to `PROCESS`.

```yaml
process:
  name: Comprehensive Release Process
  description: A structured release process covering build, test, and deployment phases
  id: comprehensive_release_process
  phases:
    - phase:
        id: build_phase
        name: Build Phase
        description: Build and validate artifacts before testing.
        owners:
          - Development Team
        depends-on: []
        activities:
          - activity: AutoPipe
            id: AutoPipe
            name: AutoPipe90
            description: ""
            depends-on: []
          - activity: AutoPipe
            id: AutoPipe12
            name: AutoPipe12
            description: ""
            depends-on:
              - AutoPipe
          - activity: AutoPipe
            id: TestActivity00
            name: TestActivity00
            description: ""
            depends-on:
              - AutoPipe12
            if: <+90>
          - activity: ManualTest
            id: AutoIioo
            name: Auto_deploy
            description: doc
            depends-on:
              - AutoPipe12
    - phase:
        id: test_phase
        name: Test Phase
        description: Execute tests and quality gates before deployment.
        owners:
          - QA Team
        depends-on:
          - build_phase
        activities:
          - activity: TestActivity
            id: TestActivity
            name: TestActivity
            depends-on: []
    - phase:
        id: deploy_phase
        name: Deploy to Staging1 Phase
        owners:
          - DevOps Team
        depends-on:
          - test_phase
        activities:
          - activity: WaitingActivity
            id: WaitingActivity
            name: WaitingActivity
            depends-on: []
            data:
              pipeline:
                pipeline: default/MyProject/MyPipeline
                inputSet: {}
```

### Model complex release processes <a href="#modeling-complex-release-processes" id="modeling-complex-release-processes"></a>

You can model complex release processes with different sequences of parallel and sequential execution.

### Common execution patterns <a href="#common-execution-patterns" id="common-execution-patterns"></a>

**Sequential execution**

Activities execute one after another:

```
Activity A → Activity B → Activity C
```

**Parallel execution**

Activities execute simultaneously:

```
Activity A ─┐
            ├→ Activity D
Activity B ─┤
            └→ Activity E
Activity C ─┘
```

**Conditional execution**

Activities execute based on conditions:

```
Activity A → [Condition] → Activity B (if true)
                      └→ Activity C (if false)
```

### Phase dependencies <a href="#phase-dependencies" id="phase-dependencies"></a>

Phases can have dependencies preconfigured. For example:

* The **test phase** has dependencies on the **build phase**
* The **validation phase** has dependencies on the **build phase**
* Phases execute in the order defined by their dependencies

### Activity dependencies <a href="#activity-dependencies" id="activity-dependencies"></a>

Activities within each phase can also have dependencies. For example:

* **Activity 3** (a manual pipeline or automated activity) and **Activity 3.1** (a manual activity) are dependent on **Activity 2** (an automated pipeline activity)
* Activities execute in the order defined by their dependencies
* Dependencies can be configured to support both parallel and sequential execution

### Complex process structure example <a href="#example-complex-process-structure" id="example-complex-process-structure"></a>

A pre-built, preconfigured process might have:

* **Build Phase**: Contains build activities
* **Test Phase**: Depends on Build Phase, contains test activities
* **Validation Phase**: Depends on Build Phase, contains validation activities
* **Activities with dependencies**: Activities within phases that depend on other activities

With this structure, it is possible to model complex release processes and execute them using a release.

To manage processes programmatically, go to the [Orchestration Processes API](https://developer.harness.io/api-reference/software-delivery-agent-apis/release-orchestration/orchestration-processes-beta). It has endpoints to create, update, execute, and delete processes, and to move a process to Git.

### Git-backed processes <a href="#git-backed-processes" id="git-backed-processes"></a>

For Git-backed processes, Harness resolves each activity from a repository and branch based on where the process and the activity are stored and whether a branch is specified for the activity.

### Activity resolution rules <a href="#activity-resolution-rules" id="activity-resolution-rules"></a>

In the following table, the process is stored in branch X of repository A. The table shows the branch Harness uses to fetch an activity.

| Activity location | Branch specified for the activity | Activity is fetched from                                           |
| ----------------- | --------------------------------- | ------------------------------------------------------------------ |
| Inline in Harness | Not applicable                    | Harness, which retrieves the activity internally from its database |
| Repository A      | No                                | Branch X of repository A, the same branch as the process           |
| Repository A      | Yes, branch Y                     | Branch Y of repository A                                           |
| Repository B      | No                                | The default branch of repository B                                 |
| Repository B      | Yes, branch Z                     | Branch Z of repository B                                           |

**Key behavior:** When you do not specify a branch for an activity in the same repository as the process, Harness fetches it from the branch where the process is stored. When the activity is in a different repository, Harness fetches it from the default branch of that repository. In both cases, a branch that you specify for the activity takes precedence.

### Resolution failure <a href="#resolution-failure" id="resolution-failure"></a>

When Harness cannot resolve an activity from the branch it expects, the activity details do not load, but the activity type is still shown. For example, the process is in the `release-v2` branch, no branch is specified for the activity, and the activity exists only in the `main` branch of the same repository. Harness looks for the activity in `release-v2`, so the details do not load.

### Configuration options <a href="#configuration-options" id="configuration-options"></a>

Use one of the following approaches to fix an activity whose details do not load:

1. Specify the branch for the activity, so it is fetched from the branch where it is stored.
2. Store the activity in the same branch as the process.
3. Store the activity in a different repository, which Harness resolves from the default branch of that repository.
4. Store the activity inline in Harness instead of in Git.

{% hint style="info" %}
To keep resolution predictable, store a process and its activities in the same branch, or specify the branch for each activity that lives in another branch.
{% endhint %}

### Sync from Git to Harness <a href="#sync-from-git-to-harness" id="sync-from-git-to-harness"></a>

When bidirectional Git Experience (GitX) is enabled for a repository, Harness listens for webhook events on tracked folder paths. Changes pushed under those paths are processed into Harness as either an update to an existing entity or the automatic creation of a new one.

Harness tracks the folder paths configured on the GitX webhook for that repository, commonly under `.harness/`. Only files under a tracked path are eligible for sync and automatic creation. Files outside a tracked path are ignored by GitX for this flow.

**Update an existing entity**

When you push a change to an existing Git-backed process, process input, or activity YAML file under a tracked path, Harness:

1. Receives the webhook event for the push.
2. Identifies the entity from the file path.
3. Validates the YAML against the structure and schema rules for that entity type.
4. If validation succeeds, refreshes its cached copy of the file.

The entity then reflects the updated YAML the next time you open or run it in Harness. If validation fails, Harness does not apply the update, and the webhook event is marked failed or warning so you can inspect the error and fix the YAML in Git.

**Example: Update a process**

1. The process `checkout-release` already exists in Harness and is stored at `.harness/process/checkout-release.yaml`.
2. You edit that file in Git, for example to change a phase description, and push to the branch Harness is syncing.
3. GitX validates the YAML and refreshes the cache.
4. Opening or running `checkout-release` in Harness shows the updated definition.

**Create a new entity automatically**

When you push a new process, process input, or activity YAML file to a tracked path on the repository's default branch, Harness automatically creates the corresponding entity. On create, Harness:

1. Confirms the file is under a path the GitX webhook is tracking.
2. Infers the entity type from the path convention.
3. Validates the YAML before creating the entity.
4. Creates the entity in Harness if validation succeeds.

A push to a non-default branch does not trigger automatic creation. A push outside a tracked path is also ignored for automatic creation.

Harness infers the entity type from the path convention. The path depth reflects the entity's scope:

* Account-scoped entity: `.harness/<entity-folder>/<identifier>.yaml`
* Org-scoped entity: `.harness/orgs/<org-identifier>/<entity-folder>/<identifier>.yaml`
* Project-scoped entity: `.harness/orgs/<org-identifier>/projects/<project-identifier>/<entity-folder>/<identifier>.yaml`

The entity folder in the path determines what Harness creates:

* `process/<identifier>.yaml` creates a process.
* `activity/<identifier>.yaml` creates an activity.
* `process/<process-identifier>/processInput/<identifier>.yaml` creates a process input for that process.

**Example: Auto-create an activity**

1. GitX is connected to your repository and tracks `.harness/` (or `.harness/activity/`).
2. On the default branch, you add `.harness/activity/deploy-service.yaml` with a valid activity YAML definition.
3. You push the commit.
4. Harness matches the path to an activity, validates the YAML, and creates the `deploy-service` activity in Harness.
5. The new activity appears in the UI without a manual import.

**Example: Auto-create a process input**

1. The process `checkout-release` already exists, either inline or stored remotely in Git.
2. On the default branch, you add `.harness/process/checkout-release/processInput/prod-defaults.yaml`.
3. You push the file under a tracked path.
4. After validation, Harness creates the process input `prod-defaults` under that process.

### Process blueprints <a href="#process-blueprints" id="process-blueprints"></a>

Start with blueprints for common scenarios:

* Standard production release
* Hotfix release
* Multi-service release
* Scheduled release

Customize a blueprint to fit your needs.

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

<details>

<summary>Activity details do not load for a Git-backed process</summary>

This happens when Harness cannot find the activity in the branch it expects. The activity type is still shown, but the details do not load. If you do not specify a branch for an activity in the same repository as the process, Harness fetches the activity from the branch where the process is stored. Specify the branch for the activity, store the activity in the same branch as the process, store it in a different repository and reference it from the default branch, or store it inline in Harness. Go to [Activity resolution rules](#activity-resolution-rules) for the full list of rules.

</details>

<details>

<summary>A change pushed to Git is not applied in Harness</summary>

If validation fails, Harness does not apply the update, and the webhook event is marked failed or warning. Inspect the error and fix the YAML in Git. Also confirm that the file is under a path that the GitX webhook tracks, because files outside a tracked path are ignored.

</details>

<details>

<summary>A new process, process input, or activity is not created automatically</summary>

Automatic creation applies only to pushes to the default branch of the repository, and only for files under a tracked path. A push to a non-default branch or outside a tracked path does not create the entity. Confirm that the file path follows the entity folder convention and that the YAML is valid.

</details>

***

### Related topics <a href="#related-topics" id="related-topics"></a>

Use the following links to continue.

* [Phases](https://developer.harness.io/release-orchestration/use-release-orchestration/release-orchestration-phases/phases-overview.md)
* [Activities](https://developer.harness.io/release-orchestration/use-release-orchestration/release-orchestration-activities/activities-overview.md)
* [Activity dependencies](https://developer.harness.io/release-orchestration/use-release-orchestration/release-orchestration-activities/activities-overview.md#activity-dependencies-and-execution-order)
* [Modeling complex processes](#modeling-complex-release-processes)

{% @harness-feedback/feedback %}
