Github Action

“actions” defines the composite action name patterns the crawler searches for.

default:

actions:
  - "*"

remark:

• a composite action is identified by an “action.yaml” or “action.yml” file, and the pattern is matched against the name of the directory holding it.

“age” defines the minimum or maximum age of a release, tag, or branch to be considered valid.

It is the “dependency cooldown” setting: setting “minimum” keeps Updatecli from suggesting a version that has just been published.

default: empty, no age filtering.

remark:

• it accepts a duration string, such as “24h”, “7d”, “3w” or “1y”.
• the age filter is not applied to the Docker images referenced by a workflow.

example:

autodiscovery:
  crawlers:
    github/action:
      age:
        minimum: '7d'

“maximum” defines the maximum age a release may have to be considered.

remark:

• accepted units are “d” for days, “w” for weeks, “mo” for months and “y” for years, plus the Go duration units such as “h”, “m” and “s”.
• a unit is required.
• a month counts as 1/12 of a year and a year as 365 days.

example:

• maximum: 6mo
• maximum: 1y

“minimum” defines the minimum age a release must have to be considered.

remark:

• accepted units are “d” for days, “w” for weeks, “mo” for months and “y” for years, plus the Go duration units such as “h”, “m” and “s”.
• a unit is required.
• a month counts as 1/12 of a year and a year as 365 days.

example:

• minimum: 24h
• minimum: 7d
• minimum: 3w

“credentials” defines the credentials used to authenticate with each git provider, keyed by git provider domain.

remark:

• without an entry, “gitea.com”, “codeberg.org” and “code.forgejo.org” use kind “gitea”, and any other domain uses kind “github” with the “github.com” credentials.

example:

autodiscovery:
  crawlers:
    github/action:
      credentials:
        "code.forgejo.com":
          kind: gitea
          token: xxx
        "github.com":
          kind: github
          token: '{{ requiredEnv "GITHUB_TOKEN" }}'

“expirationtime” defines the lifetime of the GitHub App token, in seconds.

default: 3600

remark:

• the token is used during the whole Updatecli run, so it must stay valid until the run ends.
• the minimum value is 600.

“installationid” defines the GitHub App installation ID.

remark:

• the value must be an integer.
• it is the ID shown in the URL https://github.com/settings/installation/

“privatekey” defines the PEM encoded private key of the GitHub App.

remark:

• “privatekey” or “privatekeypath” is required.
• when both are set, “privatekey” takes precedence.
• prefer “privatekeypath”, to keep sensitive information out of the manifest.

“privatekeypath” defines the path to a file holding the PEM encoded private key of the GitHub App.

remark:

• “privatekey” or “privatekeypath” is required.
• when both are set, “privatekey” takes precedence.
• setting the value from an environment variable keeps sensitive information out of the manifest.

example:

• privatekeypath: ‘{{ requiredEnv “GITHUB_APP_PRIVATE_KEY_PATH” }}’

“credentialsdocker” defines the registry credentials used for Docker images, keyed by registry host without scheme.

remark:

• when empty, Updatecli uses the local OCI credentials, such as the Docker ones.

example:

credentialsdocker:
  "ghcr.io":
    token: "xxx"
  "index.docker.io":
    username: "admin"
    password: "password"

“password” defines the container registry password used for authentication.

default: credentials are retrieved from the local environment, such as ~/.docker/config.json.

remark:

• “password” requires “username”.
• “token” cannot be combined with both “username” and “password”.

“token” defines the container registry bearer token used for authentication.

default: credentials are retrieved from the local environment, such as ~/.docker/config.json.

remark:

• “token” cannot be combined with both “username” and “password”.

“username” defines the container registry username used for authentication.

default: credentials are retrieved from the local environment, such as ~/.docker/config.json.

remark:

• “username” requires “password”.
• “token” cannot be combined with both “username” and “password”.

“digest” defines whether the generated manifests pin the digest instead of the branch or tag.

default: true

remark:

• digest pinning is supported for GitHub actions and Docker images, not yet for Gitea and Forgejo actions.
• when false, actions referenced by “main”, “master” or “latest” are skipped.

“files” defines the workflow file name patterns the crawler searches for.

default:

files:
  - "*.yaml"
  - "*.yml"

remark:

