hercules-ci-effects

This module provides

  • a mergeable herculesCI attribute; read by Hercules CI and the hci command,
  • the hci-effects library as a module argument in perSystem / withSystem,
  • ready to go, configurable continuous deployment jobs

Installation

To use these options, add to your flake inputs:

hercules-ci-effects.url = "github:hercules-ci/hercules-ci-effects";

and inside the mkFlake:

imports = [
  inputs.hercules-ci-effects.flakeModule
];

Run nix flake lock and you're set.

Options

defaultEffectSystem

hercules-ci.flake-update.enable

hercules-ci.flake-update.autoMergeMethod

hercules-ci.flake-update.baseBranch

hercules-ci.flake-update.baseMerge.enable

hercules-ci.flake-update.baseMerge.branch

hercules-ci.flake-update.baseMerge.method

hercules-ci.flake-update.createPullRequest

hercules-ci.flake-update.effect.settings

hercules-ci.flake-update.effect.system

hercules-ci.flake-update.flakes

hercules-ci.flake-update.flakes.<name>.commitSummary

hercules-ci.flake-update.flakes.<name>.inputs

hercules-ci.flake-update.forgeType

hercules-ci.flake-update.nix.package

hercules-ci.flake-update.pullRequestBody

hercules-ci.flake-update.pullRequestTitle

hercules-ci.flake-update.updateBranch

hercules-ci.flake-update.when

hercules-ci.github-pages.branch

hercules-ci.github-pages.check.enable

hercules-ci.github-pages.pushJob

hercules-ci.github-pages.settings

hercules-ci.github-releases.checkArtifacts

hercules-ci.github-releases.condition

hercules-ci.github-releases.files

hercules-ci.github-releases.files.*.archiver

hercules-ci.github-releases.files.*.label

hercules-ci.github-releases.files.*.path

hercules-ci.github-releases.files.*.paths

hercules-ci.github-releases.filesPerSystem

hercules-ci.github-releases.filesPerSystem.<function body>.*.archiver

hercules-ci.github-releases.filesPerSystem.<function body>.*.label

hercules-ci.github-releases.filesPerSystem.<function body>.*.path

hercules-ci.github-releases.filesPerSystem.<function body>.*.paths

hercules-ci.github-releases.pushJobName

hercules-ci.github-releases.releaseTag

hercules-ci.github-releases.systems

herculesCI

herculesCI.ciSystems

herculesCI.onPush

herculesCI.onPush.<name>.outputs

herculesCI.onSchedule

herculesCI.onSchedule.<name>.outputs

herculesCI.onSchedule.<name>.when

herculesCI.onSchedule.<name>.when.dayOfMonth

herculesCI.onSchedule.<name>.when.dayOfWeek

herculesCI.onSchedule.<name>.when.hour

herculesCI.onSchedule.<name>.when.minute

herculesCI.repo

herculesCI.repo.branch

herculesCI.repo.forgeType

herculesCI.repo.name

herculesCI.repo.owner

herculesCI.repo.ref

herculesCI.repo.remoteHttpUrl

herculesCI.repo.remoteSshUrl

herculesCI.repo.rev

herculesCI.repo.shortRev

herculesCI.repo.tag

herculesCI.repo.webUrl

perSystem.hercules-ci.github-pages.settings

perSystem.herculesCIEffects.pkgs

defaultEffectSystem

The default system type that some integrations will use to run their effects on.

Type: string

Default: "x86_64-linux"

Declared by:

hercules-ci-effects/flake-modules/herculesCI-helpers.nix

hercules-ci.flake-update.enable

Whether to create a scheduled flake update job.

For a complete example, see the hercules-ci-effects documentation on hercules-ci.flake-update.

Requires hercules-ci-agent 0.9.8 or newer.

Type: boolean

Default: false

Example: true

Declared by:

hercules-ci-effects/effects/flake-update/flake-module.nix

hercules-ci.flake-update.autoMergeMethod

Whether to enable auto-merge on new pull requests, and how to merge it.

This requires GitHub branch protection to be configured for the repository.

Type: one of <null>, “merge”, “rebase”, “squash”

Default: null

Declared by:

hercules-ci-effects/effects/flake-update/flake-module.nix

hercules-ci.flake-update.baseBranch

Branch name on the remote that the update branch will be

  • based on (via hercules-ci.flake-update.baseMerge.branch), and

  • merged back into if hercules-ci.flake-update.createPullRequest is enabled.

"HEAD" refers to the default branch, which is often main or master.

Type: string

Default: "HEAD"

Example: "develop"

Declared by:

