Installing private packages

All Go modules are distributed via a module proxy. When running a Go command like go build or go get, Go’s toolchain communicates to proxies controlled by the GOPROXY environment variable. Its default value is:

GOPROXY="https://proxy.golang.org,direct"

proxy.golang.org is the main Go module proxy, run by Google. Its placement as a default provides benefits for security and availability. In case of an offline third party code repository, Google’s proxy is very likely to still be up, and can return a cached version of any third party module being requested so that builds don’t fail.

Go proxies are augmented by a checksum database, normally served by Google from sum.golang.org. The database persists an immutable checksum for known Go modules which Go’s toolchain can compare against fetched modules to verify that they haven’t been tampered with, even if the modules came in by way of a third party Go proxy.

Private modules like River Pro are not publicly available to other Go module proxies and therefore cannot appear in the checksum database. For this reason, private modules prefixes must be added to the GONOSUMDB environment variable to prevent Go from attempting to verify checksums for them.

River Pro for Ruby is distributed as riverqueue-pro from https://riverqueue.com/rubygems. Scope that source to the Pro gem in your Gemfile, keeping rubygems.org as the default for public dependencies:

source "https://rubygems.org"

source "https://riverqueue.com/rubygems" do
  gem "riverqueue-pro"
end

The private source only serves Pro packages; it does not proxy public gems. Keep your core River gem, driver, and database adapter in the same Gemfile as described in getting started.

The Rust client is the riverqueue-pro crate. Its separate riverqueue-pro-cli package installs the Pro-enabled riverqueue executable. The initial alpha release is available through River’s authenticated Cargo registry.

Configure the river registry as described below, and select it only for Pro dependencies:

[dependencies]
riverqueue = "=0.6.0"
riverqueue-pro = { version = "=0.1.0-alpha.1", registry = "river" }

Public dependencies continue to come from crates.io. See the getting-started guide for the compatible version pair and Cargo features.

River Pro is distributed via a private Go proxy hosted at riverqueue.com/goproxy. It requires a customer-specific private credential obtained during the Pro subscription process that looks like river_secret_<secret>.

export RIVER_PRO_SECRET=river_secret_...
export GOPROXY=https://proxy.golang.org,https://river:$RIVER_PRO_SECRET@riverqueue.com/goproxy,direct
export GONOSUMDB=riverqueue.com/riverpro,$GONOSUMDB

go get riverqueue.com/riverpro
go get riverqueue.com/riverpro/driver/riverpropgxv5

# install riverpro CLI:
go install riverqueue.com/riverpro/cmd/riverpro@latest

Assuming everything worked, Go will have updated the project’s go.mod and go.sum files with new entries for River Pro.

Notably, the recommendation for GOPROXY above installs River’s module proxy as second priority after proxy.golang.org. Module fetches will prefer Google’s main proxy and only fall back to River’s for modules that couldn’t be found.

See also installing in CI and build environments.

Configure Bundler credentials for the host using your River Pro license key:

bundle config set --local riverqueue.com 'river:river_secret_...'
bundle install

Bundler stores local credentials in .bundle/config; exclude this file from version control. Commit the updated Gemfile and Gemfile.lock.

Use the river username and your customer license key as the password. The credentials are the same ones used for other River Pro package sources. Internal Go bootstrap credentials cannot access the RubyGems source.

If you previously used the root source URL, change it to https://riverqueue.com/rubygems and run bundle install to update the lockfile. Host-based credentials continue to work.

Configure the registry and authenticate before building:

export CARGO_REGISTRIES_RIVER_INDEX='sparse+https://riverqueue.com/cargo/'
export CARGO_REGISTRIES_RIVER_CREDENTIAL_PROVIDER='cargo:token'
cargo login --registry river
cargo build

Enter your River Pro license key (river_secret_...) when prompted, without a username or URL encoding. Commit Cargo.toml and Cargo.lock; keep the credential outside the repository. Install the Pro CLI separately.

The instructions above recommended a value for GOPROXY like:

GOPROXY=https://proxy.golang.org,https://river:$RIVER_PRO_SECRET@riverqueue.com/goproxy,direct

This requires the presence of the RIVER_PRO_SECRET in the environment. Keeping secrets in a shell environment is generally undesirable because there needs to be a mechanism for the secret to get there in the first place, and there’s a higher likelihood that it can accidentally leak.

Go supports configuring proxy credentials in a ~/.netrc file, a standard supported by other tools like cURL and Git. Add an entry containing a River secret like the following:

machine riverqueue.com
login river
password river_secret_...

This makes it possible to use GOPROXY without an inline key:

