Skip to main content
In this guide, you’ll learn how to set up the kubectl CLI within your GitHub Actions workflow to deploy to Kubernetes. By the end, you’ll have a reusable dev-deploy job that checks out your repo, installs kubectl, verifies the cluster, and is ready for your deployment steps.

​
1. Current Workflow Overview

Below is the existing workflow trigger and environment setup. We trigger on pushes to main and feature branches, and we expose MongoDB credentials via environment variables. 
on:
  workflow_dispatch:
  push:
    branches:
      - main
      - 'feature/*'

env:
  MONGO_URI: "mongodb+srv://supercluster.d83jj.mongodb.net/superData"
  MONGO_USERNAME: ${{ vars.MONGO_USERNAME }}
  MONGO_PASSWORD: ${{ secrets.MONGO_PASSWORD }}

jobs:
  unit-testing: …
  code-coverage: …
  docker: …

​
2. Adding the dev-deploy Job

We’ll append a new job named dev-deploy. It runs after the docker job on ubuntu-latest and prepares kubectl for deployment in the Development namespace. 
jobs:
  dev-deploy:
    needs: docker
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repo
        uses: actions/checkout@v4

​
3. Installing the kubectl CLI

Instead of manually downloading binaries, leverage the verified [azure/setup-kubectl@v3] action from the GitHub Marketplace.
The image shows a GitHub Marketplace search results page for "kubectl," displaying various actions related to kubectl with their descriptions and star ratings.
      - name: Install kubectl CLI
        uses: azure/setup-kubectl@v3
        with:
          version: '1.26.0'
Using the official azure/setup-kubectl action ensures you get signed binaries and can pin a specific version for reproducible builds.

​
4. Fetching Kubernetes Cluster Details

After installing, verify connectivity by checking the client version and listing all nodes: 
      - name: Fetch Kubernetes Cluster Details
        run: |
          kubectl version --short
          echo "------------------------------------------"
          kubectl get nodes

​
5. Full dev-deploy Job Snippet

Here’s the complete YAML for the dev-deploy job: 
jobs:
  dev-deploy:
    needs: docker
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repo
        uses: actions/checkout@v4

      - name: Install kubectl CLI
        uses: azure/setup-kubectl@v3
        with:
          version: '1.26.0'

      - name: Fetch Kubernetes Cluster Details
        run: |
          kubectl version --short
          echo "------------------------------------------"
          kubectl get nodes

​
5.1 Step-by-Step Summary

StepActionDescription
Checkout Repoactions/checkout@v4Clones your repository to the runner.
Install kubectl CLIazure/setup-kubectl@v3Installs a specific version of kubectl.
Fetch Kubernetes Cluster Detailskubectl version --shortValidates CLI version and cluster connectivity.

​
6. Workflow Execution

When you push these changes, GitHub Actions will execute unit-testing, code-coverage, and docker first. Once they succeed, dev-deploy runs.
The image shows a GitHub Actions page for a project called "Solar System Workflow," displaying a list of workflow runs with their statuses and details.
The image shows a GitHub Actions workflow in progress, with steps for unit testing, code coverage, containerization, and deployment. The workflow is titled "installing kubectl" and includes a visual representation of the job sequence.

​
7. Troubleshooting Connection Errors

If you encounter: 
Error: Unable to connect to the server: dial tcp 127.0.0.1:6443: connect: connection refused
that indicates kubectl has no valid context because no kubeconfig is set.
You must provide a kubeconfig file via secrets or variables and configure it in your workflow. Without it, kubectl cannot authenticate to your cluster.

​
Example kubeconfig

cat ~/.kube/config

apiVersion: v1
kind: Config
preferences: {}
clusters:
- cluster:
    certificate-authority-data: LS0tL...
  name: my-cluster
contexts:
- context:
    cluster: my-cluster
    namespace: default
    user: my-cluster-admin
  name: my-cluster-ctx
current-context: my-cluster-ctx
users:
- name: my-cluster-admin
  user:
    token: YOUR_TOKEN_HERE
To integrate this in GitHub Actions, store the kubeconfig as a secret and load it before your kubectl steps.

Watch Video