Publishing your flakes to FlakeHub

You can publish flakes to FlakeHub from these platforms:

GitHub Actions
GitLab CI/CD

We plan to support additional platforms in the future.

You can only publish flakes from one of the trusted platforms listed above; you cannot publish flakes in an ad-hoc way from, say, your laptop or a machine running in the cloud. For more on why this is the case, see FlakeHub’s publishing model below.

GitHub Actions

On GitHub Actions, you can publish your flakes to FlakeHub using the flakehub-push Action. Here’s an example configuration:

.github/workflows/flakehub-publish-rolling.yaml

name: Publish every Git push to main to FlakeHub
 
on:
  push:
    branches:
      - main
 
jobs:
  flakehub-publish:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: DeterminateSystems/nix-installer-action@main
      - uses: DeterminateSystems/flakehub-push@main
        with:
          name: DeterminateSystems/flakehub-push
          rolling: true
          visibility: public

We recommend using FlakeHub’s flake publishing wizard as a quickstart.

GitLab CI

On GitLab CI, you can publish your flakes to FlakeHub using the flakehub-push component.

Suggestions for your flake’s README

While it’s totally up to you what you put in your README, we recommend something along these lines:

README.md

# Use as a flake
 
[![FlakeHub](https://img.shields.io/endpoint?url=https://flakehub.com/f/your-org-name/your-flake-name/badge)](https://flakehub.com/flake/your-org-name/your-flake-name)
 
Add `your-flake-name` to your `flake.nix`:
 
```nix
{
  inputs.your-flake-name.url = "https://flakehub.com/f/your-org-name/your-flake-name/*";
 
  outputs = { self, your-flake-name }: {
    # Use in your outputs
  };
}
```

Notice the badge from shields.io and the example flake.nix file.

Flake metadata

Property	Source
Description	The description field of the `flake.nix`.
License	Read from the GitHub API. Overridden by the `spdx-expression` option.
Name	Read from the ambient environment. Overridden via the name option.
README	Read from `README.md` in the root of the flake.
Tag	Read from the ambient environment. Overridden via the tag option.
Rolling	Release version numbers. Rolling releases are `0.[rolling-minor].[commit-count]`, where the commit count comes from the GitHub API.
Labels	Read from the repo’s GitHub topics. Additional labels can be set with the extra-labels option.

Configuration

Parameter	Description	Required?	Default
`directory`	the directory of your flake (useful for subflakes)
`extra-labels`	`flakehub-push` automatically uses the GitHub repo's topics as labels. This `extra-labels` parameter enables you to add extra labels beyond that as a comma-separated string. Only alphanumeric characters and hyphens are allowed in labels and the maximum length of labels is 50 characters. You can specify a maximum of 20 extra labels, and have a maximum of 25 labels, including those that we retrieve from GitHub. Any labels after the 25th are ignored.
`flakehub-push-binary`	Run a version of the `flakehub-push` binary from somewhere already on disk. Conflicts with all other `flakehub-push-*` options.
`flakehub-push-branch`	The branch of `flakehub-push` to use. Conflicts with all other `flakehub-push-*` options.		`main`
`flakehub-push-pr`	The PR of `flakehub-push` to use. Conflicts with all other `flakehub-push-*` options.
`flakehub-push-revision`	The revision of `flakehub-push` to use. Conflicts with all other `flakehub-push-*` options.
`flakehub-push-tag`	The tag of `flakehub-push` to use. Conflicts with all other `flakehub-push-*` options.
`flakehub-push-url`	A URL pointing to a `flakehub-push` binary. Overrides all other `flakehub-push-*` options.
`git-root`	the git root of your flake		`.`
`github-token`	A GitHub token for making authenticated GitHub API requests		`${{ github.token }}`
`host`	The FlakeHub server to use		`https://api.flakehub.com`
`log-directives`	A list of Tracing directives, comma separated, `-`s replaced with `_` (such as `nix_installer=trace`, see https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives)		`flakehub_push=info`
`logger`	The logger to use for install (options are `pretty`, `json`, `full`, `compact`)		`full`
`mirror`	If the repository is mirrored via DeterminateSystems' mirror functionality. This is only usable by DeterminateSystems.
`repository`	The actual GitHub repository containing your flake. In the format of OrgName/RepoName.	✅	`${{ github.repository }}`
`rolling`	For untagged releases, use a rolling versioning scheme. When this is enabled, the default versioning scheme is `0.1.[commit count]+rev-[git sha]`. To customize the SemVer minor version, set the `rolling-minor` option.
`rolling-minor`	Specify the SemVer minor version of your rolling releases. All releases will follow the versioning scheme `0.[rolling-minor].[commit count]+rev-[git sha]`.
`spdx-expression`	A valid SPDX license expression. This will be used in place of what GitHub claims your repository's `spdxIdentifier` is.
`tag`	example: v0.1.1
`name`	The name of your published flake. In the format of `OrgName/RepoName`. `OrgName` must match your organization's GitHub root name or the publish will fail.
`visibility`	`public`, `private`, or `unlisted`	✅

FlakeHub’s publishing model

FlakeHub follows a trusted platform model, supporting publishing flakes only from the platforms listed above. Correspondingly, FlakeHub does not support ad-hoc publishing from developer laptops, machines running in the cloud, or any other source.

This is by design. According to the trusted platform model, things like this should never happen:

You publish a flake release because you accidentally run a command on your laptop that’s stored in your shell history
You publish a flake release because you forget to remove a publish command from a shell script that you run regularly
A malicious actor acquires the necessary credentials and uses an ephemeral EC2 instance to publish a flake release in which a package output seems legitimate but secretly starts up a Bitcoin miner
A non-malicious team member misunderstands team policy and publishes a flake release without running the necessary checks

We built FlakeHub for organizations with demanding security and process requirements, and we don’t feel that ad-hoc publishing serves such organizations well.

Getting started FlakeHub Cache