Garnix

https://garnix.io/docs
Admin
This is the documentation for Garnix, a platform that facilitated setting up GitHub repositories...
Tokens:10,613
Snippets:154
Trust Score:8.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Nix via shell script

Source: https://garnix.io/docs/getting-started/installing-nix

Executes the official Nix installation script with daemon mode enabled.

```bash
sh <(curl --proto '=https' --tlsv1.2 -L https://nixos.org/nix/install) --daemon
```

--------------------------------

### Custom Architecture Build Configuration

Source: https://garnix.io/docs/ci/yaml_config

Example of enabling Mac and ARM-linux builds by extending the include list.

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

--------------------------------

### Demonstrate FOD behavior with a flake

Source: https://garnix.io/docs/ci/fod-checks

A flake example showing two derivations with identical output hashes but different build scripts.

```nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.05";
  };
  outputs = { self, nixpkgs }:
    let
      system = "x86_64-linux";
      pkgs = import nixpkgs { inherit system; };
    in
    {
      packages.${system} = {
        valid = derivation {
          name = "source";
          outputHash = "sha256-nhfLFd11u71du5hO2mdIY8OxCrcmE8+KOaAMPhGoSSo=";
          outputHashAlgo = "sha256";
          builder = "${pkgs.bash}/bin/bash";
          system = "x86_64-linux";
          args = [
            "-c"
            ''
              ${pkgs.curl}/bin/curl 'http://garnix.io' > $out
            ''
          ];
        };
        lying = derivation {
          name = "source";
          # same hash as above
          outputHash = "sha256-nhfLFd11u71du5hO2mdIY8OxCrcmE8+KOaAMPhGoSSo=";
          outputHashAlgo = "sha256";
          builder = "${pkgs.bash}/bin/bash";
          system = "x86_64-linux";
          args = [
            "-c"
            ''
              ${pkgs.curl}/bin/curl 'http://some-other-site.io' > $out
            ''
          ];
        };
      };
    };
}
```

--------------------------------

### Implement Incremental Builds in a Flake

Source: https://garnix.io/docs/ci/incremental-builds

Example of wrapping flake outputs with withCaches and utilizing the cache argument to persist build state across runs.

```nix
{
    inputs.garnix-incrementalize.url = "github:garnix-io/incrementalize";
    outputs = { nixpkgs, garnix-incrementalize, ...} :
    garnix-incrementalize.lib.withCaches {
       packages.x86_64.default = cache: pkgs.mkDerivation {
         name = "inc"
         outputs = [ "out" "intermediates" ];
         buildPhase = ''

           mkdir $intermediates
           cat ${cache}/run-logs > "$intermediates"/run-logs
           echo "I ran again" > "$intermediates"/run-logs

           echo normal-build-stuff > $out
         '';
       } ;
    };
}
```

--------------------------------

### GET /build/{build_id}/logs/raw

Source: https://garnix.io/docs/api

Retrieves the raw logs for a specific build.

```APIDOC
## GET /build/{build_id}/logs/raw

### Description
Retrieves the raw log output for a given build ID.

### Method
GET

### Endpoint
https://api.garnix.io/build/{build_id}/logs/raw

### Parameters
#### Path Parameters
- **build_id** (string) - Required - The ID of the build.

### Request Example
curl -sH "Authorization: Bearer $JWT" https://api.garnix.io/build/$BUILD_ID/logs/raw
```

--------------------------------

### GET /whoami

Source: https://garnix.io/docs/api

Verifies the current authenticated user identity.

```APIDOC
## GET /whoami

### Description
Returns information about the currently authenticated user.

### Method
GET

### Endpoint
https://api.garnix.io/whoami

### Request Example
curl -H "Authorization: Bearer YOUR_JWT" https://api.garnix.io/whoami
```

--------------------------------

### Embed Garnix Badge in Documentation

Source: https://garnix.io/docs/ci/badges

Examples of how to embed the Garnix build status badge in different documentation formats.

```markdown
[![built with garnix](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fgarnix.io%2Fapi%2Fbadges%2Fgarnix-io%2Fhello-garnix)](https://garnix.io/repo/garnix-io/hello-garnix)
```

