Github Search

kind: githubsearch

Description

The GitHub Search SCM block allows you to interact with multiple GitHub repositories — either by fetching files or by pushing updates to them.

condition

When used in a condition, the SCM block typically fetches files or metadata from the specified repository

target

When used in a target, the SCM block usually pushes changes to that repository.

By default, the GitHub Search SCM uses the standard GitHub workflow: it creates a temporary branch, commits the changes, and opens a pull request targeting the branch defined in the configuration.

Parameters

NameTypeDescriptionRequired

Authentication

Updatecli supports multiple authentication methods for interacting with GitHub. You can authenticate using either a Personal Access Token (PAT) or a GitHub App. Below are the supported methods, in order of precedence.

1. GitHub App Authentication via Environment Variables

Set the following environment variables to enable GitHub App authentication:

  • UPDATECLI_GITHUB_APP_CLIENT_ID: Your GitHub App’s Client ID

  • UPDATECLI_GITHUB_APP_PRIVATE_KEY: The private key for your GitHub App (PEM format, as a string)

  • UPDATECLI_GITHUB_APP_PRIVATE_KEY_PATH: The path to your GitHub App’s private key file (PEM format)

  • UPDATECLI_GITHUB_APP_INSTALLATION_ID: The installation ID for your GitHub App

You can use either UPDATECLI_GITHUB_APP_PRIVATE_KEY or UPDATECLI_GITHUB_APP_PRIVATE_KEY_PATH to provide the private key.

Example using the private key content:

export UPDATECLI_GITHUB_APP_CLIENT_ID="123456"
export UPDATECLI_GITHUB_APP_PRIVATE_KEY="$(cat /path/to/private-key.pem)"
export UPDATECLI_GITHUB_APP_INSTALLATION_ID="789012"

Example using the private key path:

export UPDATECLI_GITHUB_APP_CLIENT_ID="123456"
export UPDATECLI_GITHUB_APP_PRIVATE_KEY_PATH="/path/to/private-key.pem"
export UPDATECLI_GITHUB_APP_INSTALLATION_ID="789012"
Note

When these variables are set, Updatecli will use GitHub App authentication for all GitHub operations.

2. Personal Access Token via Environment Variable

Set the following environment variable to use a Personal Access Token:

  • UPDATECLI_GITHUB_TOKEN: Your GitHub Personal Access Token

Example:

export UPDATECLI_GITHUB_TOKEN="ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXX"

3. Personal Access Token via Manifest

You can specify your Personal Access Token directly in your Updatecli manifest under the spec.token field:

scms:
  default:
    kind: github
    spec:
      owner: myorg
      repository: myrepo
      token: "{{ requiredEnv `GITHUB_TOKEN` }}"
Warning

For security reasons, it is recommended to use environment variables or secret management tools (like SOPS) instead of hardcoding tokens in your manifest.

4. GitHub App Authentication via Manifest

You can configure GitHub App authentication directly in your manifest using the spec.app field:

scms:
  default:
    kind: github
    spec:
      owner: myorg
      repository: myrepo
      app:
        clientID: "123456"
        privateKey: "{{ requiredEnv `GITHUB_APP_PRIVATE_KEY` }}"
        installationID: "789012"

Or, if you prefer to reference a private key file:

scms:
  default:
    kind: github
    spec:
      owner: myorg
      repository: myrepo
      app:
        clientID: "123456"
        privateKeyPath: "/path/to/private-key.pem"
        installationID: "789012"

Precedence and Fallback

Updatecli will use the first valid authentication method it finds, in the following order:

  1. Personal Access Token via environment variable

  2. GitHub App via environment variables

  3. Personal Access Token via manifest

  4. GitHub App via manifest

If no valid authentication is found, Updatecli will fail with an error.

Further Reading

Tip: For best security and maintainability, prefer using a GitHub App or environment variables for authentication, and avoid hardcoding secrets in your manifests.

CommitMessage

Updatecli uses conventional commits as describe on www.conventionnalcommits.org.
The goal is to add human and machine readable meaning to commit messages

By default, Updatecli generates a commit message using the default type "chore" and split long title message into the body like:

Author: olblak <updatecli@updatecli.io>
Date:   Tue May 4 15:41:44 2021 +0200

    chore: Update key "dependencies[0].version" from file "charts/jenkins/r...

    ... equirements.yaml"

    Made with ❤️️  by updatecli

Example

This pipeline automatically updates the Golang version across multiple GitHub repositories within the MyOrg organization. Using the githubsearch SCM, it discovers repositories that match specific branch patterns (e.g., main or v2) and identifies where Golang versions are defined — such as in Go modules, Dockerfiles, or GitHub Actions workflows.

Updatecli then retrieves the latest matching Golang version (for example, any 1.24.x release) and opens pull requests that update these files accordingly. It will create one pull request on a temporary branch, following the GitHub workflow, and includes a consistent commit message and label for easy tracking and automated merging. It will squash all the changes into one commit.

# updatecli.yaml
name: "Updatecli Golang"
pipelineid: "golang/version"

scms:
  default:
    kind: githubsearch
    spec:
      search: "org:MyOrg"
      limit: 3
      branch: "^main$|^v2$"
      commitusingapi: true
      commitmessage:
        squash: true
        type: chore
        scope: deps
        title: "update Golang version"
      user: myGitCommitUsername
      email: myGitCommitEmail

actions:
  default:
    kind: github/pullrequest
    scmid: default
    spec:
      labels:
        - dependencies
      title: "update Golang version"
      usetitleforautomerge: true

autodiscovery:
  scmid: default
  actionid: default
  groupby: all
  crawlers:
    golang:
      onlygoversion: true
      versionfilter:
        kind: "semver"
        pattern: "1.24.x"
    dockerfile:
      digest: true
      only:
        - images:
            - "registry.suse.com/bci/golang"
      versionfilter:
        kind: semver
        pattern: "1.24.x"

sources:
  golang:
    name: Get the latest Golang version
    kind: golang
    spec:
      versionfilter:
        kind: semver
        pattern: "1.24.x"

targets:
  github-action:
    name: 'deps(github-action): Bump Golang version to {{ source "golang" }}'
    kind: yaml
    scmid: default
    spec:
      engine: yamlpath
      files:
        - ".github/workflows/*"
      key: '$.jobs.build.steps[?(@.uses =~ /^actions\/setup-go/)].with.go-version'
      searchpattern: true
Last modified on November 6, 2025
Edit this page on GitHub
← Docker Hub rate limit
Bitbucket Cloud →