# GitHub Action<no value>
// <!-- Required for asciidoctor -->
:toc:
// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
:toclevels: 4

== 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 https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow#triggering-a-workflow-from-a-workflow[**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 https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28#primary-rate-limit-for-github_token-in-github-actions[**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 https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#preventing-github-actions-from-creating-or-approving-pull-requests[**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 https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28#primary-rate-limit-for-authenticated-users[**src**].

**GitHub App**

The third approach is to use a GitHub App that provides the highest api limit, 15000 request per hour https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow#triggering-a-workflow-from-a-workflow[**here**].

**Conclusion**

The third option is the best one but not yet supported natively by Updatecli. An issue is open at https://github.com/updatecli/updatecli/issues/2262[**issue#2262**]. A workaround is available by using the GitHub action https://github.com/actions/create-github-app-token[**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 https://github.com/jenkins-infra/jenkins-infra[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
[source,yaml]
----
{{<include "assets/code_example/docs/automate/github_action/values.yaml">}}
----

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:

[source,yaml]
----
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 link:/docs/core/configuration/["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
[source,yaml]
----
{{<include "assets/code_example/docs/automate/github_action/updatecli.yaml">}}
----

IMPORTANT: Environment variables starting with `GITHUB_` are reserved by GitHub Actions, which
is why Updatecli reads `UPDATECLI_GITHUB_TOKEN` and `UPDATECLI_GITHUB_USERNAME` instead.