{"id":13680731,"url":"https://github.com/DeterminateSystems/flakehub-push","last_synced_at":"2025-04-30T00:30:44.065Z","repository":{"id":189988408,"uuid":"646270826","full_name":"DeterminateSystems/flakehub-push","owner":"DeterminateSystems","description":"Release your Nix flake to FlakeHub.com.","archived":false,"fork":false,"pushed_at":"2025-04-27T18:05:01.000Z","size":6773,"stargazers_count":29,"open_issues_count":17,"forks_count":3,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-27T19:20:34.768Z","etag":null,"topics":["nix","release-automation","semver"],"latest_commit_sha":null,"homepage":"https://flakehub.com","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DeterminateSystems.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-05-27T20:50:45.000Z","updated_at":"2025-04-27T18:05:03.000Z","dependencies_parsed_at":"2024-01-14T15:22:55.757Z","dependency_job_id":"52749bbe-4792-4744-beea-57b9ecfcfa24","html_url":"https://github.com/DeterminateSystems/flakehub-push","commit_stats":null,"previous_names":["determinatesystems/flakehub-push"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeterminateSystems%2Fflakehub-push","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeterminateSystems%2Fflakehub-push/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeterminateSystems%2Fflakehub-push/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeterminateSystems%2Fflakehub-push/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DeterminateSystems","download_url":"https://codeload.github.com/DeterminateSystems/flakehub-push/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251607343,"owners_count":21616742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nix","release-automation","semver"],"created_at":"2024-08-02T13:01:21.178Z","updated_at":"2025-04-30T00:30:44.045Z","avatar_url":"https://github.com/DeterminateSystems.png","language":"Rust","funding_links":[],"categories":["nix","Rust"],"sub_categories":[],"readme":"# `flakehub-push`\n\n[![FlakeHub](https://img.shields.io/endpoint?url=https://flakehub.com/f/DeterminateSystems/flakehub-push/badge)](https://flakehub.com/flake/DeterminateSystems/flakehub-push)\n\nA GitHub Action for publishing [Nix flakes][flakes] to [FlakeHub].\nCreate a [YAML configuration](#configuration), push it to your repo, and you're ready to go.\n\n## Configuration\n\nThere are two ways to get started configuring this Action:\n\n1. Use our [configuration wizard](#guided-wizard) to create a configuration.\n1. Configure the Action [manually](#manual-configuration).\n\n### Guided wizard\n\nAlthough the `flakehub-push` Action requires little configuration, you may benefit from assembling it with our friendly wizard at [flakehub.com/new][wizard].\n\n### Manual configuration\n\nThe example workflow configuration below pushes new tags matching the conventional format\u0026mdash;such as `v1.0.0` or `v0.1.0-rc4`\u0026mdash;to [Flakehub]:\n\n```yaml\n# .github/workflows/flakehub-publish-tagged.yml\nname: Publish tags to FlakeHub\n\non:\n  push:\n    tags:\n      - v?[0-9]+.[0-9]+.[0-9]+*\n\njobs:\n  flakehub:\n    runs-on: ubuntu-22.04\n    permissions:\n      id-token: write # Necessary for authenticating against FlakeHub\n      contents: read\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          ref: ${{ (inputs.tag != null) \u0026\u0026 format('refs/tags/{0}', inputs.tag) || '' }}\n      - name: Install Nix\n        uses: DeterminateSystems/nix-installer-action@main\n      - name: Push to FlakeHub\n        uses: DeterminateSystems/flakehub-push@main\n        with:\n          # For the flake's visibility, you can also select \"unlisted\" if you don't want\n          # it to show up in search results and general listings on flakehub.com\n          visibility: public\n          # Release rolling versions of the form 0.1.* instead of tagged releases\n          rolling: true\n```\n\nSome other common configuration use cases are described in the sections below, along with a full listing of [all available parameters](#available-parameters).\n\n#### Set flake visibility to public, private, or unlisted\n\nWhenever you configure the `flakehub-push` Action, you need to specify the flake's [visibility] using the `visibility` parameter.\nThis configuration would make the flake public:\n\n```yaml\n- uses: DeterminateSystems/flakehub-push@main\n  with:\n    visibility: public\n```\n\nThe available options are:\n\n| Option     | What it means                                                                                                                                                                      |\n| :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `public`   | The flake is viewable and usable if you know the URL for the flake and it shows up in search results and on the [flake listing][all-flakes].                                       |\n| `private`  | The flake is viewable and usable only by users who are authenticated and granted access to the flake. [Private flakes][private-flakes] are available only on [paid plans][signup]. |\n| `unlisted` | The flake is viewable and usable only if you know the URL for it. It shows up neither in search results nor on the [flake listing][all-flakes].                                    |\n\n#### Rolling releases\n\nFor [rolling releases][rolling], as in the example above, set `rolling` to `true`:\n\n```yaml\n- uses: DeterminateSystems/flakehub-push@main\n  with:\n    rolling: true\n```\n\nBy default, the rolling minor version is 1, meaning that versions are of the form `0.1.[commit count]+rev-[git sha]`.\nAn example rolling version would be `0.1.1924+rev-ebfe2c639111d7e82972a12711206afaeeda2450`.\nYou can set a different rolling minor using the `rolling-minor` setting.\nThis configuration sets the rolling minor to 2:\n\n```yaml\n- uses: DeterminateSystems/flakehub-push@main\n  with:\n    rolling: true\n    rolling-minor: 2\n```\n\n#### Tagged releases\n\nPublishing [tagged releases][tagged] is a little bit trickier because you need to tell `flakehub-push` which tag to use.\nHere's an example configuration:\n\n```yaml\non:\n  push:\n    tags:\n      - v?[0-9]+.[0-9]+.[0-9]+*\n  workflow_dispatch:\n    inputs:\n      tag:\n        description: The existing tag to publish to FlakeHub\n        type: string\n        required: true\n\njobs:\n  flakehub-publish:\n    runs-on: ubuntu-latest\n    permissions:\n      id-token: write\n      contents: read\n    steps:\n      - uses: actions/checkout@v4\n        with:\n          # Checking out only the tag isn't necessary but should speed things up\n          ref: ${{ inputs.tag }}\n      - uses: DeterminateSystems/nix-installer-action@main\n      - uses: DeterminateSystems/flakehub-push@main\n        with:\n          visibility: private\n          tag: ${{ inputs.tag }}\n```\n\n#### Store output paths\n\n[FlakeHub] has a feature called [resolved store paths][store-paths] that, when activated, evaluates and stores all of the store paths associated with your flake outputs.\nTo activate resolved store paths, set `include-output-paths` to `true`:\n\n```yaml\n- uses: DeterminateSystems/flakehub-push@main\n  with:\n    include-output-paths: true\n```\n\nThis setting only makes a difference if you're using [FlakeHub Cache][cache].\nYou can [sign up at any time][signup] to take advantage of this feature.\n\n#### Handling multiple flakes in one repository\n\nYou can use `flakehub-push` to publish multiple flakes in the same repository by keeping different flakes in different directories and using the `directory` parameter to specify the root of those flakes.\nHere's an example configuration that would publish separate flakes in the `my-subflake-1` and `my-subflake-2` subdirectories:\n\n```yaml\nname: Publish multiple flakes to FlakeHub\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  flakehub-publish:\n    runs-on: ubuntu-latest\n    permissions:\n      id-token: write\n      contents: read\n    steps:\n      - uses: actions/checkout@v3\n      - uses: DeterminateSystems/nix-installer-action@main\n\n      # Publish my-subflake-1\n      - uses: DeterminateSystems/flakehub-push@main\n        with:\n          rolling: true\n          directory: my-subflake-1\n          visibility: public\n\n      # Publish my-subflake-2\n      - uses: DeterminateSystems/flakehub-push@main\n        with:\n          rolling: true\n          directory: my-subflake-2\n          visibility: public\n```\n\nIn this case, `flakehub-push` publishes rolling releases for both flakes every time there's a push to `main`.\nBut in other cases you may need to structure your configuration differently.\nIf different flakes have different release strategies, for example one flake uses tagged releases and another one uses rolling releases, you may need to provide different configurations in separate YAML files to accommodate separate `on` blocks.\n\n#### Available parameters\n\n| Parameter              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Type          | Required? | Default                    |\n| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------ | :-------- | :------------------------- |\n| `visibility`           | `public`, `unlisted`, or `private`. [Private flakes][private-flakes] are available only on a [FlakeHub paid plan][signup].                                                                                                                                                                                                                                                                                                                                              | enum          | ✅        |                            |\n| `repository`           | The GitHub repository containing your flake in the format of `{org}/{repo}`.                                                                                                                                                                                                                                                                                                                                                                                            | string        | ✅        | `${{ github.repository }}` |\n| `name`                 | The name of your published flake in the format of `{org}/{name}`. The `{org}` must match your organization's GitHub root name or the publish will fail. Specify this only if you want to publish under a different name from the `{org}/{repo}`.                                                                                                                                                                                                                        | string        |           |                            |\n| `include-output-paths` | Whether to expose store paths for the flake's outputs via the FlakeHub API. This is most useful when used in conjunction with [FlakeHub Cache][cache].                                                                                                                                                                                                                                                                                                                  | Boolean       |           | `false`                    |\n| `mirror`               | Whether the repository is mirrored via DeterminateSystems' mirror functionality. This is only usable by DeterminateSystems.                                                                                                                                                                                                                                                                                                                                             | Boolean       |           | `false`                    |\n| `directory`            | The path of your flake relative to the root of the repository. Useful for subflakes.                                                                                                                                                                                                                                                                                                                                                                                    | relative path |           |                            |\n| `tag`                  | The Git tag to use for non-rolling releases. This must be the character `v` followed by a SemVer version, such as `v0.1.1`.                                                                                                                                                                                                                                                                                                                                             | string        |           |                            |\n| `rolling`              | For untagged releases, use a [rolling versioning scheme][rolling]. 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.                                                                                                                                                                                                                                  | Boolean       |           | `false`                    |\n| `rolling-minor`        | Specify the [SemVer] minor version of your [rolling releases][rolling]. All releases will follow the versioning scheme `0.[rolling-minor].[commit count]+rev-[git sha]`.                                                                                                                                                                                                                                                                                                | string        |           |                            |\n| `git-root`             | The root directory of your Git repository.                                                                                                                                                                                                                                                                                                                                                                                                                              | relative path |           | `.`                        |\n| `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 will be ignored. | string        |           | `\"\"`                       |\n| `spdx-expression`      | A valid SPDX license expression. This will be used in place of what GitHub claims your repository's `spdxIdentifier` is.                                                                                                                                                                                                                                                                                                                                                | string        |           | `\"\"`                       |\n| `error-on-conflict`    | Whether to error if a release for the same version has already been uploaded.                                                                                                                                                                                                                                                                                                                                                                                           | Boolean       |           | `false`                    |\n| `github-token`         | The GitHub token for making authenticated GitHub API requests.                                                                                                                                                                                                                                                                                                                                                                                                          | string        |           | `${{ github.token }}`      |\n| `host`                 | The FlakeHub server to use.                                                                                                                                                                                                                                                                                                                                                                                                                                             | URL           |           | `https://api.flakehub.com` |\n| `logger`               | The logger to use. Options are `pretty`, `json`, `full` and `compact`.                                                                                                                                                                                                                                                                                                                                                                                                  | enum          |           | `full`                     |\n| `log-directives`       | A comma-separated list of [tracing directives](https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives). `-`s are replaced with `_`s (such as `nix_installer=trace`).                                                                                                                                                                                                                                                      | string        |           | `flakehub_push=info`       |\n| `source-binary`        | Run a version of the `flakehub-push` binary from somewhere already on disk. Conflicts with all other `source-*` options.                                                                                                                                                                                                                                                                                                                                                | string        |           |                            |\n| `source-branch`        | The branch of `flakehub-push` to use. Conflicts with all other `source-*` options.                                                                                                                                                                                                                                                                                                                                                                                      | string        |           | `main`                     |\n| `source-pr`            | The pull request for `flakehub-push` to use. Conflicts with all other `source-*` options.                                                                                                                                                                                                                                                                                                                                                                               | integer       |           |                            |\n| `source-revision`      | The revision of `flakehub-push` to use. Conflicts with all other `source-*` options.                                                                                                                                                                                                                                                                                                                                                                                    | string        |           |                            |\n| `source-tag`           | The tag of `flakehub-push` to use. Conflicts with all other `source-*` options.                                                                                                                                                                                                                                                                                                                                                                                         | string        |           |                            |\n| `source-url`           | A URL pointing to a `flakehub-push` binary. Overrides all other `source-*` options.                                                                                                                                                                                                                                                                                                                                                                                     | string        |           |                            |\n\n## Integration\n\nThe `flakehub-push` Action sets a handful of [outputs][gha-outputs] for integrating into continuous delivery pipelines:\n\n| Output              | Description                                                                                                                                                                                                                    | Example                                                                                 |\n| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |\n| `flake_name`        | Name of the flake.                                                                                                                                                                                                             | `DeterminateSystems/flakehub-push`                                                      |\n| `flake_version`     | Version of the published flake.                                                                                                                                                                                                | `0.1.99+rev-2075013a3f3544d45a96f4b35df4ed03cd53779c`                                   |\n| `flakeref_exact`    | A precise reference that always resolves to this to this exact release.                                                                                                                                                        | `DeterminateSystems/flakehub-push/=0.1.99+rev-2075013a3f3544d45a96f4b35df4ed03cd53779c` |\n| `flakeref_at_least` | A loose reference to this release. Depending on this reference will require at least this version, and will also resolve to newer releases. This output is not sufficient for deployment pipelines, use `flake_exact` instead. | `DeterminateSystems/flakehub-push/0.1.99+rev-2075013a3f3544d45a96f4b35df4ed03cd53779c`  |\n\nHere's an example Actions workflow that uses these outputs.\nAfter the flake is published, the `Notify external system` step uses [cURL] to notify an external web service that the flake has been successfully published by including the flake's version in a JSON object:\n\n```yaml\nname: Notify external system that flake has been published\n\non:\n  push:\n    branches:\n      - main\n\njobs:\n  deploy:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: DeterminateSystems/nix-installer-action@main # Install Nix\n      - uses: DeterminateSystems/flakehub-push@main # Publish to FlakeHub\n        id: flakehub_push\n        with:\n          visibility: private\n          rolling: true\n          include-output-paths: true\n\n      - name: Notify external system\n        run: |\n          curl -XPOST https://my-recording-system.dev \\\n            -H \"Content-Type: application/json\" \\\n            -H \"Bearer: ${{ secrets.RECORDING_SYSTEM_API_KEY }}\" \\\n            -d '{\"flake_version\":\"${{ steps.flakehub_push.outputs.version }}\"}'\n```\n\n## Developing `flakehub-push`\n\nSee the [development docs](./docs/development.md).\n\n[all-flakes]: https://flakehub.com/flakes\n[cache]: https://flakehub.com/cache\n[curl]: https://curl.se\n[flakehub]: https://flakehub.com\n[flakes]: https://zero-to-nix.com/concepts/flakes\n[gha-outputs]: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs\n[private-flakes]: https://docs.determinate.systems/flakehub/private-flakes\n[rolling]: https://docs.determinate.systems/flakehub/concepts/versioning#rolling\n[semver]: https://docs.determinate.systems/flakehub/concepts/semver\n[signup]: https://flakehub.com/signup\n[store-paths]: https://docs.determinate.systems/flakehub/store-paths\n[tagged]: https://docs.determinate.systems/flakehub/concepts/versioning#tagged\n[visibility]: https://docs.determinate.systems/flakehub/concepts/visibility\n[wizard]: https://flakehub.com/new\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDeterminateSystems%2Fflakehub-push","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDeterminateSystems%2Fflakehub-push","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDeterminateSystems%2Fflakehub-push/lists"}