Skip to content

File Repositories ​

A file repository is Hegemony's shared file store - the place for firmware images, scripts, and other assets your flows need. It is backed by S3-compatible object storage (the bundled Versity S3 Gateway by default), supports folder hierarchies, and records a SHA-256 checksum for every file.

File repositories are not the same as a flow's own Files tab: flow files are small text attachments versioned with the flow, while repository files are shared binaries available to every flow - see building flows for the former.

Repository names follow the platform's object name rules: trimmed, not blank, at most 128 characters, no word longer than 64, and no control characters.

Browse and organize ​

Pick a repository from the File Repository selector (the default one is preselected) and navigate folders through the breadcrumb bar. Each file row shows its size, truncated SHA-256, source (upload or URL import), and creation time. Click a file to open its detail page with full checksums, content type, storage location, and any metadata attached to it.

Folder tools sit in the browser toolbar: create a folder, rename the current one, or delete it once it is empty.

Add files ​

  • Upload - pick a local file, optionally attach JSON metadata such as {"platform": "iosxe", "version": "17.09.01"}.
  • Import from URL - have the platform download the file from an HTTP(S) URL. You can override the filename and supply an expected SHA-256; the import fails if the downloaded content does not match.

New files land in the repository root - use the row's Move action to file them into a folder afterwards.

Managing files (upload, import, move, delete, folder operations) requires the admin role; browsing and downloading is open to all users.

Use repository files in flows ​

A flow names a repository file by its repository and path:

json
{"repository": "Firmware", "path": "iosxe/17.9/cat9k_iosxe.17.09.05.SPA.bin"}

The path is the file's folder, a slash and its file name (just the file name for a file in the root). A name reads well in a flow, and it still works after the flow moves to another instance through Configuration Exchange, where file ids differ. The repository is looked up in the organization the run belongs to (for a shared organization's flow, the organization that runs it). The shared organization's repository is used only when that organization has no repository of the name; one of its own with the name hides the shared one, even for a file only the shared one holds. If two files with the same name sit in the same folder, the path is refused as ambiguous: delete or move the extra copy, which stays allowed while the other copy keeps the path.

Moving a file, or renaming or moving its folder, changes its path, so it is refused while a flow names the file by that path; the refusal lists the flows. Change those flows first. Renaming a repository is refused the same way while a flow names any of its files by repository name or limits a file field to it, and so is creating, renaming or importing a repository to the name of a shared one that this organization's flows find by that name. A flow that names the file only by id does not block a move or a rename. Deleting a file that a flow still names, either way, is refused.

Two steps download a repository file to a target: Download File to Device (netcli.file_download) for network devices and Download File to Host (shell.file_download) for Linux and Unix servers. Their File setting takes the file in one of two ways:

  • Pick it in the step. Browse File Repositories... opens the repository browser and stores the file's repository and path.
  • Let the operator pick it when the run starts. Add a Repository file field to the flow's run form (Form tab, category Files) and set the step's File to that field, for example {{ inputs.firmware }}. The field can be limited to one repository or one folder, and can take several files; a loop over inputs.firmware then runs the step once per file.

Each target downloads the file by itself, over HTTP or HTTPS, through a short-lived link the platform issues for that one file. Targets need to reach the platform (the address an administrator set as HEGEMONY_API_EXTERNAL_URL), not the object store. The server step checks the file's SHA-256 on the host itself. After the device step, add a step that verifies the file on the device. See Download links for targets.

The step's output describes the file it downloaded, so later steps can use it: file_id, filename, repository, path, folder, size_bytes, sha256, sha512, md5, content_type, metadata (what was uploaded with the file, such as {"version": "17.09.05"}), and file, a reference a later download step can take as its File: {{ steps.<step id>.output.file }}.

Older flows name the file by id (the step's File by id (legacy) setting, file_ids). They keep working. Such a step leaves path and file empty when the repository name and path would find another file: a shared organization's file, picked by id, whose path your organization's own repository of the same name also holds.

History card ​

The detail page carries a History card listing the most recent audit log entries about this object: how long ago, what the action was, which fields changed, who did it, and a non-success outcome where there was one. A row opens the same entry dialog the audit log uses, and the card links into the log filtered to this object. It appears only for callers who may read the audit log, so a viewer or approver sees the page without it.

Repository configuration (Settings) ​

Each organization has its own repositories and its own default. One is provisioned automatically against the deployment's shared object store and is marked Managed - its connection settings come from the deployment environment (HEGEMONY_S3_*) and are re-applied on every startup, so they cannot be edited here.

Settings → File Repositories lists them with their kind, endpoint, bucket, and prefix. Every signed-in user can open the list and a repository's page; the Settings hub shows the tile to anyone who may list repositories. An admin can add repositories, edit the ones that are not managed, switch which one is the organization's default, and delete a repository once it holds no files; for anyone else those controls appear locked rather than failing.

Repositories published by the shared organization appear with a Shared badge. They are readable from every organization - the same firmware image can be staged once centrally - but read-only here: uploads, folder changes, and edits are refused.

A repository either uses the deployment's own object storage or points at storage of your own. In the second case you supply the endpoint plus two secret references for the access key and secret key - the values themselves are never stored, only the references, and they are resolved when the repository is used. Test Connection on the repository page probes the bucket and reports whether the failure was credentials, networking, or a missing bucket.

For the full picture - storage kinds, connection modes, how shared-org credentials resolve, and how repositories travel through Configuration Exchange - see File Repository Storage and Connections.

Released as open source under the AGPL-3.0-or-later license. Development is sponsored by Rexonix s.r.o. Contact — [email protected].