Repositories

A repository stores software and other files as versioned packages. Use it to distribute firmware images, application bundles, configuration files, or models. This reference defines the resource hierarchy, storage behavior, and retention rules. For a complete upload and download workflow, follow Publish Software Artifacts.

Resource Hierarchy

Repositories belong to organizations and are independent of projects. Several projects can use one repository, and one project can use several repositories. For example, testing and production projects can share firmware releases.

Repositories commonly follow team, product, or tenant boundaries. Use separate repositories when ownership or access policies differ. Within the same access boundary, use separate packages for components that release independently. This lets a system image and an application have their own release streams while sharing a repository’s storage and access configuration.

Within repositories, assets are organized in a hierarchical structure:

• Repositories contain packages and define their ownership and access policies.
• Packages group related assets that are released together, such as binaries for different architectures of one tool.
• Versions group a package’s assets at a specific point in time. Seal a version to prevent content changes and deletion.

Each version can have zero or more tags, such as latest or v2.0.1. Tags serve as human-readable, semantic references and must be uniquely associated with a version within the scope of a package. Tags can be either locked or floating:

• Locked tags are stable and always point to a specific version (e.g., v2.0.1).
• Floating tags may change over time to point to different versions (e.g., latest).

Adding a tag that is assigned to another version fails unless you reassign it. Only floating tags can be reassigned.

Nexigon Hub records when each tag was assigned to its current version and reports this time as assignedAt. Spreads of OTA updates start at this time by default.

Naming constraints for repositories, packages, and asset filenames follow the hierarchy:

• Repository names must be unique within a Nexigon instance.
• Package names must be unique within the scope of a repository.
• Asset filenames must be unique within the scope of a version.

Within a Nexigon instance, specific assets can then be referenced using an asset path of the form:

<repo>/<package>/<version-tag>/<asset-filename>

For example, the latest AARCH64 binary of the Nexigon CLI might be referenced as:

nexigon/nexigon-cli/latest/aarch64-unknown-linux-musl/nexigon-cli

A package path is <repository>/<package>. A version path adds a tag or a version ID: <repository>/<package>/<version>. Paths use names and tags; IDs identify the underlying resources independently of those names.

Visibility

Repositories can be public or private. By default, packages inherit the visibility of repositories. Public packages can be accessed by anyone without any authentication. In contrast, private packages require authentication.

Device Access

A project’s devices can consume private repository software when that repository is linked to their project. Under Project Settings → Repositories, link the repository before deploying its software. Unlinking removes device access.

A repository can be linked to several projects. Management clients still need their own permissions to publish or modify its contents.

S3 Storage

Repository assets are stored in an S3-compatible bucket. Organization administrators can set default storage on the organization’s Settings > Storage page. Repositories use these settings unless they have their own S3 configuration. Each configuration specifies an endpoint, bucket, optional region and key prefix, credentials, and addressing style.

Object Locations

Organization storage puts each repository in a separate directory:

<prefix>/repositories/<repository-id>/<digest>/<asset-id>

The prefix is optional. Use a separate bucket or prefix for each organization. Repository IDs keep object paths stable when display names change. IDs in storage paths omit their API type prefix, such as repo_. Existing objects keep their original keys without the asset ID suffix. New uploads include an asset ID so cleanup of an old asset cannot delete a later upload of the same content.

An explicit repository configuration overrides all organization settings. Its object keys use <prefix>/<digest>/<asset-id>, or <public-name-or-repository-id>/<digest>/<asset-id> when no prefix is set. Existing assets retain their original keys without the asset ID suffix. Storage failures do not trigger fallback. Select Use Organization Storage in repository S3 settings and confirm removal to remove an override.

Changing Storage Settings

Changing storage settings does not move existing objects. Removing settings does not delete objects, but artifacts become inaccessible if their effective storage location changes. Move objects to their new paths before changing a bucket or prefix. Removing organization storage requires confirmation and leaves repositories without overrides unconfigured.

Storage API

Secret access keys are encrypted and never returned by the settings API. Enter the secret again when saving a configuration. The public API provides organizations_SetS3Config, organizations_GetS3Config, and organizations_DeleteS3Config; repositories_DeleteS3Config restores inheritance. Organization storage actions require permission to manage the organization’s settings.

Addressing and Permissions

Nexigon uses virtual-hosted addressing by default, placing the bucket name before the endpoint hostname. Enable Force path-style addressing for services that instead require URLs in the form https://endpoint/bucket/key. Nexigon also uses path-style addressing automatically for IP endpoints and bucket names that cannot be used safely in a hostname.

“Test Configuration” lists at most one key below the configured prefix. The credentials therefore need permission to list the bucket, in addition to the object-level permissions used for uploads and downloads. Cleanup also requires permission to delete objects. Cleanup retries use the repository’s current storage settings. Keep existing objects accessible until cleanup finishes, or move them before changing the storage location.

