Skip to content

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

  1. Navigate to your Cluster
    From the KubeDNA Home Page, select the cluster where you want to install a GitHub Runner.
  2. Go to CI/CD and click “Add GitHub.”
    This will open the “Create GitHub Runner” form (similar to the screenshot).
  3. Select the Architecture
    Choose either x86 or arm.
  4. Choose the Machine Type
    Select a machine type based on your preferred data center or compute size.
  5. Enter your GitHub Registration Token
  6. To get your GitHub runner registration token:
    1. Go to your GitHub repository (or organization) → Settings → Actions → Runners.
    2. Click New self-hosted runner → Choose Linux → Copy the registration token shown in Step 2 of GitHub’s instructions.
  7. Organization/Repository
  8. If you’re adding the runner at the repository level, enter your-username/your-repo-name.
  9. If you’re adding it at the organization level, just enter the organization name (e.g., your-org).
  10. Runner Group (Optional)
  11. Only relevant if you’re configuring an organization-wide runner and want to place it in a specific group.
  12. Labels
  13. By default, KubeDNA will generate a label like kubedna-<clustername>-<architecture>. You can override or add more labels if you like.
  14. Click “Save.”
    KubeDNA will then spin up a new resource in your environment that configures a GitHub Runner named kubedna-<clustername>-<architecture>.
  15. 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.

  1. Download the Kubeconfig from KubeDNA
  2. Go to Access & Security in your KubeDNA dashboard.
  3. Click Download to get the kubeconfig file.
  4. Add a GitHub Actions Secret
  5. In your GitHub repository, navigate to Settings → Security → Secrets and variables → Actions.
  6. Click New repository secret (or New organization secret if using an org runner).
  7. Name the secret (e.g., KUBECONFIG).
  8. Paste the contents of your kubeconfig file into the Secret value.
  9. 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

  1. Commit and push your .github/workflows/deploy.yml (and the deployment/ folder) to the main branch.
  2. Go to your GitHub repository → Actions tab.
  3. You should see the Deploy workflow listed.
  4. 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.