> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Publishing Add-ons

> Publish an add-on your organisation curated to the global Ankra Catalog, through a reviewable pull request.

<Note>
  Publishing proposes an add-on definition your organisation curated to the global Ankra Catalog. Nothing changes until the pull request it opens is reviewed and merged - after that, the add-on appears in the add-on catalog of every organisation on Ankra.
</Note>

## What publishing does

The add-on catalog every organisation sees is backed by a public Git repository, [ankraio/ankra-global-resources](https://github.com/ankraio/ankra-global-resources). Each globally available add-on is one `kind: Addon` manifest in that repository's `addons/` directory - a small YAML file carrying the add-on's name, display metadata, and the match rules that link Helm charts to it.

When you publish an add-on:

1. Ankra renders your organisation's definition as a `kind: Addon` manifest.
2. It opens a pull request against the catalog repository on your behalf, on a dedicated branch.
3. The Ankra team reviews the pull request. Merging it is the approval.
4. The platform sync ingests the merged manifest, and the add-on becomes available to **all organisations**.

Your organisation keeps its own copy of the definition. An organisation-scoped add-on always shadows the global one with the same name, so publishing never changes what your own catalog shows you.

## Who can publish

Publishing puts your organisation's name on a pull request against a public repository, and once merged the entry is visible to every organisation on Ankra. It therefore requires the **Manage Helm registries** permission (`helm.manage`), which organisation **admins** and **owners** hold. Members and operators can open the publish flow and see everything it would propose, but not submit it.

## Publishing an add-on

1. Open **Add-ons** and select an add-on curated by your organisation (global add-ons are already published).
2. Select **Publish to Ankra Catalog**.
3. **Target** - where the proposal lands, and whether it can be made at all. Publishing is unavailable when:
   * the platform has no catalog repository configured
   * a publish request for this add-on is already open
   * the definition contains material that must not reach a public repository (see below)
   * you do not hold `helm.manage`
4. **Review** - the exact manifest the pull request will add, or a **diff** against the currently published version when the add-on is already in the catalog.
5. **Confirm** - a recap of what changes and where, then **Publish via pull request**.

The flow shows the opened pull request immediately, with a direct link. Publishing is idempotent: while a pull request for the add-on is open, publishing again returns the existing request instead of opening a duplicate.

## What cannot be published

The catalog repository is public, and a pull request is effectively permanent - a credential that reaches it is in the repository's history even if the branch is later closed. Ankra screens the rendered manifest before it can be proposed and refuses anything carrying:

* credentials embedded in a URL, such as `https://user:password@host`
* recognisable provider tokens - GitHub, GitLab, AWS, Slack, generic API secret keys, or a PEM private key block

The offending field is named so it can be corrected. This is a check on the ten metadata fields an add-on definition publishes; it is not a substitute for keeping credentials out of your definitions in the first place.

## Tracking a publish

The add-on's detail page gains a **Publish history** section listing every publish request with its pull request link and lifecycle state:

| State                      | Meaning                                                                                                |
| -------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Pull request open**      | The proposal is awaiting review on the catalog repository.                                             |
| **Merged - awaiting sync** | The pull request was merged; the platform sync (which runs every few minutes) has not ingested it yet. |
| **Live in the catalog**    | The add-on is available to every organisation.                                                         |
| **Closed without merging** | The pull request was declined.                                                                         |
| **Failed**                 | The pull request could not be opened; the reason is shown on the request.                              |

States advance automatically - open pull requests are re-checked by the platform, and the history refreshes while a request is in flight.

## The Addon manifest

The manifest published for your add-on mirrors the definition fields:

```yaml theme={null}
apiVersion: v1
kind: Addon
spec:
  name: grafana
  display_name: Grafana
  description: The open observability platform.
  website_url: https://grafana.com
  documentation_url: https://grafana.com/docs/
  icon_url: https://grafana.com/logo.svg
  category: Data Visualization
  match_chart_names:
    - grafana
  match_home_url_prefixes:
    - https://grafana.com/oss
```

`spec.name` is the add-on's unique slug across the catalog. The match rules (`match_chart_names`, `match_keywords`, `match_home_url_prefixes`) determine which Helm charts resolve to the add-on in every organisation's catalog.

## Removing a published add-on

Removing the manifest from the catalog repository (again through a pull request) retires the global add-on. Organisations that customised it keep their own copies - only the shared, Ankra-curated entry goes away.