```html
<a href="https://garnix.io/repo/garnix-io/hello-garnix"><img alt="built with garnix" src="https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fgarnix.io%2Fapi%2Fbadges%2Fgarnix-io%2Fhello-garnix"></a>
```

```org
#+ATTR_HTML: :alt built with garnix
[[https://garnix.io/repo/garnix-io/hello-garnix][https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fgarnix.io%2Fapi%2Fbadges%2Fgarnix-io%2Fhello-garnix]]
```

```rst
.. image:: https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fgarnix.io%2Fapi%2Fbadges%2Fgarnix-io%2Fhello-garnix
   :alt: built with garnix
   :target :https://garnix.io/repo/garnix-io/hello-garnix
```

```asciidoc
image:https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fgarnix.io%2Fapi%2Fbadges%2Fgarnix-io%2Fhello-garnix[alt=built with garnix,link=https://garnix.io/repo/garnix-io/hello-garnix]
```

--------------------------------

### GET /build/{build_id}

Source: https://garnix.io/docs/api

Retrieves the status of a specific build.

```APIDOC
## GET /build/{build_id}

### Description
Retrieves the current status of a specific build.

### Method
GET

### Endpoint
https://api.garnix.io/build/{build_id}

### Parameters
#### Path Parameters
- **build_id** (string) - Required - The ID of the build.

### Request Example
curl -sH "Authorization: Bearer $JWT" https://api.garnix.io/build/$BUILD_ID
```

--------------------------------

### GET /commits/{commit}

Source: https://garnix.io/docs/api

Retrieves build information for a specific commit.

```APIDOC
## GET /commits/{commit}

### Description
Retrieves the build details associated with a specific commit hash.

### Method
GET

### Endpoint
https://api.garnix.io/commits/{commit}

### Parameters
#### Path Parameters
- **commit** (string) - Required - The commit hash to retrieve builds for.

### Request Example
curl -sH "Authorization: Bearer $JWT" https://api.garnix.io/commits/$COMMIT
```

--------------------------------

### Run project server in a VM

Source: https://garnix.io/docs/modules/introduction

Commands to build the NixOS configuration and execute the resulting virtual machine.

```bash
nix build .#nixosConfigurations.default.config.system.build.toplevel
./result/bin/run-nixos-vm
```

--------------------------------

### Enable Nix flakes

Source: https://garnix.io/docs/getting-started/installing-nix

Adds the necessary configuration lines to enable nix-command and flakes.

```text
experimental-features = nix-command flakes
```

--------------------------------

### Define a basic flake.nix file

Source: https://garnix.io/docs/getting-started/flake

A minimal flake configuration defining a package for x86_64-linux using nixpkgs.

```nix
{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs";
  };
  outputs = { self, nixpkgs }: {
    packages.x86_64-linux =
      let pkgs = import nixpkgs { system = "x86_64-linux"; };
      in {
        myExamplePackage = pkgs.runCommand "example" { } ''
          echo hello from nix!
          echo "build output" > $out
        '';
      };
  };
}
```

--------------------------------

### Configure branch deployment in garnix.yaml

Source: https://garnix.io/docs/hosting/branch

Define the NixOS configuration and target branch for deployment.

```yaml
servers:
  - configuration: myMachine
    deployment:
      type: on-branch
      branch: prod
```

--------------------------------

### Enable garnix module in flake.nix

Source: https://garnix.io/docs/hosting/branch

Import the garnix-lib and enable the server module within your nixosConfigurations.

```nix
{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs";
    garnix-lib = {
      url = "github:garnix-io/garnix-lib";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
  outputs = { nixpkgs, garnix-lib, ... }: {
    nixosConfigurations =
      {
        my-server = nixpkgs.lib.nixosSystem {
          system = "x86_64-linux";
          modules = [
            garnix-lib.nixosModules.garnix
            {
              garnix.server.enable = true;
              ... other nixos configuration
            }
          ];
        };
      };
  };
}
```

--------------------------------

