From 8aa76d0486272a4b573f2b5836e55c7b990c29b6 Mon Sep 17 00:00:00 2001 From: Dave Rolsky Date: Tue, 24 Dec 2024 17:09:50 -0600 Subject: [PATCH] Fix docs now that GitLab is supported. --- README.md | 97 ++++++++++++++++++++++++++-------------------- ubi/src/builder.rs | 21 +++++----- ubi/src/ubi.rs | 6 +-- 3 files changed, 69 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 97e30dc..9963e65 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # The Universal Binary Installer Library and CLI Tool -When I say "universal", I mean it downloads binaries from GitHub releases. +When I say "universal", I mean it downloads binaries from GitHub or GitLab releases. When I say "binary", I mean it handles single-file executables like those created by most Go and Rust projects. @@ -75,45 +75,51 @@ current directory. ## How to Use It ``` -USAGE: - ubi [OPTIONS] - -OPTIONS: - -d, --debug Enable debugging output - -e, --exe The name of this project's executable. By default this is the same - as the project name, so for houseabsolute/precious we look for - precious or precious.exe. When running on Windows the ".exe" suffix - will be added as needed. - -h, --help Print help information - -i, --in The directory in which the binary should be placed. Defaults to - ./bin. - -m, --matching A string that will be matched against the release filename when - there are multiple files for your OS/arch, i.e. "gnu" or "musl". - Note that this will be ignored if there is only used when there is - only one matching release filename for your OS/arch - -p, --project The project you want to install, like houseabsolute/precious or - https://github.com/houseabsolute/precious. - -q, --quiet Suppresses most output - --self-upgrade Use ubi to upgrade to the latest version of ubi. The --exe, --in, - --project, --tag, and --url args will be ignored. - -t, --tag The tag to download. Defaults to the latest release. - -u, --url The url of the file to download. This can be provided instead of a - project or tag. This will not use the GitHub API, so you will never - hit the GitHub API limits. This means you do not need to set a - GITHUB_TOKEN env var except for private repos. - -v, --verbose Enable verbose output - -V, --version Print version information +Usage: ubi [OPTIONS] + +Options: + -p, --project The project you want to install, like houseabsolute/precious or + https://github.com/houseabsolute/precious. + -t, --tag The tag to download. Defaults to the latest release. + -u, --url The url of the file to download. This can be provided instead of a + project or tag. This will not use the GitHub API, so you will never hit + the GitHub API limits. This means you do not need to set a GITHUB_TOKEN + env var except for private repos. + --self-upgrade Use ubi to upgrade to the latest version of ubi. The --exe, --in, + --project, --tag, and --url args will be ignored. + -i, --in The directory in which the binary should be placed. Defaults to ./bin. + -e, --exe The name of this project's executable. By default this is the same as + the project name, so for houseabsolute/precious we look for precious or + precious.exe. When running on Windows the ".exe" suffix will be added + as needed. + -m, --matching A string that will be matched against the release filename when there + are multiple matching files for your OS/arch. For example, there may be + multiple releases for an OS/arch that differ by compiler (MSVC vs. gcc) + or linked libc (glibc vs. musl). Note that this will be ignored if + there is only one matching release filename for your OS/arch. + --forge The forge to use. If this isn't set, then the value of --url will be + checked for gitlab.com. If --url contains any other domain _or_ if it + is not, the default is GitHub. [possible values: github, gitlab] + -v, --verbose Enable verbose output. + -d, --debug Enable debugging output. + -q, --quiet Suppresses most output. + -h, --help Print help + -V, --version Print version ``` -## Using a GitHub Token +## Using a Forge Token -If the `GITHUB_TOKEN` environment variable is set, then this will be used for all API calls. This is -required to download releases for a private project. If you are running `ubi` in a CI environment -that runs jobs frequently, you may also need this, as GitHub has a very low rate limit for anonymous -API requests. +You can set a token for GitHub in the `GITHUB_TOKEN` environment variable. For GitLab, you can +either use `CI_JOB_TOKEN` or `GITLAB_TOKEN`. The former is set in GitLab CI automatically, and it +will be preferred if both are set. -However, you can also use the `--url` option to bypass the GitHub API by providing the download link -directly. +If a token environment variable is set, then this will be used for all API calls. This is required +to download releases for a private project. If you are running `ubi` against GitHub in a CI +environment that runs jobs frequently, you may also need this, as GitHub has a very low rate limit +for anonymous API requests. + +However, you can also use the `--url` option to bypass the forge site API by providing the download +link directly. ## Upgrading `ubi` @@ -126,12 +132,16 @@ On Windows, this leaves behind a file named `ubi-old.exe` that must be deleted m There are a few things you'll want to consider when using `ubi` in CI. -First, there are -[the GitHub API rate limits](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting). -This limit can be as low as 60 requests per hour per IP when not providing a `GITHUB_TOKEN`, so you -will almost certainly want to provide this. When running in GitHub Actions you can use the -`${{ secrets.GITHUB_TOKEN }}` syntax to set this env var, and in that case the rate limits are per -repository. +First, there are forge site API rate limits. See the +[GitHub API rate limits documentation](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting) +and +[GitLab API rate limits documentation](https://docs.gitlab.com/ee/user/gitlab_com/index.html#gitlabcom-specific-rate-limits). + +The GitHub limit can be as low as 60 requests per hour per IP when not providing a `GITHUB_TOKEN`, +so you will almost certainly want to provide this if you are getting releases from GitHub. + +When running in GitHub Actions you can use the `${{ secrets.GITHUB_TOKEN }}` syntax to set this env +var, and in that case the rate limits are per repository. ```yaml - name: Install UBI @@ -151,6 +161,9 @@ repository. GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` +Similarly, the GitLab CI system sets a `CI_JOB_TOKEN` for all jobs. Make sure to pass this to UBI +when you use it to install something from GitLab in CI. + If you only run `ubi` on one platform, you can avoid hitting the GitHub API entirely by using the `--url` parameter. But if you run on multiple platforms this can be tedious to maintain and it largely defeats the purpose of using `ubi`. diff --git a/ubi/src/builder.rs b/ubi/src/builder.rs index f31059b..71fdfe5 100644 --- a/ubi/src/builder.rs +++ b/ubi/src/builder.rs @@ -44,9 +44,10 @@ impl<'a> UbiBuilder<'a> { } /// Set the project to download from. This can either be just the org/name, like - /// `houseabsolute/precious`, or the complete GitHub URL to the project, like - /// `https://github.com/houseabsolute/precious`. It also accepts a URL to any page in the - /// project, like `https://github.com/houseabsolute/precious/releases`. + /// `houseabsolute/precious`, or the complete forge site URL to the project, like + /// `https://github.com/houseabsolute/precious` or `https://gitlab.com/gitlab-org/cli`. It also + /// accepts a URL to any page in the project, like + /// `https://github.com/houseabsolute/precious/releases`. /// /// You must set this or set `url`, but not both. #[must_use] @@ -63,10 +64,10 @@ impl<'a> UbiBuilder<'a> { self } - /// Set the URL to download from. This can be provided instead of a project or tag. This will - /// not use the GitHub API, so you will never hit the GitHub API limits. That in turn means you - /// won't have to set a `GITHUB_TOKEN` env var except when downloading a release from a private - /// repo when the URL is set. + /// Set the URL to download from. This can be provided instead of a project or tag. This will not + /// use the forge site API, so you will never hit API limits. That in turn means you won't have + /// to set a token env var except when downloading a release from a private repo when the URL is + /// set. /// /// You must set this or set `project`, but not both. #[must_use] @@ -110,8 +111,8 @@ impl<'a> UbiBuilder<'a> { } /// Set a GitLab token to use for API requests. If this is not set then this will be taken from - ////the `CI_JOB_TOKEN` or `GITLAB_TOKEN` env var if one of these is set. If both are set, then - /// the value `CI_JOB_TOKEN` will be used. + /// the `CI_JOB_TOKEN` or `GITLAB_TOKEN` env var, if one of these is set. If both are set, then + /// the value in `CI_JOB_TOKEN` will be used. #[must_use] pub fn gitlab_token(mut self, token: &'a str) -> Self { self.gitlab_token = Some(token); @@ -146,7 +147,7 @@ impl<'a> UbiBuilder<'a> { } /// Set the base URL for the forge site's API. This is useful for testing or if you want to operate - /// against an Enterprise version of GitHub or GitLab, + /// against an Enterprise version of GitHub or GitLab. #[must_use] pub fn url_base(mut self, url_base: String) -> Self { self.url_base = Some(url_base); diff --git a/ubi/src/ubi.rs b/ubi/src/ubi.rs index 2bc2eb4..3db9ae5 100644 --- a/ubi/src/ubi.rs +++ b/ubi/src/ubi.rs @@ -62,9 +62,9 @@ impl<'a> Ubi<'a> { /// /// There are a number of cases where an error can be returned: /// - /// * Network errors on requests to GitHub. - /// * You've reached the API limits for GitHub (try setting the `GITHUB_TOKEN` env var to - /// increase these). + /// * Network errors on requests to the forge site (GitHub, GitLab, etc.). + /// * You've reached the API limits for the forge site (try setting the appropriate token env var + /// to increase these). /// * Unable to find the requested project. /// * Unable to find a match for the platform on which the code is running. /// * Unable to unpack/uncompress the downloaded release file.