Skip to main content

Universal

The Universal Repository introduces a flexible way to manage and proxy artifacts that don’t conform to standard package types like npm, PyPI, Maven, or Docker.
This repository type is ideal for artifacts requiring custom organization and dynamic URL support, making it especially useful for hosting or caching files from sources such as GitHub Releases.

Understanding Placeholders​

When creating a Remote Universal Repository, placeholders allow RepoFlow to dynamically replace parts of the URL based on what is being requested.
They act as variables that change automatically depending on the requested package, version, or file name.

Available placeholders:

  • {package-name} — the name of the package or project
  • {version} — the version tag or release name
  • {file} — the actual file name being downloaded

These placeholders are required so RepoFlow can correctly route and cache requests for different files without needing to hardcode every version or release URL.

Examples of Remote Repository URLs​

  1. GitHub Releases
    URL: https://github.com/{package-name}/releases/download/{version}/{file}

  2. GitLab Releases
    URL: https://gitlab.com/{package-name}/-/archive/{version}/{file}

Example: Caching GitHub Releases​

If you want to cache multiple releases of a project from GitHub, create a Remote Universal Repository with the following URL pattern:

Remote URL Pattern
https://github.com/{package-name}/releases/download/{version}/{file}

Then, when requesting a release through RepoFlow, you can access it using:

RepoFlow URL Pattern
https://api.repoflow.io/universal/<workspace-name>/<repository-name>/{package-name}/{version}/{file}

For example, to download Git LFS for macOS ARM64 v3.5.1:

Remote URL
https://github.com/git-lfs/git-lfs/releases/download/v3.5.1/git-lfs-darwin-arm64-v3.5.1.zip

You can access it from RepoFlow like this:

RepoFlow URL
https://api.repoflow.io/universal/<workspace-name>/<repository-name>/git-lfs/git-lfs/v3.5.1/git-lfs-darwin-arm64-v3.5.1.zip

This way, RepoFlow will fetch and cache the release automatically, serving it locally for future requests.

GitHub-compatible download paths​

Starting in 0.9.2, universal repositories also accept GitHub release download paths:

https://api.repoflow.io/api/universal/<workspace-name>/<repository-name>/{package-name}/releases/download/{version}/{file}

For example:

https://api.repoflow.io/api/universal/<workspace-name>/<repository-name>/git-lfs/git-lfs/releases/download/v3.5.1/git-lfs-darwin-arm64-v3.5.1.zip

Configure the remote repository URL with the same GitHub template shown above. Tools that preserve the GitHub download path can then replace the GitHub base URL with the RepoFlow repository URL without a reverse-proxy rewrite. The same path format can be used with Gitea and Forgejo remotes configured with their corresponding source URL.

Existing universal paths take precedence. If the original interpretation returns not found, RepoFlow tries the GitHub-compatible interpretation using the same download permissions and rules.

GitLab-compatible download paths​

Starting in 0.9.2, universal repositories also accept GitLab permanent release asset links, including nested asset paths:

https://api.repoflow.io/api/universal/<workspace-name>/<repository-name>/{package-name}/-/releases/{version}/downloads/{file}

Configure the remote URL as:

https://gitlab.com/{package-name}/-/releases/{version}/downloads/{file}

For example, a project acme/app with tag v1.0 and asset path bin/app.zip can be downloaded through RepoFlow at:

https://api.repoflow.io/api/universal/<workspace-name>/<repository-name>/acme/app/-/releases/v1.0/downloads/bin/app.zip

The asset must have a permanent release link configured in GitLab. Existing universal paths take precedence; the GitLab interpretation is tried only after not found. This alias supports explicit release tags, not GitLab's permalink/latest or CI job artifact URLs.