> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/application-security/application-security-posture-management-aspm/applications/defining-business-applications/define-applications-by-code-criteria.md).

# Define applications by Code Criteria

Use Code Criteria to create and maintain applications from your VCS structure.

Matching repositories and their connected assets join automatically.

You can group applications by organization, project, or repository. One Criteria can include multiple VCS providers.

Use the tenant UI for this workflow. Use the [API](/application-security/application-security-posture-management-aspm/applications/manage-applications-via-public-apis.md) for automation.

## Prerequisites

* **Data source**: Your Version Control System (such as GitHub, GitLab) must already be onboarded as a Data Source with at least one onboarded repository
* **RBAC role**: You must have the **AppSec Admin** role, or a custom role with `read/write` access to application resources on ASPM (Criteria and Applications). **Account Admin** also has sufficient permissions but is broader than required
* **SBAC**: You can only create applications from VCS entities (Organizations, Projects, or Repositories) that are already included in your SBAC Asset Groups

## Create a Code Criteria

1. Go to **Modules** → **Application Security** → **Business Applications**.
2. Click **Create** **Applications Criteria** → **New Criteria**.
3. In **General**, select **Code**. Enter a name (required) and an optional description, and click **Next**.
4. In **Define Criteria**:

   1. Select one or more VCS providers (such as GitHub).

   2. Choose a **Group by** level for each provider (Organization, Project, or Repository).

   3. Optional: Configure your merge and unification preferences:
      1. **Merge same-named applications within one provider**.

         **Recommended**: Enable this setting for your first Code Criteria. Disable it only when same-named repositories must remain separate. See [Code Criteria grouping and unification reference](/application-security/application-security-posture-management-aspm/applications/defining-business-applications/define-applications-by-code-criteria/reference-a-code-criteria-grouping-and-unification.md) for naming behavior and application boundaries.

         Example: Two GitHub repositories named `payments-api` become one application. See [Reference B: Code Criteria references and examples](/application-security/application-security-posture-management-aspm/applications/defining-business-applications/define-applications-by-code-criteria/reference-b-code-criteria-references-and-examples.md).
      2. **Unify same-named applications across providers**.

         Example: GitHub and GitLab repositories named `payments-api` become one application. See [Reference B: Code Criteria references and examples](/application-security/application-security-posture-management-aspm/applications/defining-business-applications/define-applications-by-code-criteria/reference-b-code-criteria-references-and-examples.md).

   4. Click **Next**.

   > **Note:** To understand cloud and self-managed provider behavior, see [Reference A: Code Criteria grouping and unification](/application-security/application-security-posture-management-aspm/applications/defining-business-applications/define-applications-by-code-criteria/reference-a-code-criteria-grouping-and-unification.md).
5. In **Scope**, optionally filter each provider by organization, project, or repository.
6. In **Metadata**, configure the business owner and criticality.
7. Select **Submit**.

## Verification

Verify the generated applications in the [Business Applications](/application-security/application-security-posture-management-aspm/applications/business-application-assets.md) list.

Use [Code Criteria grouping and unification reference](/application-security/application-security-posture-management-aspm/applications/defining-business-applications/define-applications-by-code-criteria/reference-a-code-criteria-grouping-and-unification.md) before submitting when you need to confirm scope or application boundaries.

## References and examples

Use [Reference A: Code Criteria grouping and unification](/application-security/application-security-posture-management-aspm/applications/defining-business-applications/define-applications-by-code-criteria/reference-a-code-criteria-grouping-and-unification.md) to verify grouping, scope, and unification rules.

Use [Reference B: Code Criteria references and examples](/application-security/application-security-posture-management-aspm/applications/defining-business-applications/define-applications-by-code-criteria/reference-b-code-criteria-references-and-examples.md) for worked merge, unification, and scope-filtering examples.

<details>

<summary>Detailed configuration guidance</summary>

1. Under **Modules**, select **Application Security** → **Applications**, then open the **Application Criteria** tab and select **+ Add Criteria**.
2. Configure the **General** step.
   1. Select **Code** as the Criteria type.
   2. Provide a Criteria name (required) and description.
   3. Click **Next**.
