Actions/ci
1
0
Fork 0
mirror of https://github.com/DeterminateSystems/ci.git synced 2025-04-19 02:30:10 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Revamp README

Browse source
This commit is contained in:
Luc Perkins 2025-02-19 13:59:20 -05:00
parent 61b0d1d052
commit 4ea7e560ad
No known key found for this signature in database
GPG key ID: C86EE5D85EE4DDA5
3 changed files with 60 additions and 37 deletions

10
.editorconfig Normal file
View file

@ -0,0 +1,10 @@
# https://editorconfig.org
root = true
[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

2
.github/workflows/validate.yml vendored
View file

@ -16,7 +16,7 @@ jobs:
- uses: DeterminateSystems/nix-installer-action@main
with:
determinate: true
- uses: DeterminateSystems/magic-nix-cache-action@main
- uses: DeterminateSystems/flakehub-cache-action@main
- run: nix run nixpkgs#action-validator -- -v ./.github/workflows/workflow.yml
- run: nix run nixpkgs#nodePackages.prettier -- --check .

85
README.md
View file

@ -1,20 +1,25 @@
# Determinate CI
The one-stop shop for effortless Nix CI in GitHub Actions.
> [!NOTE]
> This Action is intended for users of [FlakeHub Cache][cache].
> [Sign up][signup] for a FlakeHub paid plan to get started.
Your one-stop shop for effortless [Nix] CI in GitHub Actions.
- Automatically builds on all the architectures your flake supports.
- Built-in, free caching using [Magic Nix Cache][magic-nix-cache] and optionally [FlakeHub Cache][flakehub-cache].
- Discovers and builds your entire flake using [Flake Schemas][flake-schemas].
- Easily opt-in to publishing to [FlakeHub][flakehub].
- Caches all of your flake outputs using [FlakeHub Cache][cache].
- Discovers and builds your entire flake using [flake schemas][flake-schemas].
- [Publishes your flake][publishing] to [FlakeHub][flakehub] if you [opt in](#publishing-to-flakehub).
**Status:** The Determinate CI workflow is an experiment.
It may change significantly without warning.
Please feel free to try it out, report bugs, and [let us know how it goes in our Discord][discord]!
Stabilization to follow.
> [!WARNING]
> The Determinate CI workflow is an experiment.
> It may change significantly without warning.
> Please feel free to try it out, report bugs, and [let us know how it goes in our Discord][discord]!
> Stabilization to follow.
## Usage
Create a workflow in your project at `.github/workflows/ci.yml`, and copy in this text:
Create an Actions workflow in your project at `.github/workflows/ci.yml`, copy in this text...
```yaml
on:
@ -25,7 +30,7 @@ on:
- main
- master
tags:
- "v?[0-9]+.[0-9]+.[0-9]+*"
- v?[0-9]+.[0-9]+.[0-9]+*
concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
@ -35,18 +40,19 @@ jobs:
DeterminateCI:
uses: DeterminateSystems/ci/.github/workflows/workflow.yml@main
permissions:
id-token: "write"
contents: "read"
id-token: write
contents: read
```
and you're done, you'll get something like this:
...and you're done!
You'll see something like this when your workflow has run successfully:
<img width="1140" alt="image" src="https://github.com/DeterminateSystems/ci/assets/76716/c2c6aa07-3fd3-4e66-9440-bef264b472da">
![Screenshot of successful build](https://github.com/DeterminateSystems/ci/assets/76716/c2c6aa07-3fd3-4e66-9440-bef264b472da)
### Publishing to FlakeHub
Publish to FlakeHub on every push to the default branch, and every tag.
Specify the flake's visibility:
Publish to FlakeHub on every push to the default branch and on every tag.
Specify the flake's [visibility]:
```yaml
on:
@ -57,7 +63,7 @@ on:
- main
- master
tags:
- "v?[0-9]+.[0-9]+.[0-9]+*"
- v?[0-9]+.[0-9]+.[0-9]+*
concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
@ -67,31 +73,33 @@ jobs:
DeterminateCI:
uses: DeterminateSystems/ci/.github/workflows/workflow.yml@main
permissions:
id-token: "write"
contents: "read"
id-token: write
contents: read
with:
visibility: public
```
For [private flakes][private-flakes], set `visibility` to `private`.
### Caching
To speed up builds, the workflow uses [FlakeHub Cache](https://flakehub.com/cache) as a cache.
This workflow uses [FlakeHub Cache][cache] as a [binary cache][binary-cache].
> [!NOTE]
> FlakeHub Cache only works if you're on a paid plan.
If you're not signed up for FlakeHub, the workflow will still pass, but may be slower.
If you're not signed up for FlakeHub, the workflow will still pass but won't cache your flake outputs.
In this case, your logs will include a warning like this:
```
ERROR magic_nix_cache: FlakeHub cache initialization failed: FlakeHub cache error: HTTP 401 Unauthorized: "User is not authorized for this resource."
```
### Advanced Usage
### Advanced usage
#### Custom Runner Types
#### Custom runner types
The default runner map uses `ubuntu-latest` for x86 Linux, and `macos-latest` for macOS.
The default runner map uses `ubuntu-latest` for x86 Linux and `macos-latest` for macOS.
Take advantage of [larger GitHub runners][runners] by providing a custom runner map:
```yaml
@ -99,8 +107,8 @@ jobs:
DeterminateCI:
uses: DeterminateSystems/ci/.github/workflows/workflow.yml@main
permissions:
id-token: "write"
contents: "read"
id-token: write
contents: read
with:
runner-map: |
{
@ -112,7 +120,7 @@ jobs:
}
```
#### SSH Private Keys
#### Private SSH keys
Configure an SSH agent with a secret private key for private repository support.
@ -121,8 +129,8 @@ jobs:
DeterminateCI:
uses: DeterminateSystems/ci/.github/workflows/workflow.yml@main
permissions:
id-token: "write"
contents: "read"
id-token: write
contents: read
with:
enable-ssh-agent: true
secrets:
@ -131,13 +139,18 @@ jobs:
## Notes
Use of this workflow uses a collection of GitHub Action by Determinate Systems, which are covered by the Determinate Systems [privacy policy][privacy policy] and [terms of service][tos].
This workflow uses a collection of GitHub Actions by Determinate Systems, all of which are covered by the Determinate Systems [privacy policy][privacy] and [terms of service][tos].
[flake-schemas]: https://determinate.systems/posts/flake-schemas/
[magic-nix-cache]: https://github.com/determinateSystems/magic-nix-cache-action
[binary-cache]: https://zero-to-nix.com/concepts/caching
[cache]: https://flakehub.com/cache
[flake-schemas]: https://github.com/DeterminateSystems/flake-schemas
[flakehub]: https://flakehub.com/
[runners]: https://docs.github.com/en/actions/using-github-hosted-runners/about-larger-runners
[discord]: https://determinate.systems/discord
[privacy policy]: https://determinate.systems/policies/privacy/
[tos]: https://determinate.systems/policies/terms-of-service/
[flakehub-cache]: https://determinate.systems/posts/flakehub-cache-beta/
[nix]: https://zero-to-nix.com
[privacy]: https://determinate.systems/policies/privacy
[private-flakes]: https://docs.determinate.systems/flakehub/private-flakes
[publishing]: https://docs.determinate.systems/flakehub/publishing
[runners]: https://docs.github.com/en/actions/using-github-hosted-runners/about-larger-runners
[signup]: https://flakehub.com/signup
[tos]: https://determinate.systems/policies/terms-of-service
[visibility]: https://docs.determinate.systems/flakehub/concepts/visibility