# Rego Packages

Rego Packages let you define shared Rego helper functions and data sets once and import them into any number of governance policies. When a package is updated, every policy that imports it automatically uses the new logic at its next evaluation — no per-policy edits required.

This is useful whenever the same logic needs to be enforced across multiple policies: tag validation helpers, approved resource lists, account classification rules, and similar shared constructs.

***

## How Rego Packages Work

Each package is a named module of Rego code stored under the `firefly.packages` namespace. A package named `tag_validator` is imported in a policy as:

```rego
import data.firefly.packages.tag_validator
```

At policy evaluation time, Firefly resolves all imported packages automatically. The latest version of each package is always used; there is no need to re-save a policy when a package is updated.

***

## Package Naming Rules

Package names must be valid Rego identifiers:

* Start with a letter (`a–z`, `A–Z`) or underscore (`_`)
* Followed by any combination of letters, digits, or underscores
* Maximum 128 characters
* Must be unique within your account

| Valid examples  | Invalid examples                |
| --------------- | ------------------------------- |
| `aws_helpers`   | `aws.helpers` (dot not allowed) |
| `IamChecks`     | `123check` (starts with digit)  |
| `tag_validator` | `my-pkg` (hyphen not allowed)   |
| `_internal`     | `http.send` (dot not allowed)   |

> **Note:** Package names cannot be changed after a package is created.

***

## Package Code Constraints

Package code is a standalone Rego module. It must follow these rules:

| Rule                  | Requirement                                                                         |
| --------------------- | ----------------------------------------------------------------------------------- |
| `package` declaration | Must **not** be included — Firefly injects it automatically                         |
| `import` statements   | Must **not** be included — packages are standalone and cannot import other packages |
| Restricted built-ins  | `http.send` and `opa.runtime` are not permitted                                     |
| Maximum size          | 50 KB                                                                               |
| Maximum line length   | 1,000 characters per line                                                           |
| Valid Rego            | Code must compile as valid OPA Rego                                                 |

The Rego editor validates your code in real time as you type, so you can catch errors before saving.

***

## Managing Packages

### Viewing Your Packages

Navigate to **Governance** and select **Policy Packages** from the menu. The list page shows all packages for your account, with columns for name and description. You can search by name or description using the search bar.

### Creating a Package

1. On the **Policy Packages** page, click the **Add Policy Package** button (top right).
2. In the **Package Details** section:
   * **Package Name** (required) — enter a name that follows the [naming rules](#package-naming-rules) above. This cannot be changed after the package is created.
   * **Description** (optional) — a plain-text description of what the package provides.
3. In the **Rego Code** section, write your package logic in the editor. Do not include a `package` declaration or any `import` statements.
   * The editor validates your code in real time. A **✓ Rego code is valid** indicator appears when the code compiles successfully.
4. Click **Create**. A confirmation message confirms the package was saved and you are returned to the package list.

**Example package code** — a set of tag validation helpers:

```rego
# Returns true if the resource has the specified tag key.
has_tag(resource, key) {
  resource.tags[key]
}

# Returns true if the resource has all of the specified tag keys.
has_all_tags(resource, keys) {
  count([k | k := keys[_]; has_tag(resource, k)]) == count(keys)
}
```

### Editing a Package

1. On the **Policy Packages** page, click the row actions menu (**⋮**) next to the package and select **Edit**.
2. Update the description or Rego code as needed. The package name cannot be changed.
3. Click **Save**. All policies that import this package will use the updated code at their next evaluation — no changes to those policies are required.

### Deleting a Package

1. On the **Policy Packages** page, click the row actions menu (**⋮**) next to the package and select **Delete**, or use the **Delete** button on the package edit page.
2. Confirm the deletion in the dialog that appears.

> **Warning:** Deleting a package is immediate and permanent. If any policies still contain an `import data.firefly.packages.<name>` statement for the deleted package, those policies will fail to compile at their next evaluation. Remove the import from any referencing policies before deleting a package.

***

## Using Packages in Policies

### Adding an Import

To use a package in a policy, add an import statement at the top of the policy's Rego code, after any existing imports:

```rego
import data.firefly.packages.<package_name>
```

Replace `<package_name>` with the exact name of the package you want to use. You must add this import to each policy that needs the package.

### Using Package Functions in Policy Rules

Once the import is in place, call the package's functions or reference its data using the package name as a prefix:

```rego
import data.firefly.packages.tag_validator

default firefly = false

firefly {
  tag_validator.has_all_tags(input, ["team", "env", "owner"])
}
```

### Import Validation

As you edit a policy's Rego code, Firefly automatically validates that every `import data.firefly.packages.*` statement refers to a package that exists in your account. If a referenced package is not found, a warning is shown in the editor. This check runs automatically as you type.

***

## Required Permissions

| Action                                      | Required Permission |
| ------------------------------------------- | ------------------- |
| View the package list or a specific package | `governance:read`   |
| Create a package                            | `governance:create` |
| Edit a package                              | `governance:update` |
| Delete a package                            | `governance:delete` |

For information on configuring roles and permissions, see [Access Management (RBAC)](/getting-started/access-management-rbac.md).


---

# Agent Instructions: 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:

```
GET https://docs.firefly.ai/detailed-guides/policy-and-governance/rego-packages.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.