3. Configure the **Define Criteria** step.

   The Define Criteria step determines how matching assets group into applications. These settings control whether an application is defined as a single repository or a broader organization, and how the system handles assets with identical names across your environment. Connected runtime and deployment assets are automatically linked to these boundaries to provide a complete view of the application lineage.

   1. Select one or more VCS provider tiles to include in the Criteria: GitHub, GitLab, Bitbucket, Azure Repos, or AWS CodeCommit. Only providers with active integrations appear as selectable tiles.
   2. Inside each selected provider tile, select a **Group by** level from the dropdown. The Group by level is configured **per provider tile**, so different providers in the same Criteria can use different grouping levels.
      * **Organization**: Group all repositories under the same VCS organization into one application
      * **Project**: Group all repositories under the same VCS project into one application
      * **Repository**: Create one application per repository
   3. **Merge organizations/projects/repositories with identical names** (optional): The engine merges applications with the same name from the same VCS provider into one application.

      > **Example use case**\
      > Two projects in the same GitHub organization expose repositories with identical names that represent the same logical application. See [Reference B: Code Criteria references and examples](/application-security/application-security-posture-management-aspm/applications/defining-business-applications/define-applications-by-code-criteria/reference-b-code-criteria-references-and-examples.md).

      > <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><h3>Tip</h3><p>Recommended: When creating your first Code Criteria, enable <strong>Merge organizations/projects/repositories with identical names</strong> unless you know that repositories with the same name across platforms must remain separate. When this toggle is <strong>off</strong> and the engine encounters identically named sources, every generated application name is automatically suffixed with the provider name (for example, <code>payments-api_GitHub</code>), and any remaining collisions receive an additional UTC timestamp suffix in the format <code>MM_DD_YY_HH:MM:SS</code> (for example, <code>payments-api_GitHub_05_31_26_07:42:18</code>). Warning: Because Criteria are immutable, consolidating these into one application later requires deleting and recreating the Criteria.</p></div>
   4. **Unify applications across providers** (optional): The engine merges applications with the same name from different VCS providers into one application. Available only when the Criteria targets more than one provider type; enabling it auto-enables and locks the first toggle.

      > **Example use case**\
      > The organization is migrating between VCS providers (for example, Bitbucket to GitHub) or runs the same application's source across multiple VCS systems. See [Reference B: Code Criteria references and examples](/application-security/application-security-posture-management-aspm/applications/defining-business-applications/define-applications-by-code-criteria/reference-b-code-criteria-references-and-examples.md).
   5. Click **Next**.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><h3>Note</h3><p>For cloud and self-managed provider behavior, see <a href="/spaces/8Z0RLJ1BFF5TQL8VtUeK/pages/7rxYxHvINbItyrXaoY4Y">Reference A: Code Criteria grouping and unification</a>.</p></div>
4. Configure the **Scope**.

   The Scope step defines which assets the Criteria evaluates. Use Scope filters to include or exclude specific organizations, projects, or repositories within each provider.

   The Scope step displays **one tab per selected provider tile** from the **Define Criteria** step. Each tab is an independent filter expression for that provider. A tab left without filters includes every asset for that provider at the **Group by** level selected for that provider in the **Define Criteria** step.

   Scope is dynamic. The engine re-evaluates filter matches on every refresh, so newly matching assets join automatically and assets that stop matching drop out.

   #### How filters and tabs combine

   Scope has three independent combination layers. The engine applies them in order: layer 1 inside each filter row, layer 2 across filter rows in the same tab, layer 3 across tabs.

   | Layer | Where                                                     | Combinator   | Effect                                                                                                                                                                                                        |
   | ----- | --------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | 1     | Within one filter (multiple values in the same field)     | `OR`         | The asset matches if **any** listed value matches. Example: Organization Name Equal `payments`, `billing` matches an asset whose organization is either `payments` or `billing`                               |
   | 2     | Within one tab (multiple filter rows on different fields) | `AND`        | The asset matches only if **every** filter row in that tab matches. Example: Organization Name Contains `payments` **AND** Repository Name Contains `api` matches an asset only when both conditions are true |
   | 3     | Across tabs (one tab per provider)                        | `OR` (union) | The asset matches if **any one tab's** full configuration (provider + Group by level + filters) matches. Adding more tabs widens scope; it never narrows it                                                   |

   For a worked multi-provider walkthrough, see [Reference B: Code Criteria references and examples](/application-security/application-security-posture-management-aspm/applications/defining-business-applications/define-applications-by-code-criteria/reference-b-code-criteria-references-and-examples.md).

   1. Select the **provider tab** you want to filter.

      The tab name reflects the provider and its Group by level chosen in Step 2 (for example, GitHub — Repository). Repeat steps 4b-4d for each provider tab that requires filters. Tabs left without filters include all assets for that provider.

      <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><h3>Note</h3><p>A provider tab with no filters configured includes every asset for that provider at the chosen Group by level. Combined with the union behavior above, leaving multiple tabs unfiltered means the Criteria includes every connected asset across all selected providers , which is often the desired result for an organization-wide baseline Criteria, but can produce a large application count if used without intent. Use filters on tabs where the scope needs to be narrowed.</p></div>
   2. Select the **filter field** to narrow assets by:

      * **Repository Name** : Available at all Group by levels
      * **Organization Name**: Available when the tab's Group by level is Organization, Project, or Repository
      * **Project Name**: Available only when the provider supports projects (GitLab, Bitbucket, Azure Repos) and the tab's Group by level is Project or Repository

      <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><h3>Note</h3><p>Field availability is driven by the active tab's Group by level and provider capability. Fields that do not apply to the active tab are not displayed.</p></div>
   3. Choose an **operator** for the selected field: **Equal**, **Not Equal**, **Contains**, or **Not Contains**.
   4. Enter one or more filter **values**.

      Multiple values within the same filter combine with `OR` logic; multiple filters across fields combine with `AND` logic.
   5. Click Next.

   For a **multi-provider scoping** example, see [Reference B: Code Criteria references and examples](/application-security/application-security-posture-management-aspm/applications/defining-business-applications/define-applications-by-code-criteria/reference-b-code-criteria-references-and-examples.md).
