# Applications

Heeler can automatically create and manage applications by reading your existing software catalog or repository metadata from GitHub, GitLab, or Port.io. Applications group related repositories and services together, providing a unified view of business impact, security posture, and ownership.

## Why Configure Application Mapping?

* **Automated catalog**: Applications are created from your existing organizational structure — no manual setup required
* **Consistent grouping**: Repositories are grouped by the same logic your organization already uses (custom properties, GitLab paths, Port.io products)
* **Security visibility**: Each application aggregates vulnerability counts, dependency findings, and validated secrets across all its repositories and services
* **Tier and ownership**: Map criticality tiers, tech leads, and security leads directly from your source platform

## Supported Sources

| Source      | How Applications Are Derived                                                        |
| ----------- | ----------------------------------------------------------------------------------- |
| **GitHub**  | Repository custom properties (e.g., a `application` property groups repos by value) |
| **GitLab**  | Path-prefix matching on GitLab project paths                                        |
| **Port.io** | Blueprint entities representing products or applications in your software catalog   |
| **Heeler**  | Manual application creation                                                         |

## Prerequisites

* An active connection to your source platform configured under **Administration > Connections**
* For GitHub: Custom properties defined at the organization level and assigned to repositories
* For GitLab: A consistent group/path structure that maps to your application boundaries
* For Port.io: A blueprint representing applications or products with relations to repositories

## Selecting an Application Source

1. Navigate to **Administration > Connection Mapping > Applications**
2. Click the **Source** badge in the table header to open the source selector
3. Select your desired source (GitHub, GitLab, Port.io, or Heeler)

{% hint style="warning" %}
Switching sources preserves all existing applications but stops auto-creating new ones from the previous source. A confirmation dialog will appear before the switch takes effect.
{% endhint %}

4. Heeler immediately queues the relevant processor job. Applications will begin appearing within a few minutes.

## Configuring the Mapping

Click **Configure Mapping** in the toolbar to define how applications are created from your source data. The configuration varies by source.

### GitHub Custom Properties

GitHub custom properties let you tag repositories with organizational metadata at the org level. Heeler groups repositories by custom property values to create applications.

1. **Grouping Key**: Select the custom property to group by (e.g., `custom_properties.application`)
2. **Allowed Values**: Optionally select which property values to include. For example, if your `application` property has values `backend`, `frontend`, `infra`, and `data`, you can select only `backend` and `frontend`.
3. **Attribute Mapping**: Map additional custom properties to application fields like Tier, Description, or Tech Lead.

{% hint style="info" %}
Heeler reads custom properties that have already been harvested from your GitHub organization. If you recently added new properties, allow time for the next GitHub sync to complete before they appear in the dropdowns.
{% endhint %}

### GitLab Path Prefixes

GitLab projects are grouped into applications based on their `path_with_namespace`. Each configured path prefix creates one application containing all projects under that prefix.

1. **Grouping Key**: Select `group_path` and choose the group paths that represent applications
2. **Allowed Values**: Select the specific group paths to map (e.g., `org/services/auth`, `org/services/payments`)

**Example**: If your GitLab structure is:

```
org/services/auth/auth-api
org/services/auth/auth-worker
org/services/payments/payment-gateway
```

Selecting `org/services/auth` and `org/services/payments` creates two applications, each containing the repositories under their prefix.

### Port.io Software Catalog

Port.io provides the richest mapping capabilities since its software catalog already defines entities, properties, and relations.

1. **Blueprint**: Select the blueprint that represents applications (e.g., `software`, `service`, `application`)
2. **Attribute Mapping**: Map blueprint properties and relations to Heeler application fields:
   * **Name** -> `title` or a custom property
   * **Description** -> `properties.description`
   * **Tier** -> `properties.criticality` (with value mapping: `mission-critical` -> Tier 1, etc.)
   * **Tech Lead** -> `relations.tech_lead`
   * **Security Lead** -> `relations.security_lead`
   * **Repositories** -> `relations.repository` or `relations.gitlab_repository`

{% hint style="info" %}
All dropdown options are auto-populated from your Port.io data. Select a blueprint first, then the available properties and relations for that blueprint will appear in the attribute dropdowns.
{% endhint %}

### Attribute Mapping Table

The mapping table defines how source fields translate to Heeler application properties:

| Column                | Description                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------- |
| **Application Field** | The Heeler property to populate (Name, Description, Tier, Tech Lead, Security Lead, Repositories) |
| **Blueprint**         | *(Port.io only)* The blueprint this attribute belongs to                                          |
| **Source Attribute**  | The field from your source platform (auto-populated)                                              |
| **Supported Values**  | Optionally restrict accepted values for this field                                                |

Click **+ Add Attribute Mapping** to map additional properties beyond the defaults.

## Previewing Results

Click **Preview Mapping Results** to see what applications would be created from your current configuration, including the repository count for each. This lets you verify the mapping before committing.

## Creating Applications Manually

Click **Create Application** in the toolbar to manually create an application with a name, description, tier, and repository assignments. Manual applications coexist with auto-mapped applications.

## How Application Sync Works

* Application sync runs automatically every **6 hours** and immediately when you save a new configuration
* New applications are created, repository assignments are updated via set-diff (only changes are applied)
* Applications removed from the source configuration are cleaned up along with their repository links
* Vulnerability and finding counts are aggregated separately by the Application Processor (runs every hour)

## Viewing Applications

Applications created through mapping appear in **Catalog > Applications** alongside manually created ones. Each application displays:

* **Source**: An icon indicating which platform created it (GitHub, GitLab, Port.io)
* **Business Impact**: Calculated from tier and deployment environment
* **Findings**: Aggregated dependency and source code findings across all repositories
* **Validated Secrets**: Count of confirmed secret exposures
* **Team**: The owning team (if team mapping is also configured)

{% hint style="info" %}
Application management (create, edit, delete) is performed in **Administration > Connection Mapping > Applications**. The **Catalog > Applications** view is read-only and focused on security visibility.
{% endhint %}