### Reference a server URL using garnix-lib

Source: https://garnix.io/docs/hosting/multiple-servers

Use the lib.getHashSubdomain function to construct a URL pointing to another server's configuration hash.

```nix
{
  ...
  inputs.garnix-lib.url = "github:garnix-io/garnix-lib";

  outputs = { self, nixpkgs, garnix-lib, ... }: {
    nixosConfigurations.machine1 = ...;
    nixosConfigurations.machine2 = nixpkgs.lib.nixosSystem {
      ...
      modules = [{
        ...
        myservice.otherServiceURL =
          "http://" +
          garnix-lib.lib.getHashSubdomain self.nixosConfigurations.machine1 +
          "/somepath";
      }]

    }
  }
}
```

--------------------------------

### Create a JWT using Basic Auth

Source: https://garnix.io/docs/api

Exchange a GitHub username and access token for a short-lived JWT.

```bash
curl -XPOST --basic --user "YOUR_GITHUB_USERNAME:YOUR_ACCESS_TOKEN" https://api.garnix.io/auth/jwt
```

--------------------------------

### Enable Repository Contents in Action

Source: https://garnix.io/docs/actions

Set withRepoContents to true in your garnix.yaml to provide the action with access to the full repository.

```yaml
actions:
  - on: push
    run: myApp
    withRepoContents: true
```

--------------------------------

### Multi-Rule Build Configuration

Source: https://garnix.io/docs/ci/yaml_config

Uses an array of build configurations to define different rules for different branches and build types.

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

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

  - include:
      - "checks.*.*"
```

--------------------------------

### Build a flake output locally

Source: https://garnix.io/docs/getting-started/flake

Command to build a specific package defined in the flake outputs.

```bash
nix build -L .#myExamplePackage
```

--------------------------------

### Build derivation

Source: https://garnix.io/docs/ci/steps

Command to build a specific derivation path with build logs enabled.

```bash
nix build '<drvpath>^*' --log-lines 0 --print-build-logs
```

--------------------------------

### Build derivation commands

Source: https://garnix.io/docs/ci/fod-checks

Commands to build the valid and lying derivations defined in the flake.

```bash
nix build -L .#valid
```

```bash
nix build -L .#lying
```

--------------------------------

### Configure netrc for Private Cache Authentication

Source: https://garnix.io/docs/ci/caching

Create a netrc file to provide credentials for accessing private caches on cache.garnix.io.

```text
machine cache.garnix.io
  login ${YOUR_GITHUB_USER}
  password ${YOUR_GARNIX_ACCESS_TOKEN}
```

--------------------------------

### Update nix.conf for Private Cache Access

Source: https://garnix.io/docs/ci/caching

Add the netrc file path and adjust the narinfo-cache-positive-ttl to support presigned URLs.

```text
netrc-file = /etc/nix/netrc
narinfo-cache-positive-ttl = 3600
```

--------------------------------

### Retrieve Build Status and Logs

Source: https://garnix.io/docs/api

Fetch build IDs for a specific commit and subsequently retrieve raw logs and status information.

```bash
JWT="YOUR_JWT"

# This is an example commit from a public repo.
# With a valid JWT this should work for all
# public repos and for private repos that you
# have access to.
COMMIT="fbd9865a68c8f7f4bd9d4e136f27be04098fe1ee"