Assets

An asset is a stored file identified by its content hash within a repository. Uploading the same content can reuse the existing asset.

Assets can be attached to packages and package versions. A single asset can be attached to several versions when a file remains unchanged across releases. Each attachment has its own filename and metadata.

For upload, attachment, and download commands, follow Publish Software Artifacts.

Storage Usage and Cleanup

The repository’s Assets tab shows storage usage, package reference counts, and cleanup status. Stored asset size counts each asset once, even when several versions reference it. Unused bytes are stored assets with no package or version attachments. Unknown, missing, or inconsistent objects are shown separately with their declared size. Totals reflect the latest storage checks and include assets awaiting deletion. They update transactionally when Nexigon Hub records storage changes or package attachments change; they do not wait for the next background scan.

Inspecting Assets

Use Next and Previous to browse assets. Filters and sorting apply to the whole repository, and storage totals cover all assets across every page. Changing a filter or sort order returns to the first page. Refresh reloads the inventory from the first page.

Select an asset’s reference count to see the packages, versions, and filenames retaining it. Large reference lists also have Next and Previous controls. Tags do not add references: an untagged version still retains its assets. Device properties, download URLs, vulnerability index rows, and references outside Nexigon Hub do not retain an asset.

Automatic Cleanup

Automatic cleanup is disabled by default for each repository. Organization administrators can enable it through Assets → Configure Cleanup and choose a grace period, which defaults to seven days. Enabling or re-enabling cleanup gives existing unused assets a full grace period. Uploads and reuse temporarily protect an asset while a client attaches it.

When the last attachment is removed, the grace period starts. Changes to the grace period apply to assets that are already unused. Adding an attachment before deletion starts cancels scheduled cleanup. Once deletion starts, Nexigon Hub rejects new attachments, upload URLs, upload finalization, and creation of the same digest in that repository. After cleanup completes, the content can be uploaded again as a new asset.

Disabling cleanup stops new automatic deletions. Deletions already started finish. Reference counts and storage totals remain available while cleanup is disabled.

Explicit Deletion

Delete Asset explicitly schedules deletion of an unused asset regardless of the automatic cleanup setting. Referenced assets must be detached first. Each upload URL protects the asset from physical deletion for four hours. Deleting a repository hides it immediately. Background maintenance detaches its packages and schedules its assets for deletion in batches. Nexigon Hub retains the repository and its effective storage settings until all its assets have been removed.

Cleanup Status and Accounting

Cleanup and storage checks run in bounded background batches. A large backlog or slow storage can delay completion.

Failed deletions remain visible with an error and are retried. Check storage credentials, delete permissions, and the reported object identity or prefix conflict. Nexigon Hub does not remove mismatched objects or objects whose keys are shared with another tracked asset.

Stored asset size describes the tracked current objects, rather than the bucket’s total billed usage. S3 versioning may retain older object versions after deletion; configure the bucket’s noncurrent-version lifecycle policy separately. Untracked objects, incomplete uploads, and provider overhead are also outside these totals.

Asset Query API

The repositories_QueryAssets and repositories_GetAssetReferences API actions accept page with an optional limit and cursor. Pass an empty page object for the default page size, then supply the returned page.nextCursor unchanged to continue with the same query. A missing next cursor marks the end. Omitting page preserves the full response for existing clients. Inventory requests also accept filter (All, Unused, or Issues) and sort (Largest or CleanupDate). Totals always describe the full repository.

Packages

Packages group related versions and can also have assets attached directly. Package names are unique within a repository. Each attachment has its own filename and metadata, independent of other attachments to the same asset.

Versions

A version groups a package’s files and metadata for one release or build. Create the version, attach its assets, then add tags for consumers to resolve. A version can exist without tags; removing a tag does not delete the version. See Publish Software Artifacts for this sequence.

Listing Versions and Tags

repositories_QueryPackageVersions lists the versions of a package, newest first. repositories_QueryPackageTags lists the tags of a package, most recently assigned first, each with the ID and name of the version it points to. Both return a single page, by default 100 entries. Clients that need every entry must follow page.nextCursor as described in Pagination.

A filter.search narrows either listing to entries containing the text, ignoring case. Versions match by their name, their ID, or one of their tags. Tags match by their name. To list the versions whose name, ID, or tags contain 2.4, send:

{
  "packageId": "<package-id>",
  "filter": { "search": "2.4" }
}

Sealed Versions

Sealing permanently protects a version’s contents and keeps it available while routine builds continue to arrive.

A sealed version cannot be renamed or deleted. Its metadata, base version, asset attachments, and attachment metadata cannot change. Sealing cancels any scheduled deletion and protects the version from package retention. Deleting its package or repository is permanently blocked.

