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:
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:
# 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.