# Select the first build of the commit
BUILD_ID=$(curl -sH "Authorization: Bearer $JWT" https://api.garnix.io/commits/$COMMIT | jq -r '.builds.[0] | .id')

echo "Logs for build $BUILD_ID:"
curl -sH "Authorization: Bearer $JWT" https://api.garnix.io/build/$BUILD_ID/logs/raw

echo "Status for build $BUILD_ID:"
curl -sH "Authorization: Bearer $JWT" https://api.garnix.io/build/$BUILD_ID | jq -r .status
```

--------------------------------

### Evaluate Nix attributes

Source: https://garnix.io/docs/ci/steps

Command to list available attributes for a specific type in the top-level directory.

```bash
nix eval .#<type>.x86_64-linux --apply builtins.attrNames --json
```

--------------------------------

### Define a private dependency in Nix inputs

Source: https://garnix.io/docs/ci/private_inputs

Use the github: prefix to specify a private repository URL within your Nix flake inputs.

```nix
{
  inputs.privateDep.url = "github:garnix-io/private";
  ...
}
```

--------------------------------

### Add agenix Flake Input

Source: https://garnix.io/docs/hosting/secrets

Include the agenix repository in your flake inputs.

```nix
  inputs.agenix.url = "github:ryantm/agenix";
```

--------------------------------

### Configure Pull-request Deployment

Source: https://garnix.io/docs/hosting/pr

Add this configuration to your server settings to enable automatic deployments for pull requests.

```yaml
servers:
  - configuration: myMachine
    deployment:
      type: on-pull-request
```

--------------------------------

### Define secrets.nix Configuration

Source: https://garnix.io/docs/hosting/secrets

Configure access permissions for an encrypted secret using the repository key and a personal SSH key.

```nix
let repoKey = <gotten from curl command above>;
    myKey = <gotten from ~/.ssh/id_ed25519.pub or the like>;
in
{
  "sampleSecret.age".publicKeys = [ repoKey myKey ];
}
```

--------------------------------

### Retrieve derivation path

Source: https://garnix.io/docs/ci/steps

Command to obtain the raw derivation path for a given attribute.

```bash
nix eval <attribute> --apply 'pkg: pkg.drvPath' --raw
```

--------------------------------

### Default Garnix Configuration

Source: https://garnix.io/docs/ci/yaml_config

The default configuration enables x86_64-linux builds for various package and configuration types.

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

--------------------------------

### Define a Garnix App in Flake

Source: https://garnix.io/docs/actions

Define an x86_64-linux app within your flake outputs to be used as a target for actions.

```nix
{
  ...
  outputs = inputs : {
    apps.x86_64-linux.myApp = ...;
  };
}
```

--------------------------------

### Retrieve Action Public Key

Source: https://garnix.io/docs/actions

Use curl to fetch the public key for encrypting secrets used by a specific action.

```bash
curl https://garnix.io/api/keys/<repo_owner>/<repo_name>/actions/<action_name/key.public
```

--------------------------------

### Encrypt Secret with agenix

Source: https://garnix.io/docs/hosting/secrets

Open the secret file for editing using the agenix CLI.

```bash
agenix -e sampleSecret.age
```

--------------------------------

### Configure Incremental Builds in garnix.yaml

Source: https://garnix.io/docs/ci/incremental-builds

Specify branches to exclude from incremental build processing.

```yaml
incrementalizeBuilds:
  excludeBranches:
    - main
```

--------------------------------

### Configure Garnix Actions

Source: https://garnix.io/docs/actions

Add an actions section to your garnix.yaml file to trigger apps on specific events.

```yaml
actions:
  - on: push
    run: myApp
```

--------------------------------

### Retrieve Public Key

Source: https://garnix.io/docs/hosting/secrets

Use curl to fetch the public age key for a specific repository.

```bash
curl https://garnix.io/api/keys/<repo_owner>/<repo_name>/repo-key.public
```

--------------------------------

### Make Authenticated API Requests

Source: https://garnix.io/docs/api

Include the JWT in the Authorization header as a bearer token for API calls.

```bash
curl -H "Authorization: Bearer YOUR_JWT" https://api.garnix.io/whoami
```

--------------------------------

### Configure agenix Secret Path

Source: https://garnix.io/docs/hosting/secrets

Define the secret file and identity path in your NixOS configuration.

```nix
  age.secrets.sampleSecret = {
    file = ./sampleSecret.age;
  };
  age.identityPaths = [
    "/var/garnix/keys/repo-key"
  ];
```

--------------------------------

### Enable FOD checks in configuration

Source: https://garnix.io/docs/ci/fod-checks

Configuration snippet to enable FOD checks in the garnix yaml file.

```yaml
fodChecks: true
```

--------------------------------

### Garnix Configuration Schema

Source: https://garnix.io/docs/ci/yaml_config

The full schema definition for garnix.yaml, covering builds, incrementalization, server deployments, and actions.

```yaml
# or null
# config
builds: # optional
  # default:
  #   exclude: []
  #   include:
  #   - '*.x86_64-linux.*'
  #   - defaultPackage.x86_64-linux
  #   - devShell.x86_64-linux
  #   - homeConfigurations.*
  #   - darwinConfigurations.*
  #   - 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.*
      #   - darwinConfigurations.*
      #   - 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.*
        #   - darwinConfigurations.*
        #   - 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>
  ]