Tags remain editable under their existing rules. You can add release tags or move a floating tag such as latest to another version. Downloads and vulnerability indexing remain available.

Sealing cannot be reversed. Complete the version’s contents, metadata, and base version before sealing it.

Base Versions

A version can name a base version, a version of the same package that a device must have run before it installs this version. OTA update integrations use base versions to route devices through checkpoint releases. Checkpoint Releases describes the rules and the commands for managing base versions.

A version that is the base of another version cannot be deleted or scheduled for deletion, and package retention skips it. A version scheduled for deletion cannot become a base.

Version Retention

Retention is configured per package and disabled by default. A policy can impose either or both limits:

• Unsealed versions to keep: Keep the newest N unsealed versions. Sealed versions and base versions do not count toward this limit.
• Maximum age (days): Delete unsealed versions after X days from creation. Each day is 24 hours.

At least one limit is required while retention is enabled. Newest means latest creation time, with creation sequence used to break equal timestamps.

Either exceeded limit permits deletion. For example, N = 100 and X = 30 keeps at most 100 unsealed versions, and none older than 30 days after cleanup completes. The age limit can leave fewer than N unsealed versions, including zero. Sealed versions and base versions are always retained.

Changes apply to existing versions during the next cleanup run, normally within five minutes. Downtime or a backlog can delay cleanup. Deletion is permanent. Explicit deletion schedules apply independently, so a deadline can delete an unsealed version that is still within both package limits.

Disabling retention stops deletion under the package policy. It does not cancel explicit deletion schedules. Seal a version to protect it from both mechanisms. Unused assets follow the repository’s storage cleanup policy.

Seal a Version

Sealing requires permission to manage package versions. The action appears in the repository audit log.

On a version card, choose More options → Seal Version. Review the permanent protection and confirm. Choose Cancel to continue preparing the version.

Configure Version Retention

Changing retention requires permission to manage package versions. Changes appear in the repository audit log.

In a package’s Versions tab, choose Version Retention and enable Automatically delete older versions. Set either or both limits, leaving a field empty to omit it. Review the effect on existing versions and choose Save Retention. Seal important releases before enabling a policy that could delete them.

To disable the policy, clear Automatically delete older versions and save.

Sealing and Retention API

The repositories_SealVersion action permanently seals a version with this input:

{ "versionId": "<version-id>" }

Repeated sealing requests succeed without changing the version or creating another audit event. The sealed field is read-only.

Configure a package with repositories_SetPackageVersionRetention:

{
  "packageId": "<package-id>",
  "retention": { "enabled": true, "maxVersions": 100, "maxAgeDays": 30 }
}

This action replaces the policy. Set enabled to false to disable it. Package details include retention; version lists and details include sealed. These fields and actions require a Nexigon Hub build that supports sealed versions and package retention.

Scheduled Deletion

A version can have a deletion deadline, for example to keep nightly builds for seven days. Versions have no deadline by default. This feature requires a Nexigon Hub build that supports scheduled version deletion.

In a package’s Versions tab, choose More options → Schedule Deletion. Enter a future date and time in UTC and save. The deadline appears on the version. To change it, choose Edit Deletion Schedule. Cancel Scheduled Deletion cancels the deadline. Package retention still applies. You can also enable Schedule deletion while creating a version.

A deadline is the earliest deletion time. Nexigon Hub checks deadlines every five minutes; downtime or a backlog can delay deletion. You can change or cancel a schedule until deletion commits. A version that has already been deleted cannot be restored.

Deletion removes the version, its metadata, all tags including locked tags, and its file attachments. It leaves the package and other versions intact. Deployed devices and rollback requirements do not prevent deletion. Seal any build needed for deployment or recovery. Deleting a version does not uninstall software already on devices.

Version deletion releases its asset references. To reclaim the resulting unused storage automatically, enable unused-asset cleanup. Its grace period starts when the last attachment is removed. Shared files remain available, and upload protection still applies.

Schedule Versions through the API

For build-pipeline commands, see scheduled builds in Nexigon CLI Next.

The public API accepts optional deleteAt on repositories_CreateVersion and returns it from repositories_QueryPackageVersions and repositories_GetVersionDetails. Set or replace a deadline with:

{
  "versionId": "<version-id>",
  "deleteAt": "2027-01-31T00:00:00Z"
}

Send this input to repositories_SetVersionDeletionSchedule. Set deleteAt to null, or omit it, to cancel the schedule. Schedule changes and completed deletions appear in the repository audit log.

Version Commands

Both list commands accept --search, --limit, and --cursor. Pass the page.nextCursor of the output as --cursor to list the next page.

Use a version ID when a later command must address the same build even if a floating tag moves.