Github Runners: Step by step guide
What to Do
To integrate Github with your Kubernetes cluster using KubeDNA, follow these steps:
Configure a GitLab runner in your environment.
Configure kubeconfig in your GitLab environment variables.
Configure a GitHub Runner in KubeDNA
Navigate to your Cluster
From the KubeDNA Home Page, select the cluster where you want to install a GitHub Runner.Go to CI/CD and click “Add GitHub.”
This will open the “Create GitHub Runner” form (similar to the screenshot).Select the Architecture
Choose either x86 or arm.Choose the Machine Type
Select a machine type based on your preferred data center or compute size.Enter your GitHub Registration Token
To get your GitHub runner registration token:
Go to your GitHub repository (or organization) → Settings → Actions → Runners.
Click New self-hosted runner → Choose Linux → Copy the registration token shown in Step 2 of GitHub’s instructions.
Organization/Repository
If you’re adding the runner at the repository level, enter
your-username/your-repo-name
.If you’re adding it at the organization level, just enter the organization name (e.g.,
your-org
).
Runner Group (Optional)
Only relevant if you’re configuring an organization-wide runner and want to place it in a specific group.
Labels
By default, KubeDNA will generate a label like
kubedna-<clustername>-<architecture>
. You can override or add more labels if you like.
Click “Save.”
KubeDNA will then spin up a new resource in your environment that configures a GitHub Runner namedkubedna-<clustername>-<architecture>
.This label will also appear by default in your GitHub repository or organization settings under Actions → Runners.
Once this is done, your KubeDNA-managed runner will automatically register itself with GitHub and be available to run Actions jobs.
Configure Kubeconfig as a GitHub Secret
To allow your GitHub Actions to interact with your Kubernetes cluster, you need to store the kubeconfig as a secret in GitHub.
Download the Kubeconfig from KubeDNA
Go to Access & Security in your KubeDNA dashboard.
Click Download to get the kubeconfig file.
Add a GitHub Actions Secret
In your GitHub repository, navigate to Settings → Security → Secrets and variables → Actions.
Click New repository secret (or New organization secret if using an org runner).
Name the secret (e.g.,
KUBECONFIG
).Paste the contents of your kubeconfig file into the Secret value.
Click Save.
Now you have a KUBECONFIG
secret that can be referenced in your GitHub Actions workflow.
Example GitHub Actions Workflow
Below is a minimal example of a .github/workflows/deploy.yml
file that uses your new self-hosted runner and the kubeconfig secret to deploy to your cluster. Adjust names, paths, and commands as needed.
name: Deploy to Kubernetes
on:
push:
branches:
- main
jobs:
deploy:
name: Deploy
runs-on: self-hosted
# Make sure this label matches what KubeDNA created for your runner
# (e.g., kubedna-mycluster-x86)
labels:
- kubedna-mycluster-x86
steps:
- name: Check out repository
uses: actions/checkout@v3
- name: Set up Kubeconfig
# Write the kubeconfig secret to a file
run: echo "$KUBECONFIG" > kubeconfig.yml
env:
KUBECONFIG: ${{ secrets.KUBECONFIG }}
- name: Install kubectl
run: |
apt-get update && \
apt-get install -y ca-certificates curl && \
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" && \
install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
- name: Deploy to cluster
run: |
export KUBECONFIG=$GITHUB_WORKSPACE/kubeconfig.yml
kubectl apply -f deployment/
Directory Structure
Make sure you have a deployment/
folder with your Kubernetes YAML manifests inside (e.g., deployment.yml
, service.yml
, ingress.yml
) similar to:
deployment/
├─ deployment.yml
├─ service.yml
└─ ingress.yml
.github/
└─ workflows/
└─ deploy.yml
Triggering Your First Deployment
Commit and push your
.github/workflows/deploy.yml
(and thedeployment/
folder) to themain
branch.Go to your GitHub repository → Actions tab.
You should see the Deploy workflow listed.
If everything is configured correctly, the job will pick up the self-hosted runner spun up by KubeDNA and run your deployment steps.
You’re all set! This setup will allow your GitHub Actions to communicate with your Kubernetes cluster, using a self-hosted runner automatically managed by KubeDNA.