5. Configure the **Metadata** step.

   Configure rules to automatically assign ownership and risk levels to the generated applications.

   1. **Business Owner** (required): Select the VCS hierarchy level from which to inherit ownership for every generated application. Options include **None**, **Organization Owner**, **Project Owner**, or **Repository Owner** (inherit the owner from the VCS repository).
   2. Configure **Business Criticality**:

      1. Select a default severity level: Critical, High, Medium, Low.
      2. (Optional): **Automatically upgrade criticality to Critical if a mapped asset is exposed to the internet**: Enable this checkbox to elevate the criticality of internet-exposed assets to Critical, ensuring accurate risk prioritization.

      The business criticality level feeds the Urgency calculation for every issue associated with the generated applications.
   3. Click **Submit**.

      Cortex Cloud will begin processing your criteria. Navigate to the [business applications](/application-security/application-security-posture-management-aspm/applications/business-application-assets.md) list to verify that your new applications have been generated and populated with assets.

#### Examples: Grouping and unification

See [Reference B: Code Criteria references and examples](/application-security/application-security-posture-management-aspm/applications/defining-business-applications/define-applications-by-code-criteria/reference-b-code-criteria-references-and-examples.md) for the worked examples. See [Reference A: Code Criteria grouping and unification](/application-security/application-security-posture-management-aspm/applications/defining-business-applications/define-applications-by-code-criteria/reference-a-code-criteria-grouping-and-unification.md) for the toggle matrix and deployment rules.

#### Example: Merge within a provider

This example illustrates the **Merge organizations/projects/repositories with identical names** option on a Criteria that targets a single VCS provider.

**Scenario**: A Code Criteria targets GitHub with **Group by = Repository**. The GitHub organization `acme-eng` contains two projects, each exposing a repository named `payments-api`.

**Inputs**

| Provider | Organization | Project    | Repository      |
| -------- | ------------ | ---------- | --------------- |
| GitHub   | `acme-eng`   | `checkout` | `payments-api`  |
| GitLab   | `acme-eng`   | `billing`  | `payments-api`. |

**Result**

