Welcome to the new unified Determinate docs experience!
FlakeHubPublishing your flakes

Publishing your flakes to FlakeHub

You can publish flakes to FlakeHub from these platforms:

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

PropertySource
DescriptionThe description field of the flake.nix.
LicenseRead from the GitHub API. Overridden by the spdx-expression option.
NameRead from the ambient environment. Overridden via the name option.
READMERead from README.md in the root of the flake.
TagRead from the ambient environment. Overridden via the tag option.
RollingRelease version numbers. Rolling releases are 0.[rolling-minor].[commit-count], where the commit count comes from the GitHub API.
LabelsRead from the repo’s GitHub topics. Additional labels can be set with the extra-labels option.

Configuration

ParameterDescriptionRequired?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.