hercules-ci-effects/effects/flake-update/flake-module.nix

hercules-ci.flake-update.baseMerge.enable

Whether to merge the base branch into the update branch before running the update.

This is useful to ensure that the update branch is up to date with the base branch.

If this option is false, you may have to merge or rebase the update branch manually sometimes.

Type: boolean

Default: false

Declared by:

hercules-ci-effects/effects/flake-update/flake-module.nix

hercules-ci.flake-update.baseMerge.branch

Branch name on the remote to merge into the update branch before running the update.

Used when hercules-ci.flake-update.baseMerge.enable is true.

Type: string

Default: hercules-ci.flake-update.baseBranch

Declared by:

hercules-ci-effects/effects/flake-update/flake-module.nix

hercules-ci.flake-update.baseMerge.method

How to merge the base branch into the update branch before running the update.

Used when hercules-ci.flake-update.baseMerge.enable is true.

Type: one of “merge”, “rebase”

Default: "merge"

Declared by:

hercules-ci-effects/effects/flake-update/flake-module.nix

hercules-ci.flake-update.createPullRequest

Whether to create a pull request for the updated flake.lock.

Type: boolean

Default: true

Declared by:

hercules-ci-effects/effects/flake-update/flake-module.nix

hercules-ci.flake-update.effect.settings

A module that extends the flake-update effect arbitrarily.

See also:

Type: module

Default: { }

Declared by:

hercules-ci-effects/effects/flake-update/flake-module.nix

hercules-ci.flake-update.effect.system

The system on which to run the flake update job.

Type: string

Default: config.defaultEffectSystem

Example: "aarch64-linux"

Declared by:

hercules-ci-effects/effects/flake-update/flake-module.nix

hercules-ci.flake-update.flakes

Flakes to update.

The attribute names refer to the relative paths where the flakes/subflakes are located in the repository.

The values specify further details about how to update the lock. See the sub-options for details.

NOTE: If you provide a definition for this option, it does not extend the default. You must specify all flakes you want to update, including the project root (".") if applicable.

Type: attribute set of (submodule)

Default:

{
  "." = { };
}

Example:

{
  "." = {
    commitSummary = "/flake.lock: Update";
  };
  "path/to/subflake" = {
    inputs = [
      "nixpkgs"
    ];
  };
}

Declared by:

hercules-ci-effects/effects/flake-update/flake-module.nix

hercules-ci.flake-update.flakes.<name>.commitSummary

Summary for commit. “” means to use the default.

Type: string

Default: ""

Example: "chore: update flake inputs"

Declared by:

hercules-ci-effects/effects/flake-update/flake-module.nix

hercules-ci.flake-update.flakes.<name>.inputs

Flake inputs to update. The default, [] means to update all inputs.

Type: list of string

Default: [ ]

Example: "[\"nixpkgs\" \"nixpkgs-unstable\"]"

Declared by:

hercules-ci-effects/effects/flake-update/flake-module.nix

hercules-ci.flake-update.forgeType

The type of Git server commited to.

Type: string

Default: "github"

Example: "gitlab"

Declared by:

hercules-ci-effects/effects/flake-update/flake-module.nix

hercules-ci.flake-update.nix.package

The Nix package to use for performing the lockfile updates.

The function arguments are the module arguments of perSystem for hercules-ci.flake-update.effect.system.

Type: function that evaluates to a(n) package

Default: { pkgs, ... }: pkgs.nix

Declared by:

hercules-ci-effects/effects/flake-update/flake-module.nix

hercules-ci.flake-update.pullRequestBody

The body of the pull request being made

Type: null or string

Default:

''
  Update `flake.lock`. See the commit message(s) for details.

You may reset this branch by deleting it and re-running the update job.

  git push origin :flake-update

''

Example: "updated flake.lock"

Declared by:

hercules-ci-effects/effects/flake-update/flake-module.nix

hercules-ci.flake-update.pullRequestTitle

The title of the pull request being made

Type: string

Default: "`flake.lock`: Update"

Example: "chore: update flake.lock"

Declared by:

hercules-ci-effects/effects/flake-update/flake-module.nix

hercules-ci.flake-update.updateBranch

To which branch to push the updated flake lock.

Type: string

Default: "flake-update"

Example: "update"

Declared by:

hercules-ci-effects/effects/flake-update/flake-module.nix

hercules-ci.flake-update.when

See herculesCI.onSchedule.<name>.when for details.

Type: raw value

Declared by:

hercules-ci-effects/effects/flake-update/flake-module.nix

hercules-ci.github-pages.branch

