{"id":15282184,"url":"https://github.com/rrbutani/use-nix-shell-action","last_synced_at":"2025-04-12T21:27:56.247Z","repository":{"id":65709292,"uuid":"596846571","full_name":"rrbutani/use-nix-shell-action","owner":"rrbutani","description":"`nix develop` for your Github Action steps","archived":false,"fork":false,"pushed_at":"2023-10-08T18:29:59.000Z","size":47,"stargazers_count":14,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-11T16:14:42.033Z","etag":null,"topics":["actions","devshell","github-actions","nix","nix-shell"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rrbutani.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-02-03T03:34:14.000Z","updated_at":"2025-02-05T22:58:21.000Z","dependencies_parsed_at":"2023-02-19T02:45:59.407Z","dependency_job_id":null,"html_url":"https://github.com/rrbutani/use-nix-shell-action","commit_stats":{"total_commits":49,"total_committers":1,"mean_commits":49.0,"dds":0.0,"last_synced_commit":"59a52b2b9bbfe3cc0e7deb8f9059abe37a439edf"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrbutani%2Fuse-nix-shell-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrbutani%2Fuse-nix-shell-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrbutani%2Fuse-nix-shell-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrbutani%2Fuse-nix-shell-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rrbutani","download_url":"https://codeload.github.com/rrbutani/use-nix-shell-action/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248633839,"owners_count":21136922,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actions","devshell","github-actions","nix","nix-shell"],"created_at":"2024-09-30T14:20:18.400Z","updated_at":"2025-04-12T21:27:56.226Z","avatar_url":"https://github.com/rrbutani.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `use-nix-shell-action`\n\nThis action applies the environment of a nix shell to your GitHub Actions job.\n\nThis action works like [`workflow/nix-shell-action`](https://github.com/workflow/nix-shell-action) with one crucial difference: rather than only \"applying\" the provided shell to a script passed to the action's step, the shell is \"applied\" to the rest of the job.\n\nThis allows you to use `nix` to provide binaries that other GitHub Actions require and also allows you to run your action's steps in a nix shell without needing to wrap every step in a `nix-shell` action or bundle all your commands under one step.\n\n## Example\n\n\u003e **Note**\n\u003e If `nix` isn't found, this action *will* handle installing `nix` for you using [`cachix/install-nix-action`](https://github.com/cachix/install-nix-action).\n\u003e\n\u003e However it's recommended that you run this action yourself.\n\n```yaml\nname: \"Test\"\non: [push]\njobs:\n  example:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: cachix/install-nix-action@v18\n        with:\n          nix_path: nixpkgs=channel:nixos-unstable\n      - name: Print env, before\n        run: env\n      # To make the environment in your flake's devShell available to future\n      # steps:\n      - uses: rrbutani/use-nix-shell-action@v1\n        with:\n          devShell: .#default # this is the default\n      - name: Print env, after\n        run: env\n      - name: Run hello\n        run: hello\n      - name: Print env var\n        run: echo $SOME_ENV_VAR\n\n      # Alternatively you can also run a script directly in the shell; choosing\n      # whether to preserve the environment outside the shell or not:\n      - uses: rrbutani/use-nix-shell-action@v1\n        with:\n          devShell: .#\n          exportEnv: false\n          interpreter: python3\n          clearEnvForScript: true # `SOME_ENV_VAR` will not be visible; nor will\n                                  # `hello` be on `$PATH`\n          script: |\n            import os\n            print(os.sys.version)\n            print(os.environ['PATH'])\n```\n\n## Options (`with: ...`)\n\n### Source\n\nThese options describe the shell that `use-nix-shell-action` should use.\n\n\u003e **Note**\n\u003e You can only specify **one** of these options.\n\n  - `packages`: Comma-separated list of [packages](https://search.nixos.org/packages?) to install in your shell.\n    + i.e. `packages: bash,python3,python3Packages.numpy`\n      * spaces will be stripped so `bash, python3, python3Packages.numpy` works too\n    + these packages are sourced from `\u003cnixpkgs\u003e`; see [`cachix/install-nix-action`](https://github.com/cachix/install-nix-action) for easy ways to influence this channel or consider using flakes\n  - `flakes`: Comma-separated list of [flake references](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#flake-references) to install in your shell.\n    + i.e. `nixpkgs#hello, github:edolstra/nix-serve, .#myPackage`\n  - `devShell`: Flake reference to a [devShell output](https://nixos.wiki/wiki/Flakes). \u003ckbd\u003e(default)\u003c/kbd\u003e\n    + i.e. `.#` or `github:NixOS/nix` or `some/path#someShell` or `.#devShells.x86_64-linux.someSpecialShell`\n  - `file`: Path to a [nix file producing a shell](https://nixos.wiki/wiki/Development_environment_with_nix-shell).\n    + i.e. `shell.nix`\n\n### Export Options\n\n  - `exportEnv`: Boolean specifying whether `use-nix-shell-action` should export the shell given to your environment.\n    + defaults to \u003ckbd\u003etrue\u003c/kbd\u003e\n  - `preserveDefaultPath`: Boolean controlling whether the shell's environment *overrides* `$PATH` in the job (`false`) or appends to it (`true`).\n    \u003e **Warning**\n    \u003e Be careful with this option; if your shell doesn't include `bash`, `node`, `docker`, etc. those tools will not be on the `PATH` after this step; this can break other actions.\n    + note: things added to `$GITHUB_PATH` (i.e. by other actions) will be preserved regardless\n    + defaults to \u003ckbd\u003etrue\u003c/kbd\u003e\n\n### Script Options\n\n`use-nix-shell-action` can also, _optionally_, run a script of your choosing under your nix shell. This is the functionality provided by [`workflow/nix-shell-action`](https://github.com/workflow/nix-shell-action) but with some small mechanical differences; this action provides ways to run scripts under flake dev shells, for example.\n\n  - `script`: A script to run under the [nix shell specified](#source).\n    + note: this runs _after_ the environment is exported\n      * if you wish to have your script affect the environment you'll need to update `$GITHUB_ENV` yourself\n  - `interpreter`: The interpreter under which to run `script`.\n    + this should be present in your shell's `$PATH`\n    + defaults to \u003ckbd\u003ebash\u003c/kbd\u003e\n  - `clearEnvForScript`: Boolean specifying whether to preserve existing env vars when running the provided script.\n    + note: this does not influence the environment that's exported and cannot be used to provide a \"pure\" shell for future steps in your action\n    + defaults to \u003ckbd\u003etrue\u003c/kbd\u003e\n\n### Other options\n\n  - `extraNixOptions`: Escape hatch that you can use to specify extra flags to be passed to the command producing the shell.\n    + for example `--impure` or extra [`--option`s](https://nixos.org/manual/nix/stable/command-ref/conf-file.html?highlight=nix.conf)\n    + see the options for [`nix print-dev-env`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-print-dev-env.html#options) and [`nix shell`](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-shell.html)\n\n## FAQ\n\n#### Does this work on self-hosted runners?\n\nYes!\n\n#### Are bash functions set in the shell preserved?\n\nNope, sorry. Just regular (non-array) env vars. Anything that `env` prints out.\n\nNote that this also does not preserve the `readonly` property of env vars.\n\n#### How does this work?\n\nEssentially just constructs a nix shell, [one way](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-print-dev-env.html) or [another](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-shell.html), and then dumps the contents of `env` into [`$GITHUB_ENV`](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-environment-variable).\n\nWe reuse [this logic from `nix-direnv`](https://github.com/nix-community/nix-direnv/blob/75c74a090bf37f34cd92eeab7f22f17dc0fcd48f/direnvrc#L83-L126).\n\n#### When should I use `script` instead of just exporting the env and running the script in a separate step?\n\ni.e. this:\n```yaml\n- uses: rrbutani/use-nix-shell-action@v1\n  with:\n    script: ./foo.sh\n```\n\nverus this:\n```yaml\n- uses: rrbutani/use-nix-shell-action@v1\n- run: ./foo.sh\n```\n\nThe key difference here is \"purity\" (i.e. of the environment that `foo.sh` is run in). The former is run in the GitHub Actions environment (with the nix shell's environment layered on) while the latter is run with `nix develop --ignore-environment` (unless `clearEnvForScript` is set to `false`).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frrbutani%2Fuse-nix-shell-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frrbutani%2Fuse-nix-shell-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frrbutani%2Fuse-nix-shell-action/lists"}