export GOPROXY=https://proxy.golang.org,https://riverqueue.com/goproxy,direct
export GONOSUMDB=riverqueue.com/riverpro,$GONOSUMDB

go get riverqueue.com/riverpro
go get riverqueue.com/riverpro/driver/riverpropgxv5

Use local Bundler configuration to keep credentials out of the Gemfile:

bundle config set --local riverqueue.com 'river:river_secret_...'

Exclude .bundle/config from version control and the Docker build context.

With the registry index and cargo:token provider configured, store your River Pro license key interactively:

cargo login --registry river

Cargo stores this token in its user credentials file. Keep that file out of source control and container images. In CI, supply CARGO_REGISTRIES_RIVER_TOKEN from your secret store instead. See Cargo registry authentication.

GOPROXY and GONOSUMDB are normal environment variables, and can be configured in a shell env/RC file like ~/.zshenv or ~/.zshrc.

Another option is to use the Go toolchain’s built-in go env for managing variables that’ll be scoped specifically to Go commands.

go env -w GOPROXY=https://proxy.golang.org,https://riverqueue.com/goproxy,direct
go env -w GONOSUMDB=riverqueue.com/riverpro

# or, with a secret inline instead of being read from `~/.netrc`
go env -w GOPROXY=https://proxy.golang.org,https://river:river_secret_...@riverqueue.com/goproxy,direct

go get riverqueue.com/riverpro
go get riverqueue.com/riverpro/driver/riverpropgxv5

A River secret is still required, and may be configured in ~/.netrc above, or set directly as a static string with go env -w GOPROXY=.

To share the credential across your local Ruby projects, Bundler also supports user-wide configuration:

bundle config set --global riverqueue.com 'river:river_secret_...'

This writes to your user Bundler configuration. Use --local when credentials should be scoped to one project.

For configuration shared across local projects and CLI installation, put the registry settings in ~/.cargo/config.toml:

[registries.river]
index = "sparse+https://riverqueue.com/cargo/"
credential-provider = "cargo:token"

Keep the token in Cargo’s credentials file, not this configuration. cargo install --registry river does not read a project’s .cargo/config.toml, so use user-level configuration or environment variables for CLI installation.

Setting GOPROXY/GONOSUMDB to either a shell RC file or with go env -w has a less-than-optimal side effect of making the new configuration global across all your Go projects. This isn’t harmful, but this sort of configuration leakage is generally not considered best practice.

Projects can avoid this by using a tool like direnv to manage project-specific environment variables:

# contents of `~/.envrc` is a project directory
export GOPROXY=https://proxy.golang.org,https://riverqueue.com/goproxy,direct
export GONOSUMDB=riverqueue.com/riverpro,$GONOSUMDB

# or, with secret inline instead of being read from `~/.netrc`
export GOPROXY=https://proxy.golang.org,https://river:river_secret_...@riverqueue.com/goproxy,direct

This approach has the downside that all developers will need to have direnv installed for it to work, but the upside that especially when using a private Git repository, an .envrc file can be checked in to enable configuration-free Go builds that need only a git clone ... && cd ... && go build.

Bundler can also read the credential from the environment. Supply RIVER_PRO_SECRET through your secret manager or local environment, then set:

export BUNDLE_RIVERQUEUE__COM="river:$RIVER_PRO_SECRET"
bundle install

Bundler maps dots in riverqueue.com to double underscores. The same variable works in a project-specific environment managed with direnv, or in CI. Keep the actual secret out of committed environment files.

A project environment can set the registry and provider, while the secret manager supplies CARGO_REGISTRIES_RIVER_TOKEN:

export CARGO_REGISTRIES_RIVER_INDEX='sparse+https://riverqueue.com/cargo/'
export CARGO_REGISTRIES_RIVER_CREDENTIAL_PROVIDER='cargo:token'
cargo build --locked

These settings also work with direnv; keep the actual token out of committed environment files.

If you’re using River Pro, you will also need it to be available in a CI environment like GitHub Actions so it can run a test suite that uses features specific to River Pro. This can be accomplished by adding a Pro key as a GitHub repository secret, then observing the usual GOPROXY/GONOSUMDB environment variables:

- name: Setup Go
  uses: actions/setup-go@v5
  with:
    go-version: "stable"
    check-latest: true

- name: Install River Pro CLI
  run: go install riverqueue.com/riverpro/cmd/riverpro@latest
  env:
    GOPROXY: https://proxy.golang.org,https://river:${{ secrets.RIVER_PRO_SECRET }}@riverqueue.com/goproxy,direct
    GONOSUMDB: riverqueue.com/riverpro

