Home

Awesome

OpenShift Tools Installer Action

CI Checks Install from Mirror Example Install from GitHub Example Link checker

tag badge license badge

openshift-tools-installer is a GitHub Action that downloads, installs and caches OpenShift and Kubernetes related CLI tools from the OpenShift Mirror or from GitHub Releases, allowing you to easily use these tools in your Action workflows.

<a id="supported-tools"></a>

Supported Tools

Below is the list of supported tools that can be installed from the OpenShift Mirror or from GitHub.

NameDescriptionOpenShift MirrorGitHubSupported OS
crcCodeReady Containers✔️ crcLinux & Windows
crdaCodeReady Dependency Analytics✔️ fabric8-analytics/cli-toolsAll
helmHelm✔️ helmAll
kamGitOps Application Manager✔️ kam✔️ redhat-developer/kamAll
kamelCamel K✔️ camel-k✔️ apache/camel-kAll
knKnative Client✔️ serverless✔️ knative/clientAll
kustomizeKustomize✔️ kubernetes-sigs/kustomizeAll
ocOpenShift Client✔️ v3 and ocp (v4)All
odoOpenShift Do✔️ odoAll
openshift-installOpenShift Installer✔️ ocpLinux & macOS
operator-sdkOperator SDK✔️ operator-sdk ✔️ operator-framework/operator-sdkLinux & macOS
opmOperator Package Manager✔️ ocp✔️ operator-framework/operator-registryAll*️
s2iSource to Image✔️ openshift/source-to-imageAll
tknTekton Pipelines Client✔️ pipeline✔️ tektoncd/cliAll
yqyq✔️ mikefarah/yqAll
chart-verifierChart Verifier✔️ redhat-certification/chart-verifierLinux
koko✔️ google/koAll
preflightpreflight✔️ redhat-openshift-ecosystem/openshift-preflightLinux

*️ For Mirror: OPM versions less than 4.6.17 are only available for Linux.<br> For GitHub: OPM versions less than 1.15.1 are only available for Linux. <br> Note that OPM versions on the OpenShift Mirror are versioned by the OCP version, not the OPM executable version. <br> Note that the chart verifier binaries are only available starting with version 1.4.1

Inputs

<!-- markdown-link-check-disable -->
InputDescriptionDefault
sourceSource from which to download all tools in the step. Can be github or mirror. If you want to download tools from both sources, use two steps.mirror
github_patGitHub personal access token. This is required if the source input is github. It can be a personal access token, but it is easiest to use the built-in ${{ github.token }} or ${{ secrets.GITHUB_TOKEN }}. See GitHub docs for details about the built-in token.${{ github.token }}
skip_cacheSet to true to skip caching of the downloaded executables. This will also skip fetching previously cached executables.false
<!-- markdown-link-check-disable -->

The other inputs are just the names of the supported tools, exactly as listed above. The value for each input is a semantic version or range for that tool. If the version given is a range, this action will install the maximum version that satisfies the range.

Version numbers must be quoted, so the yaml parser interprets them as strings.

The version can also be "*", or "latest", which are the same. This installs the latest release that is available on the selected source.

For a list of available versions of a given tool, follow the links in the Supported Tools table for the selected source, and look at the versions available.

If an invalid version is specified, the action will not proceed with any installations.

If the requested version is valid but not available on the mirror, the action fails, but any tools that were found will still be installed and cached.

Example

Here is an workflow step demonstrating some example version inputs.

Also see the OpenShift Mirror example workflow, and the GitHub example workflow.

Refer to the semver documentation. The action uses the semver package, so all syntax is supported.

steps:
  - name: Install CLI tools from OpenShift Mirror
    uses: redhat-actions/openshift-tools-installer@v1
    with:

      # "mirror" is the default source, so this is optional.
      source: "mirror"

      # Installs the latest kam release.
      kam: "latest"

      # Installs the latest release of oc with the major version 3.
      # This is equivalent to "3.x" or "^3".
      oc: "3"

      # Installs the latest release of odo with the major version 2, and the minor version 0.
      # This would install odo 2.0.3, but not odo 2.1.0.
      odo: "2.0"

      # This exact version will install version 0.11.0 of Tekton, no other version.
      tkn: "0.11.0"

  - name: Install CLI tools from GitHub
    uses: redhat-actions/openshift-tools-installer@v1
    with:
      # Search through these projects' GitHub releases, instead of the OpenShift Mirror.
      # https://docs.github.com/en/actions/reference/authentication-in-a-workflow
      source: "github"

      # Using GitHub token from the github context
      github_pat: ${{ github.token }}

      kam: "latest"
      s2i: "1.2"
      tkn: "0.17"

Outputs

The action has one output called installed, which is a JSON object that maps tool names (as above) to an object describing the version that was installed.

For example, after installing oc with the version range "4.3", the output object contains:

{
    // ... other items omitted
    oc: {
        fromCache: true,
        installedPath: "/home/runner/work/_temp/openshift-bin/oc",
        url: "https://mirror.openshift.com/pub/openshift-v4/clients/ocp/4.3.40/openshift-client-linux-4.3.40.tar.gz",
        version: "4.3.40"
    }
}

If a CLI was not installed due to an error, it will be absent from this object. Check the action output and workflow summary for the error.

Caching

The executables are cached after being download and extracted. The cache key is determined by the source, the tool name, and the actual version that was downloaded - not the range that was input.

This means that if a new version is released that satisfies the version range, the cached old version will be bypassed in favour of the new version which is then cached. The upgrade is done for you, so long as the version range allows it.

See the actions/cache repository for cache limits.

The cache can be disabled for the current action run by setting the skip_cache input to true.

Caching on GHES

The Actions cache is not supported on GitHub Enterprise Server, as per this issue.

The cache is disabled in this action if you are using GitHub Enterprise Server.

Troubleshooting

<!-- markdown-link-check-disable-next-line -->
  - run: |
    apk add gcompat