| Merge toggle | Applications produced                                                                                  |
| ------------ | ------------------------------------------------------------------------------------------------------ |
| **Off**      | Two applications named \`payments-api\` — one per source repository                                    |
| **On**       | One application named \`payments-api\` containing both repositories and their connected runtime assets |

#### Example: Unify across providers

This example illustrates the **Unify applications across providers** option on a Criteria that targets two VCS provider types.

**Scenario**: A Code Criteria targets GitHub and GitLab with **Group by = Repository** on both tiles. Each provider hosts a repository named payments-api

**Inputs**

| Provider | Organization / Group | Repository     |
| -------- | -------------------- | -------------- |
| GitHub   | `acme-eng`           | `payments-api` |
| GitLab   | `acme-platform`      | `payments-api` |

**Result**

| Merge toggle | Unify toggle | Applications produced                                                                                                                                                                                 |
| ------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Off**      | **Off**      | Two applications: `payments-api_GitHub` and `payments-api_GitLab`. The provider suffix is added automatically. No name collision occurs because each app already has a distinct provider-derived name |
| **On**       | **Off**      | .`payments-api_GitLab` and `payments-api_GitHub`. Merge only operates within each provider; cross-provider unification stays off                                                                      |
| **On**       | **On**       | One application named `payments-api_GitHub_GitLab` spanning both providers and their connected runtime assets. The suffix lists all unified providers.                                                |

{% hint style="info" %}

### Note

Enabling **Unify applications across providers** auto-enables and locks the **Merge organizations/projects/repositories with identical names** option, so the `Off / On` combination is not reachable. For the full matrix and edge cases, see [Reference A: Code Criteria grouping and unification](/application-security/application-security-posture-management-aspm/applications/defining-business-applications/define-applications-by-code-criteria/reference-a-code-criteria-grouping-and-unification.md).
{% endhint %}

#### Example: Multi-provider scoping with filters

This example illustrates the **Scope** step on a Code Criteria that targets three providers with different Group by levels and different per-tab filters

**Scenario**: A single Code Criteria selects GitHub, GitLab, and Bitbucket. Each provider tab is configured independently:

* **GitHub tab**: **Group by = Organization**, filter: **Organization Name Contains payments**
* **GitLab tab**: **Group by = Repository**, filter: **Repository Name Equal api-gateway**
* **Bitbucket tab**: **Group by = Project**, no filter

**Result**: Effective scope is the union of the three expressions

| Tab       | Included assets                                                                                                            |
| --------- | -------------------------------------------------------------------------------------------------------------------------- |
| GitHub    | Every repository under any GitHub organization whose name contains payments, grouped per organization                      |
| GitLab    | Every GitLab repository named exactly api-gateway, one application per matching repository                                 |
| Bitbucket | Every repository under every Bitbucket project the tenant has connected, grouped per project (no filter restricts the set) |

A repository that matches the GitHub filter is included even if it does not appear in GitLab or Bitbucket. A Bitbucket repository is included regardless of name because the Bitbucket tab has no filter. The three result sets do not intersect; they are added together. If unification toggles are enabled in Step 3, identically named applications produced by different tabs subsequently merge per [Reference A: Code Criteria grouping and unification](/application-security/application-security-posture-management-aspm/applications/defining-business-applications/define-applications-by-code-criteria/reference-a-code-criteria-grouping-and-unification.md).

### Reference: Advanced unification logic (Code Criteria)

When configuring grouping and unification in the Define Criteria step, specific rules govern cross-provider dependencies, deployments of the same provider type, and how different toggle combinations determine your final application boundaries.

The **Unify applications across providers** toggle is available only when your Criteria targets more than one VCS provider type. Activating this toggle automatically turns on and locks the **Merge organizations/projects/repositories with identical names** setting, since cross-provider unification requires within-provider merging to happen first.

**Provider unification configuration options**

Consider a tenant setup with GitHub Cloud (organizations `acme-eng`, `acme-research`), GitHub Enterprise (organization `acme-legacy`), and GitLab (group `acme-platform`). The user selects **Repository** grouping on the GitHub tile and **Project** grouping on the GitLab tile. A repository named `payments-api` exists across all three environments.

The engine produces the following results based on your configuration:

| Merge toggle | Unify toggle | Expected result                                                                                                                                                                                                                                                   |
| ------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **OFF**      | **OFF**      | **Three separate applications** (one per repository). Each repository's unique asset ID keeps it separate. The same behavior applies when only one provider type is selected and the Merge organizations/projects/repositories with identical names toggle is OFF |
| **ON**       | **OFF**      | **Two applications**. The first application combines GitHub Cloud and Enterprise (merged because they act as a single provider tile). The second application isolates GitLab because cross-provider unification is OFF                                            |
| **ON**       | **ON**       | **One single application**. All three repositories collapse into a unified application boundary across all providers                                                                                                                                              |
| **OFF**      | **ON**       | **Not reachable**. The UI automatically enables and locks the Merge toggle whenever cross-provider unification is enabled, making this state impossible to submit via the Console or API.                                                                         |

### Cloud and self-managed deployments of the same VCS

The **Unify applications across providers** toggle becomes available only when the Define Criteria step shows two or more separate provider tiles with a group-by selected (for example, mixing GitHub and GitLab).

Because Cortex Cloud and self-managed deployments of the same provider (for example, GitHub Cloud and GitHub Enterprise) collapse into one tile, this toggle stays disabled for the pair. It is not needed, because the **Merge organizations/projects/repositories with identical names** toggle already merges assets across those deployments within that single tile.

{% hint style="warning" %}

### Warning

If two unrelated organizations with identical names exist across your cloud and self-managed deployments and must remain separate applications, do not enable within-provider merging. Instead, define one Criteria per deployment scope using filters on **Organization Name** to isolate the content.
{% endhint %}

</details>


---

# 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://cortex-docs.paloaltonetworks.com/application-security/application-security-posture-management-aspm/applications/defining-business-applications/define-applications-by-code-criteria.md?ask=<question>&goal=<endgoal>
```

`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.