Git-related Modules

Module `git-auth`

The module provides the basics for working with a git repository.

Example import:

hci-effects.modularEffect {
  imports = [
    hci-effects.modules.git-auth
  ];
}

git.checkout.forgeType

The forge type according to Hercules CI.

Valid values include "github" and "gitlab", or you could forward this from herculesCI.repo.forgeType (flake-parts) or the metadata passed to the herculesCI function: primaryRepo.forgeType.

Type: string

Example:

primaryRepo.forgeType

Declared by:

git-auth

git.checkout.remote.url

The git remote URL. Currently only http/https URLs are supported.

The current repo URL is available in herculesCI.repo.remoteHttpUrl or the metadata passed to the herculesCI function: primaryRepo.remoteHttpUrl.

Type: string

Example:

primaryRepo.remoteHttpUrl

Declared by:

git-auth

git.checkout.tokenSecret

Name of the secret that contains the git token.

Type: string

Default:

"token"

Declared by:

git-auth

git.checkout.user

User name for authentication with the git remote.

Type: string

Default:

"git"

Declared by:

git-auth

Module `git-update`

A module that facilitates the updating of a git repository.

Example import:

hci-effects.modularEffect {
  imports = [
    hci-effects.modules.git-update
  ];
}

git.update.baseBranch

Branch name on the remote that the update branch will be

based on (via git.update.baseMerge.branch), and
merged back into (via git.update.pullRequest.base) if enabled.

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

Type: string

Default:

"HEAD"

Declared by:

git-auth

git.update.baseMerge.enable

Whether to update an existing update branch with changes from the base branch before running git.update.script.

This option only applies when the update branch already exists from a previous run. The existing branch is likely stale, so enabling this ensures it includes recent changes from the base branch.

If disabled and the update branch exists, the update script will run from the branch’s current state, which may be missing recent changes from the base branch.

Type: boolean

Default:

false

Declared by:

git-auth

git.update.baseMerge.branch

Branch name on the remote to update the existing update branch from.

Typically this should be the same as the target branch for pull requests. Used when git.update.baseMerge.enable is true and the update branch exists.

Type: string

Default:

git.update.baseBranch

Declared by:

git-auth

git.update.baseMerge.method

How to update an existing update branch with changes from the base branch.

"merge": Create a merge commit, preserving both branch histories. Safe but creates additional merge commits in the update branch.
"rebase": Rebase existing update branch commits onto the current base branch. Creates a linear history but rewrites commit hashes (requires force push).
"fast-forward": Only proceed if the update branch can fast-forward to the base branch. Fails if the update branch has any commits not present in the base branch. This is the most conservative option, preventing complex merge scenarios.
"reset": Always discard the existing update branch and start fresh from the base branch. This treats the update branch as fully regeneratable from the update script. Useful for automated updates (like flake.lock) where the update script output is deterministic and conflicts should be resolved by regenerating. Any manual changes to the update branch will be lost.