- name: Migrate River
  run: |
    riverpro migrate-up --database-url "$DATABASE_URL"
    riverpro migrate-up --database-url "$DATABASE_URL" --line pro

- name: Go test
  run: go test ./...
  env:
    GOPROXY: https://proxy.golang.org,https://river:${{ secrets.RIVER_PRO_SECRET }}@riverqueue.com/goproxy,direct
    GONOSUMDB: riverqueue.com/riverpro

Store RIVER_PRO_SECRET as a GitHub Actions secret and set Bundler’s host credential on the step that installs dependencies. With Ruby already installed by your workflow:

- name: Install dependencies
  run: bundle install
  env:
    BUNDLE_RIVERQUEUE__COM: river:${{ secrets.RIVER_PRO_SECRET }}

- name: Migrate River
  run: |
    bundle exec river migrate-up --database-url "$DATABASE_URL"
    bundle exec river migrate-up --database-url "$DATABASE_URL" --line pro

- name: Run tests
  run: bundle exec rake test

Set DATABASE_URL for the migration step and use your application’s test command. If ruby/setup-ruby installs dependencies with bundler-cache: true, provide BUNDLE_RIVERQUEUE__COM on that setup step instead.

With Rust 1.95 or newer installed, configure the registry and supply your license key through an Actions secret:

- name: Build application and migration CLI
  run: |
    cargo build --release --locked
    cargo install riverqueue-pro-cli --registry river --version 0.1.0-alpha.1 --locked --root ./river-cli
  env:
    CARGO_REGISTRIES_RIVER_INDEX: sparse+https://riverqueue.com/cargo/
    CARGO_REGISTRIES_RIVER_CREDENTIAL_PROVIDER: cargo:token
    CARGO_REGISTRIES_RIVER_TOKEN: ${{ secrets.RIVER_PRO_SECRET }}

- name: Migrate River
  run: |
    ./river-cli/bin/riverqueue migrate-up --line main
    ./river-cli/bin/riverqueue migrate-up --line pro
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}

Store your River Pro license key as the Actions secret RIVER_PRO_SECRET. The migration step needs the database connection, but no Cargo credential. See the getting-started guide for CLI installation details.

In order to deploy a River Pro app, you may need to build it within a Docker image. Using River’s module proxy in a Dockerfile is typically done by mounting a secret into the container:

COPY go.mod go.sum ./
RUN --mount=type=secret,id=river_pro_secret,dst=/etc/secrets/river_pro_secret \
  sh -c 'GOPROXY=https://proxy.golang.org,https://river:$(cat /etc/secrets/river_pro_secret)@riverqueue.com/goproxy,direct \
  go mod download'

When building the Docker image, you’ll need to pass the secret to the build command with a source such as env or file:

docker build --secret id=river_pro_secret,env=RIVER_PRO_SECRET ...

Use a Docker BuildKit secret for the credential during bundle install:

COPY Gemfile Gemfile.lock ./
RUN --mount=type=secret,id=river_pro_secret,required=true \
    BUNDLE_RIVERQUEUE__COM="river:$(cat /run/secrets/river_pro_secret)" bundle install

Pass the secret from the build environment:

docker build --secret id=river_pro_secret,env=RIVER_PRO_SECRET .

Keep .bundle/config out of the build context with .dockerignore. BuildKit mounts the secret for the install command without storing the credential in an image layer.

Mount your River Pro license key as a BuildKit secret in a Rust 1.95 or newer build stage:

ENV CARGO_REGISTRIES_RIVER_INDEX=sparse+https://riverqueue.com/cargo/
ENV CARGO_REGISTRIES_RIVER_CREDENTIAL_PROVIDER=cargo:token
COPY . .
RUN --mount=type=secret,id=river_pro_cargo_token,required=true \
    CARGO_REGISTRIES_RIVER_TOKEN="$(cat /run/secrets/river_pro_cargo_token)" \
    cargo build --release --locked
RUN --mount=type=secret,id=river_pro_cargo_token,required=true \
    CARGO_REGISTRIES_RIVER_TOKEN="$(cat /run/secrets/river_pro_cargo_token)" \
    cargo install riverqueue-pro-cli --registry river \
      --version 0.1.0-alpha.1 --locked --root /river-cli

Supply the license key from your environment as the build secret:

docker build \
  --secret id=river_pro_cargo_token,env=CARGO_REGISTRIES_RIVER_TOKEN .

Copy the application executable and /river-cli/bin/riverqueue into the runtime stage. Exclude Cargo credentials and local secret files from the build context. See deploying without Cargo for runtime requirements.