> For the complete documentation index, see [llms.txt](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/get-started/map-your-organization/applications.md).

# Applications

Group repositories into applications automatically from GitHub custom properties, GitLab paths, or a Port.io catalog.

Applications group related repositories and services into a single unit — giving you aggregated business impact, security posture, and ownership. Heeler creates and maintains them by reading your existing software catalog or repository metadata, so there's no manual setup.

## Supported sources

<table><thead><tr><th width="160">Source</th><th>How applications are derived</th><th>Needs a separate connection?</th></tr></thead><tbody><tr><td><strong>GitHub</strong></td><td>Repository <strong>custom properties</strong> (e.g. an <code>application</code> property groups repos by value).</td><td>No — reuses your <a href="/mrecEO40m5D6bt7Pq5pE/get-started/source-code-scm/github.md">GitHub connection</a>.</td></tr><tr><td><strong>GitLab</strong></td><td>Path-prefix matching on project paths.</td><td>No — reuses your <a href="/mrecEO40m5D6bt7Pq5pE/get-started/source-code-scm/gitlab.md">GitLab connection</a>.</td></tr><tr><td><strong>Port.io</strong></td><td>Blueprint entities representing products or applications.</td><td>Yes — the <a href="/mrecEO40m5D6bt7Pq5pE/get-started/developer-platform/port-io.md">Port.io integration</a>.</td></tr><tr><td><strong>Heeler</strong></td><td>Manual application creation.</td><td>No.</td></tr></tbody></table>

## Select an application source

1. Go to **Administration → Connection Mapping → Applications**.
2. Click the **Source** badge in the table header.
3. Select **GitHub**, **GitLab**, **Port.io**, or **Heeler**.

Heeler queues the processor job; applications appear within a few minutes.

{% hint style="warning" %}
Switching sources preserves existing applications but stops auto-creating new ones from the previous source. A confirmation dialog appears first.
{% endhint %}

## Configure the mapping

Click **Configure Mapping** to define how applications are built from your source.

{% tabs %}
{% tab title="GitHub Custom Properties" %}
Group repositories by a custom-property value:

* **Grouping Key** — the property to group by (e.g. `custom_properties.application`).
* **Allowed Values** — optionally include only certain values (e.g. only `backend` and `frontend`).
* **Attribute Mapping** — map other properties to application fields like Tier, Description, or Tech Lead.

{% hint style="info" %}
Heeler reads properties already harvested from GitHub — new properties appear after the next sync. For multi-org tenants, available properties are aggregated across **all** connected GitHub / GHES orgs.
{% endhint %}
{% endtab %}

{% tab title="GitLab Path Prefixes" %}
Projects group by `path_with_namespace` — each prefix becomes one application:

* **Grouping Key** — `group_path`.
* **Allowed Values** — the group paths that represent applications (e.g. `org/services/auth`, `org/services/payments`).

Selecting `org/services/auth` and `org/services/payments` from a structure like `org/services/auth/auth-api` creates two applications, each with the repos under its prefix.
{% endtab %}

{% tab title="Port.io" %}
Port.io offers the richest mapping — its catalog already defines entities, properties, and relations. Three selects decide which entities are read and how they group:

| Control                   | What it selects                                                                                                                                                                          |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Software Blueprint**    | The blueprint holding your service catalog. Each of its entities names the product it belongs to, and those products become applications.                                                |
| **Products Grouping Key** | The relation or property on those entities that names the product. This is what decides application membership. The list is populated from the software blueprint, so choose that first. |
| **Product Blueprint**     | Optional. Supplies each application's title and description. A product with no entry here keeps its raw product name.                                                                    |

Changing the software blueprint clears the grouping key. Pick a new one from the fields of the blueprint you moved to.

**Attribute Mapping** maps blueprint properties and relations to Heeler fields: Name → `title`, Tier → `properties.criticality` (with value mapping like `mission-critical` → Tier 1), Tech Lead → `relations.tech_lead`, Security Lead → `relations.security_lead`, Repositories → `relations.repository` (or `relations.gitlab_repository`).
{% endtab %}
{% endtabs %}

### Attribute mapping table

<table><thead><tr><th width="200">Column</th><th>What it does</th></tr></thead><tbody><tr><td><strong>Application Field</strong></td><td>Name, Description, Tier, Tech Lead, Security Lead, or Repositories.</td></tr><tr><td><strong>Blueprint</strong></td><td><em>(Port.io only)</em> the blueprint the attribute belongs to.</td></tr><tr><td><strong>Source Attribute</strong></td><td>The source field (auto-populated).</td></tr><tr><td><strong>Supported Values</strong></td><td>Optionally restrict accepted values.</td></tr></tbody></table>

## Preview and manual create

* **Preview Mapping Results** lists the applications the mapping would create and how many repositories each would hold. It reads the mapping the next sync will use, so save a change before previewing it.
* **Create Application** adds one manually with a name, description, tier, and repositories — manual and auto-mapped applications coexist.

## How sync works

* Application sync runs every **6 hours** and immediately on save; repository assignments update via set-diff (only changes applied).
* Applications removed from the source config are cleaned up with their repo links.
* Finding counts are aggregated hourly by the Application Processor.

## Viewing applications

Mapped applications appear in [**Catalog → Applications**](/mrecEO40m5D6bt7Pq5pE/catalog/applications.md) with a source icon, business impact (from tier + environment), aggregated findings, validated-secret counts, and owning team.

{% hint style="info" %}
Create/edit/delete happens in **Connection Mapping → Applications**; the **Catalog → Applications** view is read-only, focused on security visibility.
{% endhint %}

## Verify

1. On **Connection Mapping → Applications**, each application appears with its **Source** icon and non-zero **repository** counts.
2. The application shows in [**Catalog → Applications**](/mrecEO40m5D6bt7Pq5pE/catalog/applications.md) with its business impact, aggregated findings, and owning team.
3. If you changed the mapping, use **Preview Mapping Results** to confirm the applications and repo counts match what you expect before the next sync writes them.

## Troubleshooting

<table><thead><tr><th width="300">Symptom</th><th>Fix</th></tr></thead><tbody><tr><td>No applications appear</td><td>The <strong>Source</strong> is still set to Heeler (manual). Select GitHub, GitLab, or Port.io in the table header.</td></tr><tr><td>Applications appear but group 0 repositories</td><td>The <strong>Grouping Key</strong> is wrong — confirm it matches the property or path that groups repos in your source (e.g. <code>custom_properties.application</code>, <code>group_path</code>).</td></tr><tr><td>A newly configured source shows nothing yet</td><td>Sync hasn't run. It runs every 6 hours and immediately on save — wait a few minutes, or re-save the configuration.</td></tr></tbody></table>


---

# 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://docs.heeler.com/mrecEO40m5D6bt7Pq5pE/get-started/map-your-organization/applications.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.