Docs

GitHub Action

Description

Updatecli is most effective when executed regularly and automatically. So, lets see how to use updatecli in a GitHub Action.

Credentials

Updatecli requires a token to interact with the GitHub API. It can be done using different approaches.

GITHUB_TOKEN

The easiest one is the GITHUB_TOKEN which comes with two major limitations:

  1. For security reason, GitHub prevents to trigger GitHub action workflow from pullrequest created with a GITHUB_TOKEN, more information here. This means that a pullrequest recreated this way won’t trigger any test.

  2. GITHUB_TOKEN has the lower API request limit 1000 requests per hour as explained here

Important
By default the GITHUB_TOKEN is not allowed to open pullrequest. You first need to configure the default GITHUB_TOKEN permission for your repository. More information here

Personal Access Token

The second approach is to configure a GitHub action secret with a personal access token that allow 5000 request per hour src.

GitHub App

The third approach is to use a GitHub App that provides the highest api limit, 15000 request per hour here.

Conclusion

The third option is the best one but not yet supported natively by Updatecli. An issue is open at issue#2262. A workaround is available by using the GitHub action actions/create-github-app-token.

Migration

Important
The v1 and v2 branches of the action are deprecated and will be removed. Use v3 or later.

From v2 to v3

Pin the action to a current release, for example updatecli/updatecli-action@v3.4.0. The inputs are unchanged, so no other edit is needed.

From v1 to v2

The action v1 was a GitHub Action of type docker. While it was easier to start with, that type of action runs inside a container, in a fully isolated environment. Updatecli shells out to many other tools, so switching to a JavaScript action allows installing Updatecli directly on the runner, next to those tools. From v2 onwards the purpose of the action is to install Updatecli, not to run it (running it is a separate run: step, as in the example below).

Parameter

Version

version: the Updatecli version to install. Accepts any released tag, such as v0.119.0. Defaults to the latest Updatecli release.

Required: false

Example

This example is modelled on the jenkins-infra/jenkins-infra repository.

Once your update strategy lives in ./updatecli/updatecli.d, two more files are needed to run Updatecli from GitHub Actions.

Values file

The values file holds the settings that change between environments, so the manifests themselves stay generic.

updatecli/values.yaml
---
github:
  user: "GitHub Actions Bot"
  email: "bots@updatecli.io"
  username: "github-actions"
  token: "UPDATECLI_GITHUB_TOKEN"

These keys are not read by Updatecli directly: they are made available to the manifests, which reference them with Go templating. A manifest declaring a github scm consumes them like this:

scms:
  default:
    kind: github
    spec:
      user: '{{ .github.user }}'
      email: '{{ .github.email }}'
      username: '{{ .github.username }}'
      token: '{{ requiredEnv .github.token }}'
      owner: updatecli
      repository: website
      branch: main
Note
token holds the name of an environment variable, not the token itself. requiredEnv resolves it at run time and fails the pipeline if the variable is unset, which keeps the secret out of the repository. See "Configuration" page for the full templating reference.

Pass the file with --values, as the workflow below does. Any key your manifests do not reference can be dropped.

Workflow

github/workflows/updatecli.yaml
name: Updatecli

on:
  # Trigger Updatecli if a new commit land on the main branch
  push:
    branches: [main]
  # Trigger Updatecli if a pullrequest is open targeting the main branch.
  # This is useful to test Updatecli manifest change
  pull_request:
    branches: [main]
  # Manually trigger Updatecli via GitHub UI
  workflow_dispatch:
  # Trigger Updatecli once day by a cronjob
  schedule:
    # * is a special character in YAML so you have to quote this string
    # Run once a day
    - cron: "0 0 * * *"

permissions:
  # Required by Updatecli to create Git Commit(s)
  contents: "write"
  # Required by Updatecli to open GitHub pull request
  pull-requests: "write"
  # Required by Updatecli to update GitHub action workflows
  actions: "write"

jobs:
  updatecli:
    runs-on: "ubuntu-latest"
    steps:
      - name: Checkout
        uses: actions/checkout@v7.0.1

      - name: Install Updatecli in the runner
        uses: updatecli/updatecli-action@v3.4.0

      - name: Run Updatecli in Dry Run mode
        run: "updatecli diff --config ./updatecli/updatecli.d --values updatecli/values.yaml"
        env:
          UPDATECLI_GITHUB_USERNAME: "${{ github.actor }}"
          UPDATECLI_GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

      - name: Run Updatecli in apply mode
        run: "updatecli apply --config ./updatecli/updatecli.d --values updatecli/values.yaml"
        env:
          UPDATECLI_GITHUB_USERNAME: "${{ github.actor }}"
          UPDATECLI_GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
Important
Environment variables starting with GITHUB_ are reserved by GitHub Actions, which is why Updatecli reads UPDATECLI_GITHUB_TOKEN and UPDATECLI_GITHUB_USERNAME instead.
Last updated on July 30, 2026
Prev
Automate with Jenkins
Next
ArgoCD