Skip to content

Nix User Repositories

After releasing to GitHub, GitLab, or Gitea, GoReleaser can generate and publish a nix derivation to an existing Nix User Repository.

The nix section specifies how the pkgs should be created:

.goreleaser.yaml
nix:
  - #
    # Name of the recipe
    #
    # Default: the project name.
    # Templates: allowed.
    name: myproject

    # IDs of the archives to use.
    # Empty means all IDs.
    ids:
      - foo
      - bar

    # GOAMD64 to specify which amd64 version to use if there are multiple
    # versions from the build section.
    #
    # Default: v1.
    goamd64: v1

    # URL which is determined by the given Token (github, gitlab or gitea).
    #
    # Default depends on the client.
    # Templates: allowed.
    url_template: "https://github.mycompany.com/foo/bar/releases/download/{{ .Tag }}/{{ .ArtifactName }}"

    # The project name and current git tag are used in the format string.
    #
    # Templates: allowed.
    commit_msg_template: "{{ .ProjectName }}: {{ .Tag }}"

    # Path for the file inside the repository.
    #
    # Default: pkgs/<name>/default.nix.
    # Templates: allowed.
    path: pkgs/foo.nix

    # Your app's homepage.
    #
    # Templates: allowed.
    # Default: inferred from global metadata.
    homepage: "https://example.com/"

    # Your app's description.
    #
    # Templates: allowed.
    # Default: inferred from global metadata.
    description: "Software to create fast and easy drum rolls."

    # License name.
    #
    # Default: inferred from global metadata.
    license: "mit"

    # Setting this will prevent goreleaser to actually try to commit the updated
    # package - instead, it will be stored on the dist directory only,
    # leaving the responsibility of publishing it to the user.
    #
    # If set to auto, the release will not be uploaded to the repository
    # in case there is an indicator for prerelease in the tag e.g. v1.0.0-rc1
    #
    # Templates: allowed.
    skip_upload: true

    # Runtime dependencies of the package.
    dependencies:
    - zsh
    - chromium
    - name: bash
      os: linux
    - name: fish
      os: darwin

    # Custom install script.
    #
    # Default: 'mkdir -p $out/bin; cp -vr $binary $out/bin/$binary', and
    #   `makeWrapper` if `dependencies` were provided.
    # Templates: allowed.
    install: |
      mkdir -p $out/bin
      cp -vr ./foo $out/bin/foo

    # Custom additional install instructions.
    # This has the advantage of preventing you to rewrite the `install` script
    # if the defaults work for you.
    #
    # Templates: allowed.
    extra_install: |
      installManPage ./manpages/foo.1.gz

    # Custom post_install script.
    # Could be used to do any additional work after the "install" script
    #
    # Templates: allowed.
    post_install: |
      installShellCompletion ./completions/*

    # Format the generated file.
    # Valid options: 'nixfmt', 'alejandra'.
    #
    # 
Since v2.14
formatter: nixfmt # Repository to push the generated files to. repository: # Repository owner. # # Templates: allowed. owner: caarlos0 # Repository name. # # Templates: allowed. name: my-repo # Optionally a branch can be provided. # # Default: default repository branch. # Templates: allowed. branch: main # Optionally a token can be provided, if it differs from the token # provided to GoReleaser # # Templates: allowed. token: "{{ .Env.GITHUB_PERSONAL_AUTH_TOKEN }}" # Optionally specify if this is a token from another SCM, allowing to # cross-publish. # # Only taken into account if `token` is set. # # Valid options: # - 'github' # - 'gitlab' # - 'gitea' # # This feature is only available in GoReleaser Pro. token_type: "github" # Sets up pull request creation instead of just pushing to the given branch. # Make sure the 'branch' property is different from base before enabling # it. # # This might require a personal access token. pull_request: # Whether to enable it or not. enabled: true # Whether to open the PR as a draft or not. draft: true # If the pull request template has checkboxes, enabling this will # check all of them. # # This feature is only available in GoReleaser Pro, and when the pull # request is being opened on GitHub. check_boxes: true # Allows to set a body for the pull request. # If the repository has a pull request template, it will be appended to # this. # # Since: v2.12. body: | cc/ @foobar # Base can also be another repository, in which case the owner and name # above will be used as HEAD, allowing cross-repository pull requests. base: owner: goreleaser name: my-repo branch: main # Clone, create the file, commit and push, to a regular Git repository. # # Notice that this will only have any effect if the given URL is not # empty. git: # The Git URL to push. # # Templates: allowed. url: 'ssh://[email protected]:repo.git' # The SSH private key that should be used to commit to the Git # repository. # This can either be a path or the key contents. # # IMPORTANT: the key must not be password-protected. # # WARNING: do not expose your private key in the configuration file! # # Templates: allowed. private_key: '{{ .Env.PRIVATE_KEY_PATH }}' # The value to be passed to `GIT_SSH_COMMAND`. # This is mainly used to specify the SSH private key used to pull/push # to the Git URL. # # Default: 'ssh -i {{ .KeyPath }} -o StrictHostKeyChecking=accept-new -F /dev/null'. # Templates: allowed. ssh_command: 'ssh -i {{ .Env.KEY }} -o SomeOption=yes' # Git author used to commit to the repository. # # {{< inline_version "v2.11" >}} # Default: inferred from global metadata. {{< inline_version "v2.12" >}} commit_author: # Git author name. # # Templates: allowed. name: goreleaserbot # Git author email. # # Templates: allowed. email: [email protected] # Git commit signing configuration. # Only useful if repository is of type 'git'. # # Since: v2.11. signing: # Enable commit signing. enabled: true # The signing key to use. # Can be a key ID, fingerprint, email address, or path to a key file. # # Templates: allowed. key: "{{ .Env.GPG_SIGNING_KEY }}" # The GPG program to use for signing. # # Templates: allowed. program: gpg2 # The signature format to use. # # Valid options: openpgp, x509, ssh. # Default: openpgp. format: openpgp
Learn more about the template language.

Things not supported

  • Generating packages that compile from source (using buildGoModule)
  • Generating packages when archives.format is binary

Dependencies

nix-hash

The nix-hash binary must be available in the $PATH for the publishing to work.

GitHub Actions

To publish a package from one repository to another using GitHub Actions, you cannot use the default action token. You must use a separate token with content write privileges for the tap repository. You can check the resource not accessible by integration for more information.

Setting up a NUR

To set up a Nix User Repository, follow the instructions in their repository.

Then, you’ll need to:

  • publish a release with GoReleaser: it should create the package at ./pkgs/{name}/default.nix or whatever path you set it up to
  • make sure ./flake.nix is correct with what you want, especially the systems bit
  • add your package to ./default.nix
  • edit your README.md removing the template stuff

That’s it!

Pull Requests

GoReleaser allows you to, instead of pushing directly to the main branch, push to a feature branch, and open a pull requests with the changes.

Templates

GoReleaser will check for a .github/PULL_REQUEST_TEMPLATE.md, and set it in the pull request body if it exists.

We do that to prevent extra work for maintainers of things like winget-pkgs, nixpkgs, and so on.

Cross-repository pull requests

You can also push to a fork, and open the pull request in the original branch.

Here’s an example on how to set it up:

.goreleaser.yaml
something: # can be nix, brews, etc...
  - repository:
      owner: john
      name: repo
      branch: "{{.ProjectName}}-{{.Version}}"
      pull_request:
        enabled: true
        base:
          owner: mike
          name: repo
          branch: main

This will:

  • Try to sync the john/repo fork with mike/repo:main (if on GitHub).
  • Create the files into john/repo, in the branch foo-1.2.3 (assuming ProjectName=foo and Version=1.2.3). 1
  • Open a pull request from john/repo into mike/repo, with the branch main as target. 2

Things that don’t work

  • Opening pull requests to a forked repository (go-github does not have the required fields to do it).
  • Since this can fail for a myriad of reasons, if an error happen, it’ll log it to the release output, but will not fail the pipeline.

  1. In GitHub’s terms, this means head=john:repo:foo-1.2.3 ↩︎

  2. In GitHub’s terms, this means base=mike:repo:main ↩︎

Last updated on