• the pattern is matched against the file name only, not against its path, so a pattern such as “.github/workflows/*.yaml” never matches.
• a workflow file must sit directly inside a “workflows” directory whose parent is “.github”, “.gitea”, or “.forgejo”.

“ignore” defines rules to exclude matching actions or Docker images from the autodiscovery.

remark:

• an action or Docker image is ignored when it matches at least one rule.

“actions” defines the actions and Docker images to match, keyed by name.

remark:

• for an action, the key is the action name, such as “actions/checkout”.
• for a Docker image, the key is the image reference as written in the workflow, tag included, such as “docker://alpine:3.18” for a step or “alpine:3.18” for a job container.
• an empty value matches any version.
• otherwise the value is a semantic version constraint, such as “>=1.0.0”.
• when the version or the constraint cannot be parsed, the value must equal the reference, such as a git branch, a git tag, or a Docker image tag.

“path” defines a workflow or composite action file path pattern.

remark:

• the pattern must match the whole path, not just a substring.
• the pattern follows the Go filepath.Match syntax, such as “*” or “?”.

“only” defines rules to restrict the autodiscovery to matching actions or Docker images.

remark:

• an action or Docker image is kept only when it matches at least one rule.

“actions” defines the actions and Docker images to match, keyed by name.

remark:

• for an action, the key is the action name, such as “actions/checkout”.
• for a Docker image, the key is the image reference as written in the workflow, tag included, such as “docker://alpine:3.18” for a step or “alpine:3.18” for a job container.
• an empty value matches any version.
• otherwise the value is a semantic version constraint, such as “>=1.0.0”.
• when the version or the constraint cannot be parsed, the value must equal the reference, such as a git branch, a git tag, or a Docker image tag.

“path” defines a workflow or composite action file path pattern.

remark:

• the pattern must match the whole path, not just a substring.
• the pattern follows the Go filepath.Match syntax, such as “*” or “?”.

“rootdir” defines the directory where the crawler starts searching for workflow files and composite actions.

default: the scm directory when “scmid” is set, otherwise the directory relative paths resolve from, by default the working directory.

remark:

• a relative path is resolved from the default directory.
• an absolute path is used as is, instead of the scm directory.

“versionfilter” defines the version filter used by the generated manifests.

default:

• for an action, kind “semver” with pattern “*”, the latest version, when its reference is a semantic version, otherwise kind “latest”.
• for a Docker image, kind “semver” with pattern “>=”, combined with a tag filter derived from the current tag.

remark:

• with kind “semver”, “pattern” accepts:
  • “prerelease”: the latest prerelease of the current version.
  • “patch”: patch updates only.
  • “minor”: patch and minor updates.
  • “minoronly”: minor updates only.
  • “major”: patch, minor and major updates.
  • “majoronly”: major updates only.
  • a version constraint, such as “>= 1.0.0”.
• with kind “regex”, “pattern” accepts a regular expression.
• more examples at https://www.updatecli.io/docs/core/versionfilter/

example:

versionfilter:
  kind: semver
  pattern: minor

“kind” defines the versioning scheme used to select a version.

default: latest

remark:

• accepted values are “latest”, “semver”, “regex”, “regex/semver”, “time”, “regex/time”, “lex” and “pep440”.
• “latest” returns the last version of the list.
• “lex” sorts the versions lexicographically and returns the last one.
• “pep440” follows https://peps.python.org/pep-0440/

example:

• kind: semver

“pattern” defines the version pattern, according to “kind”.

default:

• latest: “latest”
• semver and pep440: “*”
• regex: “.*”
• time and regex/time: “2006-01-02”

remark:

• for “latest”, “latest” returns the last version, any other value must match a version exactly.
• for “semver” and “regex/semver”, it is a semantic versioning constraint.
• for “pep440”, it is a pep440 version specifier.
• for “regex”, it is a regular expression.
• for “time” and “regex/time”, it is a Go date layout.
• ignored by “lex”.

example:

• pattern: ~1.2
• pattern: “>=1.0.0 <2.0.0”
• pattern: ^v\d+.\d+.\d+$

“regex” defines the regular expression extracting the version from each entry.

remark:

• only used by the kinds “regex/semver” and “regex/time”.
• the value of the first capture group is used as the version.

example:

• regex: ^v(\d+.\d+.\d+)$

“replaceall” applies a regular expression replacement to each version before filtering.

remark:

• only used by the kinds “regex”, “regex/semver” and “regex/time”.
• the replacement runs before “pattern” or “regex” is evaluated.

example:

replaceall:
  pattern: "_"
  replacement: "."

turns “curl-8_15_0” into “curl-8.15.0”.

“pattern” defines the regular expression matching the text to replace.

example:

• pattern: “_”

“replacement” defines the text replacing each match of “pattern”.

remark:

• capture groups can be referenced with $1, $2, and so on.

example:

• replacement: “.”

“strict” enforces strict semantic versioning rules when parsing versions.

default: false

remark:

• only used by the kinds “semver” and “regex/semver”.