Workflow Setup Kubectl

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

Step	Action	Description
Checkout Repo	`actions/checkout@v4`	Clones your repository to the runner.
Install kubectl CLI	`azure/setup-kubectl@v3`	Installs a specific version of `kubectl`.
Fetch Kubernetes Cluster Details	`kubectl version --short`	Validates 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.

Introduction

GitHub Actions - Core Concepts

Continuous Integration with GitHub Actions

Continuous Deployment with GitHub Actions

Reusable Workflows and Reporting

Custom Actions

Self Hosted Runner

Security Guide

GitHub Actions in the Enterprise Cloud

Workflow Setup Kubectl

1. Current Workflow Overview

2. Adding the `dev-deploy` Job

3. Installing the `kubectl` CLI

4. Fetching Kubernetes Cluster Details

5. Full `dev-deploy` Job Snippet

5.1 Step-by-Step Summary

6. Workflow Execution

7. Troubleshooting Connection Errors

Example `kubeconfig`

Links and References

Watch Video

​1. Current Workflow Overview

​2. Adding the dev-deploy Job

​3. Installing the kubectl CLI

​4. Fetching Kubernetes Cluster Details

​5. Full dev-deploy Job Snippet

​5.1 Step-by-Step Summary

​6. Workflow Execution

​7. Troubleshooting Connection Errors

​Example kubeconfig

​Links and References

Watch Video

1. Current Workflow Overview

2. Adding the `dev-deploy` Job

3. Installing the `kubectl` CLI

4. Fetching Kubernetes Cluster Details

5. Full `dev-deploy` Job Snippet

5.1 Step-by-Step Summary

6. Workflow Execution

7. Troubleshooting Connection Errors

Example `kubeconfig`

Links and References