incrementalizeBuilds: # optional
  # default: false
  # Whether to override the `garnix-incrementalize` flake input to point to an parent built commit. This allows incremental builds. See our https://garnix.io/docs for more information.
  # one of
  [ <boolean>
  , # ExcludesBranches
    excludeBranches: # required
      # What branches *not* to incrementalize
      - <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>
        machine: # optional
          # default: i2x4
          # What server tier to deploy
          <string>
        isPrimary: # optional
          # default: false
          # If this deploy should also be reachable at «repo-name».«org-name».garnix.me
          <boolean>
        type: # required
          on-branch
      ]
actions: # optional
  # default: []
  # Specifies which actions to run.
  - # actions
    run: # required
      # Name of the nix app to run as an action.
      <string>
    on: # required
      # Event that triggers this action
      push
    sandboxType: # optional
      # default: fast-startup
      # What sandbox type. If you want to use the 'SharedResources' type, get in touch with us.
      # one of
      [ fast-startup
      , shared-resources
      ]
    withRepoContents: # optional
      # default: false
      # Whether the action should run with access to the entire repo. If false (default), only the closure of the action is available.
      <boolean>
modules: # optional
  # default: publish: false
  # Specifies which actions to run.
  # modules
  publish: # optional
    # default: false
    # Whether to publish modules from this repository.
    <boolean>
fodChecks: # optional
  # default: false
```

--------------------------------

### Branch-Filtered Build Configuration

Source: https://garnix.io/docs/ci/yaml_config

Restricts builds to a specific branch by adding a branch key.

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

--------------------------------

### Retrieve Garnix Badge URL

Source: https://garnix.io/docs/ci/badges

The raw URL for the Garnix build status badge endpoint.

```text
https://img.shields.io/endpoint.svg?url=https%3A%2F%2Fgarnix.io%2Fapi%2Fbadges%2Fgarnix-io%2Fhello-garnix
```

--------------------------------

### GitHub Actions check_suite workflow configuration

Source: https://garnix.io/docs/ci/gh-actions

Configure a workflow to trigger on the completion of a check suite. The workflow file must be merged into the default branch to function.

```yaml
  on:
    check_suite:
      types: [completed]

  jobs:
    foo:
      runs-on: ubuntu-latest
      steps:
        - run: ...
```

--------------------------------

### Configure ALIAS record for apex domains

Source: https://garnix.io/docs/hosting/custom-domain

Use an ALIAS record for apex domains when using raw domains. Note that this requires manual TLS certificate management and may result in brief downtime during deployments.

```text
mydomain.com      ALIAS       myServer.branch.repo.org.raw.garnix.me
```

--------------------------------

### Configure CNAME record for subdomains

Source: https://garnix.io/docs/hosting/custom-domain

Use a CNAME record to point a subdomain to your Garnix deployment. Garnix automatically handles TLS certificate generation for these domains.

```text
www.mydomain.com      CNAME       myServer.branch.repo.org.garnix.me
```

--------------------------------

### POST /auth/jwt

Source: https://garnix.io/docs/api

Exchanges a GitHub username and access token for a short-lived JWT.

```APIDOC
## POST /auth/jwt

### Description
Creates a short-lived JWT for API authentication using Basic Auth.

### Method
POST

### Endpoint
https://api.garnix.io/auth/jwt

### Request Example
curl -XPOST --basic --user "YOUR_GITHUB_USERNAME:YOUR_ACCESS_TOKEN" https://api.garnix.io/auth/jwt
```
Tokens:
Raw