diff --git a/source/tutorials/continuous-integration-github-actions.md b/source/tutorials/continuous-integration-github-actions.md new file mode 100644 index 0000000..d430bf9 --- /dev/null +++ b/source/tutorials/continuous-integration-github-actions.md @@ -0,0 +1,76 @@ +--- +html_meta: + "description lang=en": "Continuous Integration with GitHub Actions and Cachix" + "keywords": "CI, Continuous Integration, GitHub Actions, Cachix, Binary Cache, Nix" +--- + +(github-actions)= + +# Continuous Integration with GitHub Actions + +In this tutorial, we'll show you **a few short steps** to get started using [GitHub Actions](https://github.com/features/actions) as your continuous integration (CI) workflow for commits and pull requests. + +## Caching builds using Cachix + +One benefit of Nix is that **CI can build and cache developer environments for every project** on every branch using binary caches. + +An important aspect of CI is the feedback loop of, **how many minutes does the build take to finish?** + +Using [Cachix](https://cachix.org/) you'll never have to waste time building a derivation twice, and you'll share built derivations with all your developers. + +After each job, just-built derivations are pushed to your binary cache. + +Before each job, derivations to be built are first substituted (if they exist) from your binary cache. + +### 1. Creating your first binary cache + +It's recommended to have different binary caches per team, depending who will have write/read access to it. + +Fill out the form on the [create binary cache](https://app.cachix.org/cache) page. + +On your freshly created binary cache, follow the **Push binaries** tab instructions. + +### 2. Setting up secrets + +On your GitHub repository or organization (for use across all repositories): + +1. Click on `Settings`. +2. Click on `Secrets`. +3. Add your previously generated secrets (`CACHIX_SIGNING_KEY` and/or `CACHIX_AUTH_TOKEN`). + +## Setting up GitHub Actions + +Create `.github/workflows/test.yml` with: + +```yaml +name: "Test" +on: + pull_request: + push: +jobs: + tests: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2.4.0 + - uses: cachix/install-nix-action@v16 + with: + nix_path: nixpkgs=channel:nixos-unstable + - uses: cachix/cachix-action@v10 + with: + name: mycache + # If you chose signing key for write access + signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}' + # If you chose API tokens for write access OR if you have a private cache + authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}' + - run: nix-build + - run: nix-shell --run "echo OK" +``` + +Once you commit and push to your GitHub repository, +you should see status checks appearing on commits and PRs. + +## Next steps + +- See [GitHub Actions workflow syntax](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions) +- To quickly setup a Nix project read through + [Getting started Nix template](https://github.com/nix-dot-dev/getting-started-nix-template). diff --git a/source/tutorials/continuous-integration-github-actions.rst b/source/tutorials/continuous-integration-github-actions.rst deleted file mode 100644 index 3917de5..0000000 --- a/source/tutorials/continuous-integration-github-actions.rst +++ /dev/null @@ -1,85 +0,0 @@ -.. _github-actions: - -.. meta:: - :description: Continuous Integration with GitHub Actions and Cachix - :keywords: CI, Continuous Integration, GitHub Actions, Cachix, Binary Cache, Nix - -Continuous Integration with GitHub Actions -========================================== - -In this tutorial, we'll show you **a few short steps** to get started using `GitHub Actions `_ as your continuous integration (CI) workflow for commits and pull requests. - -Caching builds using Cachix ---------------------------- - -One benefit of Nix is that **CI can build and cache developer environments for every project** on every branch using binary caches. - -An important aspect of CI is the feedback loop of, **how many minutes does the build take to finish?** - -Using `Cachix `_ you'll never have to waste time building a derivation twice, and you'll share built derivations with all your developers. - -After each job, just-built derivations are pushed to your binary cache. - -Before each job, derivations to be built are first substituted (if they exist) from your binary cache. - - -1. Creating your first binary cache -*********************************** - -It's recommended to have different binary caches per team, depending who will have write/read access to it. - -Fill out the form on the `create binary cache `_ page. - -On your freshly created binary cache, follow the **Push binaries** tab instructions. - - -2. Setting up secrets -********************* - -On your GitHub repository or organization (for use across all repositories): - -1. Click on ``Settings``. -2. Click on ``Secrets``. -3. Add your previously generated secrets (``CACHIX_SIGNING_KEY`` and/or ``CACHIX_AUTH_TOKEN``). - - -Setting up GitHub Actions -------------------------- - -Create ``.github/workflows/test.yml`` with: - -.. code:: yaml - - name: "Test" - on: - pull_request: - push: - jobs: - tests: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2.4.0 - - uses: cachix/install-nix-action@v16 - with: - nix_path: nixpkgs=channel:nixos-unstable - - uses: cachix/cachix-action@v10 - with: - name: mycache - # If you chose signing key for write access - signingKey: '${{ secrets.CACHIX_SIGNING_KEY }}' - # If you chose API tokens for write access OR if you have a private cache - authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}' - - run: nix-build - - run: nix-shell --run "echo OK" - -Once you commit and push to your GitHub repository, -you should see status checks appearing on commits and PRs. - - -Next steps ----------- - -- See `GitHub Actions workflow syntax `_ - -- To quickly setup a Nix project read through - `Getting started Nix template `_. diff --git a/source/tutorials/contributing.md b/source/tutorials/contributing.md new file mode 100644 index 0000000..a071e6d --- /dev/null +++ b/source/tutorials/contributing.md @@ -0,0 +1,67 @@ +# How to Contribute + +This guide explains how you can contribute to Nix, Nix packages or +NixOS. + +## Report an issue + +We can only fix issues that we know of, so please report any issue you +encounter. + +Issues with the **package manager Nix** (including it's documentation) +are reported at . + +Issues with **specific packages or NixOS** (including it's modules and +documentation) are reported at . + +Make sure that there is not already an open issue for your problem. +Please follow the issue template and fill in all requested information +as they help us solve the problem. + +You need a [GitHub] account for that. + +## Contribute to Nix + +The package manager Nix is mostly written in C++. If you are a developer +and want to contribute to it's development, you can find information on +[how to setup a development environment] in the manual. + +You can find inspiration for things to improve in the [reported +issues][reported issues]. + +Feel free to [join our community] to get in +contact with other developers. + +## Contribute to Nix packages + +Packaging for Nix is simple when you have understood the basic concept. + +[The manual] explains step-by-step how to add new packages to the Nix +package collection. There are also [programming language specific +instructions][programming language specific instructions]. + +## Contribute to NixOS + +It’s pretty easy to contribute to NixOS compared to other linux +distributions. All the code is on GitHub in the repository [nixpkgs]. +Everyone can propose an improvement and most of them get merged after a +review of the maintainers. You will get feedback in the pull request. + +See the [NixOS manual] to get started and find all the details. + +You can find inspiration for things to improve in the [reported +issues](https://github.com/NixOS/nixpkgs/issues). There are also +[issues tagged with good-first-bug] that are a good start for new +contributors. + +Feel free to [join our community] of developers! + +[github]: https://github.com/ +[how to setup a development environment]: https://nixos.org/manual/nix/stable/contributing/hacking.html +[issues tagged with good-first-bug]: https://github.com/NixOS/nixpkgs/labels/3.skill%3A%20good-first-bug +[join our community]: https://github.com/NixOS/nixpkgs#community +[nixos manual]: https://nixos.org/manual/nixos/stable/index.html#ch-development +[nixpkgs]: https://github.com/NixOS/nixpkgs +[programming language specific instructions]: https://nixos.org/manual/nixpkgs/stable/#chap-language-support +[reported issues]: https://github.com/NixOS/nix/issues +[the manual]: https://nixos.org/manual/nix/stable/quick-start.html diff --git a/source/tutorials/contributing.rst b/source/tutorials/contributing.rst deleted file mode 100644 index 7dc2f38..0000000 --- a/source/tutorials/contributing.rst +++ /dev/null @@ -1,72 +0,0 @@ -How to Contribute -================= - -This guide explains how you can contribute to Nix, Nix packages or -NixOS. - -Report an issue ---------------- - -We can only fix issues that we know of, so please report any issue you -encounter. - -Issues with the **package manager Nix** (including it's documentation) -are reported at https://github.com/NixOS/nix/issues. - -Issues with **specific packages or NixOS** (including it's modules and -documentation) are reported at https://github.com/NixOS/nixpkgs/issues. - -Make sure that there is not already an open issue for your problem. -Please follow the issue template and fill in all requested information -as they help us solve the problem. - -You need a `GitHub`_ account for that. - -Contribute to Nix ------------------ - -The package manager Nix is mostly written in C++. If you are a developer -and want to contribute to it's development, you can find information on -`how to setup a development environment`_ in the manual. - -You can find inspiration for things to improve in the `reported -issues`_. - -Feel free to `join our community`_ to get in -contact with other developers. - -Contribute to Nix packages --------------------------- - -Packaging for Nix is simple when you have understood the basic concept. - -`The manual`_ explains step-by-step how to add new packages to the Nix -package collection. There are also `programming language specific -instructions`_. - -Contribute to NixOS -------------------- - -It’s pretty easy to contribute to NixOS compared to other linux -distributions. All the code is on GitHub in the repository `nixpkgs`_. -Everyone can propose an improvement and most of them get merged after a -review of the maintainers. You will get feedback in the pull request. - -See the `NixOS manual`_ to get started and find all the details. - -You can find inspiration for things to improve in the `reported -issues `__. There are also -`issues tagged with good-first-bug`_ that are a good start for new -contributors. - -Feel free to `join our community`_ of developers! - -.. _GitHub: https://github.com/ -.. _how to setup a development environment: https://nixos.org/manual/nix/stable/contributing/hacking.html -.. _reported issues: https://github.com/NixOS/nix/issues -.. _join our community: https://github.com/NixOS/nixpkgs#community -.. _The manual: https://nixos.org/manual/nix/stable/quick-start.html -.. _programming language specific instructions: https://nixos.org/manual/nixpkgs/stable/#chap-language-support -.. _nixpkgs: https://github.com/NixOS/nixpkgs -.. _NixOS manual: https://nixos.org/manual/nixos/stable/index.html#ch-development -.. _issues tagged with good-first-bug: https://github.com/NixOS/nixpkgs/labels/3.skill%3A%20good-first-bug