A GitHub Pages deployment will be triggered when changes are pushed to this branch.

A non-null value enables the effect.

Type: null or string

Default: null

Declared by:

hercules-ci-effects/flake-modules/github-pages.nix

hercules-ci.github-pages.check.enable

Whether to make sure that the effect is buildable. This adds checks.${config.defaultEffectSystem}.gh-pages to onPush.default.

Type: boolean

Default: true

Declared by:

hercules-ci-effects/flake-modules/github-pages.nix

hercules-ci.github-pages.pushJob

The Hercules CI job in which to perform the deployment.

By default the GitHub pages deployment is triggered by the onPush.default job, so that the deployment only proceeds when the default builds are successful.

Type: string

Default: "default"

Declared by:

hercules-ci-effects/flake-modules/github-pages.nix

hercules-ci.github-pages.settings

Modular settings for the GitHub Pages effect.

For system-dependent settings, define perSystem.hercules-ci.github-pages.settings instead.

See gitWriteBranch for options.

Type: module

Example:

{
  message = "Update GitHub Pages";
}

Declared by:

hercules-ci-effects/flake-modules/github-pages.nix

hercules-ci.github-releases.checkArtifacts

Condition under which to check whether artifacts can be built.

Type: function that evaluates to a(n) boolean

Default: _: true

Declared by:

hercules-ci-effects/flake-modules/github-releases

hercules-ci.github-releases.condition

Condition under which a release is going to be pushed. This is a function accepting HerculesCI parameters and returning boolean. By default, pushing happens if a tag is present.

Type: function that evaluates to a(n) boolean

Default:

{ tag, ... }: tag != null

Declared by:

hercules-ci-effects/flake-modules/github-releases

hercules-ci.github-releases.files

List of asset files or archives.

Each entry must be either an attribute set of type

  • { label: string, path: string } for a single file, or

  • { label: string, paths: [string], archiver: 'zip' } for an archive.

In case of archive, paths may contain directories: their contents will be archived recursively.

Type: list of (submodule)

Default: []

Example:

[
  {
    label = "api.json";
    path = withSystem "x86_64-linux" ({config, ...}: config.packages.api-json);
  }
  {
    label = "api-docs.zip";
    paths = withSystem "x86_64-linux" ({config, ...}: [ config.packages.api-docs ]);
    archiver = "zip";
  }
]

Declared by:

hercules-ci-effects/flake-modules/github-releases

hercules-ci.github-releases.files.*.archiver

The archiver to use for the archive.

This must be set when paths is set.

Type: value “zip” (singular enum)

Default: (unset)

Declared by:

hercules-ci-effects/flake-modules/github-releases

hercules-ci.github-releases.files.*.label

Label of the asset file or archive.

This is the name that will be used in the GitHub release.

Type: string

Declared by:

hercules-ci-effects/flake-modules/github-releases

hercules-ci.github-releases.files.*.path

Path to the asset file. Must not be a directory. Mutually exclusive with paths.

Type: path

Declared by:

hercules-ci-effects/flake-modules/github-releases

hercules-ci.github-releases.files.*.paths

Paths to the asset files. Mutually exclusive with path.

Directories are allowed, and their contents will be archived recursively.

Type: list of path

Declared by:

hercules-ci-effects/flake-modules/github-releases

hercules-ci.github-releases.filesPerSystem

List of asset files or archives for each system.

The arguments passed are the same as those passed to perSystem modules.

The function is invoked for each of the systems. The returned labels must be unique across invocations. This generally means that you have to include the system value in the attribute names.

NOTE: If you are implementing generic logic, consider placing the function in a mkIf, so that the function remains undefined in cases where it is statically known to produce no files. When filesPerSystem has no definitions, a traversal of potentially many perSystems modules is avoided.

Type: function that evaluates to a(n) list of (submodule)

Example:

{ system, config, ... }: [
  {
    label = "foo-static-${system}";
    path = lib.getExe config.packages.foo-static;
  }
]

Declared by:

hercules-ci-effects/flake-modules/github-releases

hercules-ci.github-releases.filesPerSystem.<function body>.*.archiver

The archiver to use for the archive.

This must be set when paths is set.

Type: value “zip” (singular enum)

Default: (unset)

Declared by:

hercules-ci-effects/flake-modules/github-releases

hercules-ci.github-releases.filesPerSystem.<function body>.*.label

Label of the asset file or archive.

This is the name that will be used in the GitHub release.

Type: string

Declared by:

hercules-ci-effects/flake-modules/github-releases

hercules-ci.github-releases.filesPerSystem.<function body>.*.path

