actions-runner-controller

A Kubernetes controller for managing self-hosted GitHub Actions runners at scale. This project automates the deployment, scaling, and management of GitHub Actions runners on your Kubernetes cluster, making CI/CD workflows more efficient, secure, and customizable.

Features

• Automated Runner Provisioning: Dynamically launches and terminates self-hosted runners as needed.
• Runner Autoscaling: Scales runners up or down based on job demand or custom metrics.
• Multi-Repository Support: Supports runners for multiple GitHub repositories, organizations, or enterprises.
• Secure by Design: Leverages Kubernetes RBAC and secrets to keep sensitive data safe.
• Custom Runner Images: Use your own container images for specialized build environments.
• Management API: Integrates with GitHub’s REST API for seamless runner registration and deregistration.

Prerequisites

• Kubernetes cluster (>=1.22 recommended)
• kubectl configured for your cluster
• GitHub Personal Access Token with repo and admin:org scopes
• Helm (optional, for easier installation)

Installation

1. Clone the repository

git clone https://github.com/nodoubtz/actions-runner-controller.git
cd actions-runner-controller

2. Install CRDs

kubectl apply -f config/crd/

3. Deploy the Controller

kubectl apply -f config/deploy/

Or use Helm:

helm repo add arc https://nodoubtz.github.io/actions-runner-controller/
helm install actions-runner-controller arc/actions-runner-controller

Getting Started

1. Create a RunnerDeployment

Create a RunnerDeployment YAML manifest:

apiVersion: actions.summerwind.dev/v1alpha1
kind: RunnerDeployment
metadata:
  name: example-runner-deployment
spec:
  replicas: 2
  template:
    spec:
      repository: nodoubtz/actions-runner-controller
      image: summerwind/actions-runner:latest
      env: []

Apply it:

kubectl apply -f runner-deployment.yaml

2. Monitor Runners

Check runner pods:

kubectl get pods -l app=actions-runner-controller
kubectl get runners

Configuration

• GitHub Token: Store your token as a Kubernetes Secret and reference it in your runner spec.
• Custom Runner Images: Specify the image field in the runner spec.
• Scaling: Adjust the replicas field or use the HPA integration.

See docs/ for more advanced configuration options.

Security

• Runners are isolated in Kubernetes pods.
• Sensitive tokens and secrets are mounted via Kubernetes Secrets.
• RBAC is enforced for all controller operations.

Contributing

1. Fork the repo
2. Create your feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -am 'Add new feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

License

MIT

---

References:

• GitHub Actions Documentation
• Kubernetes Documentation