azure/setup-kubectl

Install a specific version of kubectl on the runner.

Official actionCategory: Infrastructure & KubernetesLatest v5View on GitHub

What it does

azure/setup-kubectl installs the requested kubectl version on the runner so later steps can run kubectl commands against any cluster.

It only installs the binary, cluster credentials (kubeconfig) come from a separate step such as azure/aks-set-context, aws eks update-kubeconfig, or gcloud container clusters get-credentials.

Usage

workflow (.yml)

steps:
  - uses: azure/login@v2
    with:
      client-id: ${{ secrets.AZURE_CLIENT_ID }}
      tenant-id: ${{ secrets.AZURE_TENANT_ID }}
      subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
  - uses: azure/setup-kubectl@v5
    with:
      version: v1.30.0
  - run: |
      az aks get-credentials --resource-group my-rg --name my-cluster
      kubectl get pods

Inputs

Input	Description	Default	Required
`version`	Version of kubectl (latest or a semantic version like v1.30.0).	`latest`	Yes

Outputs

Output	Description
`kubectl-path`	Path to the cached kubectl binary.

Notes

Pin version to the minor version of your cluster (kubectl supports one minor version of skew in either direction) instead of latest.

Common errors

The connection to the server localhost:8080 was refused from kubectl means no kubeconfig was configured, the install succeeded, but you skipped the cluster-credentials step.
An invalid version string fails the download; use latest or a full semantic version like v1.30.0.

Security and pinning

Pin the action to a commit SHA and pin version for reproducible builds.
Prefer OIDC-based cloud logins (azure/login federated credentials, configure-aws-credentials role assumption) over long-lived kubeconfig files stored as secrets.

Alternatives and related

azure/setup-helmInstall a specific version of the Helm CLI on the runner. azure/loginLog in to Azure in a workflow, using OIDC federated credentials or a service principal. aws-actions/configure-aws-credentialsAuthenticate to AWS in a workflow, ideally by assuming a role with OIDC (no stored keys). google-github-actions/authAuthenticate to Google Cloud, ideally via keyless Workload Identity Federation.

Frequently asked questions

Does setup-kubectl connect me to my cluster?

No. It only installs the binary. Add a credentials step for your provider (aks-set-context / az aks get-credentials, aws eks update-kubeconfig, or gcloud get-credentials) before running kubectl.