Path to the asset file. Must not be a directory. Mutually exclusive with paths.

Type: path

Declared by:

hercules-ci-effects/flake-modules/github-releases

hercules-ci.github-releases.filesPerSystem.<function body>.*.paths

Paths to the asset files. Mutually exclusive with path.

Directories are allowed, and their contents will be archived recursively.

Type: list of path

Declared by:

hercules-ci-effects/flake-modules/github-releases

hercules-ci.github-releases.pushJobName

Name of the Hercules CI job in which to perform the deployment. By default the GitHub pages deployment is triggered by the onPush.default job, so that the deployment only proceeds when the default builds are successful.

Type: string

Default: default

Declared by:

hercules-ci-effects/flake-modules/github-releases

hercules-ci.github-releases.releaseTag

Tag to be assigned to the release.

Type: function that evaluates to a(n) string

Default: herculesCI: herculesCI.config.repo.tag

Declared by:

hercules-ci-effects/flake-modules/github-releases

hercules-ci.github-releases.systems

List of systems for which to call filesPerSystem.

Type: null or (list of string)

Default: null, which means that herculesCI.ciSystems will be used.

Declared by:

hercules-ci-effects/flake-modules/github-releases

herculesCI

Hercules CI environment and configuration. See the sub-options for details.

This module represents a function. Hercules CI calls this function to provide expressions in the flake with extra information, such as repository and job metadata.

While this attribute feels a lot like a submodule, it can not be queried by definitions outside of herculesCI. This is required by the design of flakes: evaluation of the standard flake attribute values is hermetic.

Data that is unique to Hercules CI (as opposed to the flake itself) is provided by in the sub-options of herculesCI. This is syntactically different from the native herculesCI attribute interface. For example, instead of { primaryRepo, ... }: ... primaryRepo.ref, you would write { config, ... }: ... config.repo.ref.

See e.g. ref.

Type: module

Declared by:

hercules-ci-effects/flake-modules/herculesCI-helpers.nix, hercules-ci-effects/flake-modules/herculesCI-attribute.nix

herculesCI.ciSystems

Flake systems for which to generate attributes in herculesCI.onPush.default.outputs.

Type: list of string

Default: config.systems # from flake parts

Declared by:

hercules-ci-effects/flake-modules/herculesCI-attribute.nix

herculesCI.onPush

This declares what to do when a Git ref is updated, such as when you push a commit or after you merge a pull request.

By default onPush.default defines a job that builds the known flake output attributes. It can be disabled by setting onPush.default.enable = false;.

The name of the job (from onPush.<name>) will be used as part of the commit status of the resulting job.

Type: lazy attribute set of (submodule)

Default: { }

Declared by:

hercules-ci-effects/flake-modules/herculesCI-attribute.nix

herculesCI.onPush.<name>.outputs

A collection of builds and effects. These may be nested recursively into attribute sets.

Hercules CI’s traversal of nested sets can be cancelled with lib.dontRecurseIntoAttrs.

See the parent option for details about when the job runs.

Type: a tree of attribute sets and derivations

Declared by:

hercules-ci-effects/flake-modules/herculesCI-attribute.nix

herculesCI.onSchedule

Since hercules-ci-agent 0.9.8

Behaves similar to onPush, but is responsible for jobs that respond to the passing of time rather than to a git push or equivalent.

Type: lazy attribute set of (submodule)

Default: { }

Declared by:

hercules-ci-effects/flake-modules/herculesCI-attribute.nix

herculesCI.onSchedule.<name>.outputs

A collection of builds and effects. These may be nested recursively into attribute sets.

Hercules CI’s traversal of nested sets can be cancelled with lib.dontRecurseIntoAttrs.

See the parent option for details about when the job runs.

Type: a tree of attribute sets and derivations

Declared by:

hercules-ci-effects/flake-modules/herculesCI-attribute.nix

herculesCI.onSchedule.<name>.when

The time at which to schedule a job.

Each subattribute represents an equality, all of which will hold at the next planned time. The time zone is UTC.

The minute or hour attributes can be omitted, in which case Hercules CI will pick an arbitrary time for you.

See the when.* options below for details.

Type: submodule

Default: { }

Declared by:

hercules-ci-effects/flake-modules/herculesCI-attribute.nix

herculesCI.onSchedule.<name>.when.dayOfMonth

An optional list of day of the month during which to create a job.

The default value null represents all days.

Type: null or ((list of integer between 0 and 31 (both inclusive)) or integer between 0 and 31 (both inclusive) convertible to it)

Default: null

Declared by:

hercules-ci-effects/flake-modules/types/when.nix

