Releases are an essential feature of github (or other platforms like gitea) and the assets you can attach are pretty useful if you want to pre-compile a binary for example.
But linking to these assets directly in your README can be pretty annoying if every of your release asset has a version number in it, for example program-v1.0.0, and with every release the version number changes, and you have to change the direct link to it in your README.
And this is where smartrelease enters the game.
It provides a simple yet powerful api endpoint which will redirect the user directly to the latest release asset you've specified in the api url.
Take me directly to the examples.
The api works with a single link which will take the user to the asset of the latest release you've specified. Its url scheme looks like the following:
https://example.com/:platform/:owner/:repository/:pattern
The platform is the hoster of your git repository. The current supported platforms are:
Currently, only the official instances are supported by the api (github has no instance for self-hosting anyway) but support for self-hostet instances is planned.
The owner is owner of the repository (mostly you).
The repository is the name of the repository you want to set up the api for.
pattern is the part where all the magic happens. The pattern you specify here is used to redirect the user to the asset you want. To archive this, wildcards as well as regex (see here for possible dangers with regex) can be used.
The following takes mostly care of wildcards since the official instance and default configurations are both only supporting wildcards and not regex.
Wildcards are simply nothing other than text fragments / variables / ... (whatever you want to call it) which are getting replaced with their corresponding values from the release name / tag.
These wildcards are currently supported:
-
majorThe major version number. It must always be a number. In
smartrelease-v1.21.5-rc4,1is the major version number.Note: The first number occurrence will always be matched as
major. At the moment I have no idea how I should avoid this and only match the first number if necessary but if you want create a new issue, and I will take further investigations how to solve this. -
minorThe minor version number. It must always be a number. In
smartrelease-v1.21.5-rc4,21is the minor version number. -
patchThe patch version number. It must always be a number. In
smartrelease-v1.21.5-rc4,5is the patch version number. -
preThe pre-release number. It can be a mix of numbers and letters (without any special characters between). In
smartrelease-v1.21.5-rc4,rc4is the pre-release number. -
tagThe release tag. In
https://github.com/ByteDream/smartrelease/releases/tag/v0.1.0,v0.1.0is the tag.
major, minor, patch and pre are all version number specific wildcards.
Hence, they are matched descending.
This means minor is only matched if major is matched, patch is only matched if minor is matched and so on.
I clearly can't name all cases here where the pattern matches your asset name or not, so if you want to check and test which name is support and which not, I suggest you to visit this website and type in your asset name in the big box. If it gets highlighted somewhere it is supported, if not then not. In case your asset name is not supported, but you want it to be supported, feel free to create a new issue or join the discord server and submit your asset name, so I can take care and implement it.
For the example the official instance is used as host.
Latest release for this repo. The result looks like this: Latest release
[Latest release](https://smartrelease.bytedream.dev/github/ByteDream/smartrelease/smartrelease-v{major}.{minor}.{patch}_linux)
We can also use shields.io to make it look more appealing to the user.
The result looks like this:
[](https://smartrelease.bytedream.dev/github/ByteDream/smartrelease/smartrelease-v{major}.{minor}.{patch}_linux)
And now with the official Gitea instance (Gitea is a great open-source based alternative to GitHub, if you didn't knew it already) The result looks like this: Now with gitea!
[Now with gitea!](https://smartrelease.bytedream.dev/gitea/gitea/tea/tea-{major}.{minor}.{patch}-linux-amd64)
The official instance is hosted on https://smartrelease.bytedream.dev.
It has regex disabled and a maximal pattern length of 70 characters.
So if you want, for example, using the official api for this repo, the following link will do it:
https://smartrelease.bytedream.dev/github/ByteDream/smartrelease/smartrelease-v{major}.{minor}.{patch}_linux
Nevertheless, I recommend you to host your own instance if you have the capabilities to do so since I cannot guarantee that my server will have a 100% uptime (but I will do my best to keep it online). I also recommend you to visit this repo from time to time to see if something will change / has already changed with the official instance.
All following instructions are specified for linux, but at least building should be possible on every platform.
Make sure you have docker installed.
You can simply pull and run the docker image from docker hub.
[~]$ docker run --name smartrelease -p 8080:8080 bytedream/smartrelease:latestDownload the latest linux binary from here (built with musl, so should work on libc and musl systems). Now simply execute binary and the server is up and running:
[~]$ ./smartrelease-v<version>_linuxMake sure you have the latest stable version of rust installed.
Clone the repo via git clone or download the zipfile and extract it.
Open a shell, enter the directory and follow the following commands:
[~/smartrelease]$ cargo build --release
[~/smartrelease]$ ./target/release/smartreleaseEvery configuration can be made with environment variables or via an .env file. See .example.env for an example configuration.
The host address. I don't really know a case where this has to be changed but to have the choice is always better.
Default is 0.0.0.0.
The port to serve the server on.
Default is 8080.
Enable or disable regex support in the pattern.
Default is false.
Limits the maximal length the pattern can have.
Default is 70.
If requests should always be made with https connections. Default is true.
If custom hosted instances of git servers should be supported too. Default is false.
The url scheme of using a custom git server follows this:
https://example.com/custom/:host/:platform/:owner/:repository/:pattern
:host is the url of the custom git server host. Subpaths are currently not supported.
It is recommended to limit the pattern length with MAX_PATTER_LEN if ENABLE_REGEX is enabled since a too long pattern which is too complex could lead to an, wanted or unwanted, ReDoS attack.
If you host it yourself it is highly recommended taking one of the "big" dns servers like 1.1.1.1 or 8.8.8.8 as your dns resolver.
The actix-web library which handles all the network stuff sometimes takes up too much time to resolve a dns address when the dns server is, for example, your local router.
And most of the time when this happens a 504 timeout error is thrown and the api is practically unusable.
This project is licensed under the MIT License - see the LICENSE file for more details.