Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cachix/devenv/llms.txt

Use this file to discover all available pages before exploring further.

GitHub Actions is the continuous integration (CI) platform built into GitHub. devenv lets you reuse your existing development environment in GitHub Actions workflows to run checks, builds, tests, and more — giving you the same reproducible environment in CI that you have locally. This guide walks through the steps to set up devenv in a GitHub Actions workflow and shows how to run commands in the devenv shell. The following sample devenv.nix is used throughout the examples: 
{ pkgs, ... }:

{
  packages = [ pkgs.hello ];

  scripts.say-bye.exec = ''
    echo bye
  '';
}
The hello package prints “Hello, world!” and the custom say-bye script prints “bye”.

​
Prerequisites

Before running devenv commands, prepare the job environment with the following steps: 
steps:
- uses: actions/checkout@v5
- uses: cachix/install-nix-action@v31
- uses: cachix/cachix-action@v16
  with:
    name: devenv
- name: Install devenv.sh
  run: nix profile add nixpkgs#devenv
This snippet:
  1. Checks out the repository.
  2. Installs and sets up Nix.
  3. Configures Nix to use the devenv Cachix binary cache to speed up installation.
  4. Installs devenv.
If you’re using a self-hosted runner, you can pre-install both Nix and devenv and skip the associated setup steps.

​
Running devenv in CI

​
devenv test

devenv provides a convenient built-in devenv test command. It builds the shell and runs any defined git hooks against your repository — a quick way to verify your development environment works and lint your code at the same time. 
- name: Build the devenv shell and run any git hooks
  run: devenv test

​
Run a single command

Single commands can be passed directly to devenv shell: 
- name: Run a single command in the devenv shell
  run: devenv shell hello

Building shell ...
Hello, world!

​
Run multiple commands

Each run step in a job launches a separate shell, so you can’t run devenv shell in one step and have subsequent steps inherit that environment. Instead, use the shell option to replace the default shell for a step with the devenv shell: 
- name: Run a multi-line command in the devenv shell
  shell: devenv shell bash -- -e {0}
  run: |
    hello
    say-bye

Building shell ...
Hello, world!
bye
When you have many run steps, set devenv as the default shell for the entire job using defaults.run: 
defaults:
  run:
    shell: devenv shell bash -- -e {0}
When setting the default shell for a job, the “Install devenv.sh” step must explicitly opt out, otherwise it will try to use the devenv shell before devenv is installed:
- name: Install devenv.sh
  shell: bash
  run: nix profile add nixpkgs#devenv

​
Complete example

The full workflow combining all of the above: 
name: "Test"

on:
  pull_request:
  push:

jobs:
  tests:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest]
    runs-on: ${{ matrix.os }}

    steps:
    - uses: actions/checkout@v5
    - uses: cachix/install-nix-action@v31
    - uses: cachix/cachix-action@v16
      with:
        name: devenv
    - name: Install devenv.sh
      run: nix profile add nixpkgs#devenv

    - name: Build the devenv shell and run any pre-commit hooks
      run: devenv test

    - name: Run a single command in the devenv shell
      run: devenv shell hello

    - name: Run a multi-line command in the devenv shell
      shell: devenv shell bash -- -e {0}
      run: |
        hello
        say-bye

​
Using with Nix Flakes

If you’re using devenv with Nix Flakes and nix develop to set the shell for a step, wrap the command in bash to set the necessary environment variables for devenv to work inside the restrictive flake shell: 
- name: Run command in flake shell
  shell: bash -c "nix develop --impure -c bash -- {0}"
  run: devenv test

Build docs developers (and LLMs) love

Get started for freeTalk to us