yaml config

You can configure what garnix builds by including a garnix.yaml file at the top-level of your repository. This is useful to prevent "acceptable failures" from causing your check suites to fail. devShells, for instance, are often not buildable as derivations.

A second reason why you may want this is to turn on Mac or ARM-linux builds, see below.

Note: It will often be the case that you have a string in your YAML config that starts with an asterisk (*). Be sure to escape it, or it will be treated as a reference.

Examples

This is the default configuration:

builds:
  exclude: []
  include:
  - '*.x86_64-linux.*'
  - defaultPackage.x86_64-linux
  - devShell.x86_64-linux
  - homeConfigurations.*
  - nixosConfigurations.*

As you can see, the default configuration values only enable x86_64-linux builds. To enable for example Mac builds for all packages and ARM-linux builds for the package foo, you can do:

builds:
 exclude: []
 include:
 - '*.x86_64-linux.*'
 - 'packages.aarch64-darwin.*'
 - 'packages.aarch64-linux.foo'

Branch filtering

You can add a branch key as a sibling to include and exclude like so:

builds:
  include:
    - "packages.*.*"
  exclude: []
  branch: main

The above config will only build packages on the main branch.

Also, builds can be an array instead of a single build config. Each element applies include/exclude rules as normal, but the union of matching packages will be built. For example:

builds:
  - include:
      - "packages.*.*"
    exclude:
      - "packages.*.pkgA"
    branch: main

  - include:
      - "packages.*.*"
    exclude:
      - "packages.*.pkgB"
    branch: production

  - include:
      - "checks.*.*"

With the above config, commits pushed to main will build all packages except pkgA, commits pushed to production will build all packages except pkgB, and all commits regardless of branch will build all checks.

Branch Hosting and Pull-Request Deployments

Garnix can deploy NixOS configurations for you automatically. For more information, see Deployments.

Schema

The schema for the configuration (garnix.yaml) is below:

# or null
# config
builds: # optional
  # default:
  #   exclude: []
  #   include:
  #   - '*.x86_64-linux.*'
  #   - defaultPackage.x86_64-linux
  #   - devShell.x86_64-linux
  #   - homeConfigurations.*
  #   - nixosConfigurations.*
  # Specifies what should be built. Everything in the `include` section, minus everything in the `exclude` section, is built.
  # one of
  [ # builds
    include: # optional
      # default:
      #   - '*.x86_64-linux.*'
      #   - defaultPackage.x86_64-linux
      #   - devShell.x86_64-linux
      #   - homeConfigurations.*
      #   - nixosConfigurations.*
      # What builds to include. This is a list of *attribute matchers*, of the form `x.y.z` or `x.y`. For example, `packages.x86_64-linux.*`, or `*.*`. Two-place matchers only match two-place matchers, and three-place matchers only match three-place matchers. '*' is the wildcard.
      - <string>
    exclude: # optional
      # default: []
      # What builds to exclude. This is a list of *attribute matchers*, of the form `x.y.z` or `x.y`. For example, `packages.x86_64-linux.*`, or `*.*`. Two-place matchers only match two-place matchers, and three-place matchers only match three-place matchers. '*' is the wildcard. This is applied *after* the 'include'. Thus, if something matches both the 'include' and the 'exclude', it will be excluded.
      - <string>
    branch: # optional
      # What (optional) branch this build section is enabled for.
      <string>
  , - # builds
      include: # optional
        # default:
        #   - '*.x86_64-linux.*'
        #   - defaultPackage.x86_64-linux
        #   - devShell.x86_64-linux
        #   - homeConfigurations.*
        #   - nixosConfigurations.*
        # What builds to include. This is a list of *attribute matchers*, of the form `x.y.z` or `x.y`. For example, `packages.x86_64-linux.*`, or `*.*`. Two-place matchers only match two-place matchers, and three-place matchers only match three-place matchers. '*' is the wildcard.
        - <string>
      exclude: # optional
        # default: []
        # What builds to exclude. This is a list of *attribute matchers*, of the form `x.y.z` or `x.y`. For example, `packages.x86_64-linux.*`, or `*.*`. Two-place matchers only match two-place matchers, and three-place matchers only match three-place matchers. '*' is the wildcard. This is applied *after* the 'include'. Thus, if something matches both the 'include' and the 'exclude', it will be excluded.
        - <string>
      branch: # optional
        # What (optional) branch this build section is enabled for.
        <string>
  ]
servers: # optional
  # default: []
  # Specifies what servers to deploy.
  - # servers
    configuration: # required
      # What attribute to deploy (e.g.: 'myServer' for 'nixosConfigurations.myServer')
      <string>
    deployment: # required
      # When to deploy a new server, or redeploy an existing one
      # deployment
      # one of
      [ <object>
        type: # required
          on-pull-request
      , branch: # required
          # What git branch to deploy from
          <string>
        type: # required
          on-branch
      ]
enableGithubOrgAccessTokens: # optional
  # default: false
  # When set to `true`, this sets the nix configuration option
  # `access-token = github.com=$TOKEN` when building flakes on garnix. This
  # makes it possible to use private github repos (from the same user or
  # organization) as flake inputs. Defaults to `false`.
  #
  # The used `$TOKEN` is a github token generated through the garnix github
  # app. This means that the builds of this repo will have access to all
  # private github repos that the garnix github app installation of this
  # user or organization has access to.
  #
  # See also here:
  # https://nixos.org/manual/nix/stable/command-ref/conf-file.html#conf-access-tokens
  <boolean>