herculesCI.onSchedule.<name>.when.dayOfWeek

An optional list of week days during which to create a job.

The default value null represents all days.

Type: null or ((list of (one of “Mon”, “Tue”, “Wed”, “Thu”, “Fri”, “Sat”, “Sun”)) or (one of “Mon”, “Tue”, “Wed”, “Thu”, “Fri”, “Sat”, “Sun”) convertible to it)

Default: null

Declared by:

hercules-ci-effects/flake-modules/types/when.nix

herculesCI.onSchedule.<name>.when.hour

An optional integer representing the hours at which a job should be created.

The default value null represents an arbitrary hour.

Type: null or ((list of integer between 0 and 23 (both inclusive)) or integer between 0 and 23 (both inclusive) convertible to it)

Default: null

Declared by:

hercules-ci-effects/flake-modules/types/when.nix

herculesCI.onSchedule.<name>.when.minute

An optional integer representing the minute mark at which a job should be created.

The default value null represents an arbitrary minute.

Type: null or integer between 0 and 59 (both inclusive)

Default: null

Declared by:

hercules-ci-effects/flake-modules/types/when.nix

herculesCI.repo

The repository and checkout metadata of the current checkout, provided by Hercules CI. These options are read-only.

You may read options by querying the config module argument.

Type: submodule (read only)

Declared by:

hercules-ci-effects/flake-modules/herculesCI-attribute.nix

herculesCI.repo.branch

The branch of the checkout. null when not on a branch; e.g. when on a tag.

Type: null or string (read only)

Example: "main"

Declared by:

hercules-ci-effects/flake-modules/herculesCI-attribute.nix

herculesCI.repo.forgeType

What forge implementation hosts the repository.

E.g. “github” or “gitlab”

Since hercules-ci-agent 0.9.8

Type: string (read only)

Default:

Example: "github"

Declared by:

hercules-ci-effects/flake-modules/herculesCI-attribute.nix

herculesCI.repo.name

The name of the repository.

Since hercules-ci-agent 0.9.8

Type: string (read only)

Default:

Declared by:

hercules-ci-effects/flake-modules/herculesCI-attribute.nix

herculesCI.repo.owner

The owner of the repository.

Since hercules-ci-agent 0.9.8

Type: string (read only)

Default:

Declared by:

hercules-ci-effects/flake-modules/herculesCI-attribute.nix

herculesCI.repo.ref

The git “ref” of the checkout.

Type: string (read only)

Example: "refs/heads/main"

Declared by:

hercules-ci-effects/flake-modules/herculesCI-attribute.nix

herculesCI.repo.remoteHttpUrl

HTTP url for cloning the repository.

Since hercules-ci-agent 0.9.8

Type: string (read only)

Default:

Declared by:

hercules-ci-effects/flake-modules/herculesCI-attribute.nix

herculesCI.repo.remoteSshUrl

SSH url for cloning the repository.

Since hercules-ci-agent 0.9.8

Type: string (read only)

Default:

Declared by:

hercules-ci-effects/flake-modules/herculesCI-attribute.nix

herculesCI.repo.rev

The git revision, also known as the commit hash.

Type: string (read only)

Example: "17ae1f614017447a983c34bb046892b3c571df52"

Declared by:

hercules-ci-effects/flake-modules/herculesCI-attribute.nix

herculesCI.repo.shortRev

An abbreviated rev.

Type: string (read only)

Example: "17ae1f6"

Declared by:

hercules-ci-effects/flake-modules/herculesCI-attribute.nix

herculesCI.repo.tag

The tag of the checkout. null when not on a tag; e.g. when on a branch.

Type: null or string (read only)

Example: "1.0"

Declared by:

hercules-ci-effects/flake-modules/herculesCI-attribute.nix

herculesCI.repo.webUrl

A URL to open the repository in the browser.

Since hercules-ci-agent 0.9.8

Type: string (read only)

Default:

Declared by:

hercules-ci-effects/flake-modules/herculesCI-attribute.nix

perSystem.hercules-ci.github-pages.settings

Modular settings for the GitHub Pages effect.

See gitWriteBranch for options.

Type: module

Example:

{
  contents = config.packages.docs + "/share/doc/mypkg/html";
}

Declared by:

hercules-ci-effects/flake-modules/github-pages.nix

perSystem.herculesCIEffects.pkgs

Nixpkgs instance to use for hercules-ci-effects.

The effects functions, etc, will be provided as the effects module argument of perSystem.

Type: raw value

Default: pkgs (module argument)

Declared by:

hercules-ci-effects/flake-modules/module-argument.nix