hercules-ci-effects
This module provides
- a mergeable
herculesCI
attribute; read by Hercules CI and thehci
command, - the
hci-effects
library as a module argument inperSystem
/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
hercules-ci.flake-update.enable
hercules-ci.flake-update.autoMergeMethod
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.pullRequestBody
hercules-ci.flake-update.pullRequestTitle
hercules-ci.flake-update.updateBranch
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.onPush.<name>.outputs
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
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.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.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: