{"id":50691208,"url":"https://github.com/vmvarela/terraform-github-actions-runner-scale-set","last_synced_at":"2026-06-09T03:03:00.887Z","repository":{"id":323154500,"uuid":"1085365834","full_name":"vmvarela/terraform-github-actions-runner-scale-set","owner":"vmvarela","description":"This Terraform module simplifies the deployment of self-hosted GitHub Actions runners on any Kubernetes cluster. It uses the official Actions Runner Controller (ARC) to create and manage auto-scaling runner sets.","archived":false,"fork":false,"pushed_at":"2025-12-08T21:28:58.000Z","size":31,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-02T01:38:58.350Z","etag":null,"topics":["actions-runner-controller","terraform-module"],"latest_commit_sha":null,"homepage":"https://registry.terraform.io/modules/vmvarela/actions-runner-scale-set/github/latest","language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vmvarela.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-29T00:09:36.000Z","updated_at":"2025-11-08T11:46:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vmvarela/terraform-github-actions-runner-scale-set","commit_stats":null,"previous_names":["vmvarela/terraform-github-actions-runner-scale-set"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/vmvarela/terraform-github-actions-runner-scale-set","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmvarela%2Fterraform-github-actions-runner-scale-set","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmvarela%2Fterraform-github-actions-runner-scale-set/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmvarela%2Fterraform-github-actions-runner-scale-set/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmvarela%2Fterraform-github-actions-runner-scale-set/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vmvarela","download_url":"https://codeload.github.com/vmvarela/terraform-github-actions-runner-scale-set/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vmvarela%2Fterraform-github-actions-runner-scale-set/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34089329,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actions-runner-controller","terraform-module"],"created_at":"2026-06-09T03:02:57.772Z","updated_at":"2026-06-09T03:03:00.878Z","avatar_url":"https://github.com/vmvarela.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub Actions Runner Scale Set on Kubernetes\n\nTerraform module that deploys self-hosted GitHub Actions runners on Kubernetes using the official [Actions Runner Controller (ARC)](https://github.com/actions/actions-runner-controller).\n\nThis module automates the deployment of:\n- **ARC Controller**: Manages the lifecycle of runner scale sets\n- **Runner Scale Sets**: Auto-scaling GitHub Actions runners\n- **Runner Groups**: Organized runner access control (optional)\n- **Authentication**: Support for both GitHub Apps and Personal Access Tokens\n\n## Features\n\n- ✅ Multiple scale sets with independent configurations\n- ✅ Auto-scaling runners (min/max configuration)\n- ✅ GitHub App or PAT authentication\n- ✅ Private container registry support\n- ✅ Runner group management with repository and workflow restrictions\n- ✅ Flexible runner image configuration\n- ✅ Container mode support (Docker-in-Docker or Kubernetes)\n- ✅ Automatic namespace creation\n\n## Usage\n\n### Basic Example\n\n```hcl\nmodule \"github_runners\" {\n  source  = \"path/to/module\"\n\n  github_org   = \"my-organization\"\n  github_token = var.github_token\n}\n```\n\n### Complete Example with Multiple Scale Sets\n\n```hcl\nmodule \"github_runners\" {\n  source = \"path/to/module\"\n\n  github_org   = \"my-organization\"\n  github_token = var.github_token\n\n  controller = {\n    name             = \"arc-controller\"\n    namespace        = \"arc-system\"\n    create_namespace = true\n    version          = \"0.13.0\"\n  }\n\n  scale_sets = {\n    \"default-runners\" = {\n      namespace           = \"arc-runners-default\"\n      create_namespace    = true\n      min_runners         = 1\n      max_runners         = 10\n      runner_image        = \"ghcr.io/actions/actions-runner:latest\"\n      container_mode      = \"dind\"\n      visibility          = \"all\"\n      create_runner_group = true\n    }\n\n    \"production-runners\" = {\n      namespace           = \"arc-runners-prod\"\n      create_namespace    = true\n      min_runners         = 2\n      max_runners         = 20\n      runner_group        = \"production\"\n      visibility          = \"selected\"\n      repositories        = [\"repo1\", \"repo2\"]\n      create_runner_group = true\n    }\n\n    \"ci-runners\" = {\n      namespace           = \"arc-runners-ci\"\n      create_namespace    = true\n      min_runners         = 3\n      max_runners         = 15\n      runner_group        = \"ci\"\n      visibility          = \"selected\"\n      workflows           = [\".github/workflows/ci.yml\"]\n      create_runner_group = true\n    }\n  }\n}\n```\n\n### GitHub App Authentication\n\n```hcl\nmodule \"github_runners\" {\n  source = \"path/to/module\"\n\n  github_org                 = \"my-organization\"\n  github_app_id              = 123456\n  github_app_installation_id = 789012\n  github_app_private_key     = file(\"${path.module}/github-app-key.pem\")\n}\n```\n\n### Private Container Registry\n\n```hcl\nmodule \"github_runners\" {\n  source = \"path/to/module\"\n\n  github_org   = \"my-organization\"\n  github_token = var.github_token\n\n  private_registry          = \"registry.example.com\"\n  private_registry_username = var.registry_username\n  private_registry_password = var.registry_password\n\n  scale_sets = {\n    \"custom-image-runners\" = {\n      runner_image = \"registry.example.com/custom/runner:latest\"\n    }\n  }\n}\n```\n\n## Requirements\n\n| Name | Version |\n|------|---------|\n| \u003ca name=\"requirement_terraform\"\u003e\u003c/a\u003e [terraform](#requirement\\_terraform) | \u003e= 1.0 |\n| \u003ca name=\"requirement_github\"\u003e\u003c/a\u003e [github](#requirement\\_github) | ~\u003e 6.0 |\n| \u003ca name=\"requirement_helm\"\u003e\u003c/a\u003e [helm](#requirement\\_helm) | ~\u003e 3.0 |\n| \u003ca name=\"requirement_kubernetes\"\u003e\u003c/a\u003e [kubernetes](#requirement\\_kubernetes) | ~\u003e 2.0 |\n\n## Providers\n\n| Name | Version |\n|------|---------|\n| \u003ca name=\"provider_github\"\u003e\u003c/a\u003e [github](#provider\\_github) | ~\u003e 6.0 |\n| \u003ca name=\"provider_helm\"\u003e\u003c/a\u003e [helm](#provider\\_helm) | ~\u003e 3.0 |\n| \u003ca name=\"provider_kubernetes\"\u003e\u003c/a\u003e [kubernetes](#provider\\_kubernetes) | ~\u003e 2.0 |\n\n## Resources\n\n| Name | Type |\n|------|------|\n| [github_actions_runner_group.this](https://registry.terraform.io/providers/integrations/github/latest/docs/resources/actions_runner_group) | resource |\n| [helm_release.controller](https://registry.terraform.io/providers/hashicorp/helm/latest/docs/resources/release) | resource |\n| [helm_release.scale_set](https://registry.terraform.io/providers/hashicorp/helm/latest/docs/resources/release) | resource |\n| [kubernetes_namespace.controller](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/resources/namespace) | resource |\n| [kubernetes_namespace.scale_set](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/resources/namespace) | resource |\n| [kubernetes_secret.github_creds](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/resources/secret) | resource |\n| [kubernetes_secret.private_registry_creds](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/resources/secret) | resource |\n| [github_repositories.all](https://registry.terraform.io/providers/integrations/github/latest/docs/data-sources/repositories) | data source |\n\n## Inputs\n\n| Name | Description | Type | Default | Required |\n|------|-------------|------|---------|:--------:|\n| \u003ca name=\"input_github_org\"\u003e\u003c/a\u003e [github\\_org](#input\\_github\\_org) | GitHub organization name | `string` | n/a | yes |\n| \u003ca name=\"input_controller\"\u003e\u003c/a\u003e [controller](#input\\_controller) | Controller configuration | \u003cpre\u003eobject({\u003cbr\u003e  name             = optional(string, \"arc\")\u003cbr\u003e  namespace        = optional(string, \"arc-systems\")\u003cbr\u003e  create_namespace = optional(bool, true)\u003cbr\u003e  version          = optional(string, \"0.13.0\")\u003cbr\u003e})\u003c/pre\u003e | \u003cpre\u003e{\u003cbr\u003e  \"name\": \"arc\",\u003cbr\u003e  \"namespace\": \"arc-systems\",\u003cbr\u003e  \"create_namespace\": true,\u003cbr\u003e  \"version\": \"0.13.0\"\u003cbr\u003e}\u003c/pre\u003e | no |\n| \u003ca name=\"input_scale_sets\"\u003e\u003c/a\u003e [scale\\_sets](#input\\_scale\\_sets) | Scale sets configuration (map) | \u003cpre\u003emap(object({\u003cbr\u003e  runner_group        = optional(string, null)\u003cbr\u003e  create_runner_group = optional(bool, true)\u003cbr\u003e  namespace           = optional(string, \"arc-runners\")\u003cbr\u003e  create_namespace    = optional(bool, true)\u003cbr\u003e  version             = optional(string, \"0.13.0\")\u003cbr\u003e  min_runners         = optional(number, 1)\u003cbr\u003e  max_runners         = optional(number, 5)\u003cbr\u003e  runner_image        = optional(string, \"ghcr.io/actions/actions-runner:latest\")\u003cbr\u003e  pull_always         = optional(bool, true)\u003cbr\u003e  container_mode      = optional(string, \"dind\")\u003cbr\u003e  visibility          = optional(string, \"all\")\u003cbr\u003e  workflows           = optional(list(string), null)\u003cbr\u003e  repositories        = optional(list(string), null)\u003cbr\u003e}))\u003c/pre\u003e | \u003cpre\u003e{\u003cbr\u003e  \"arc-runner-set\": {\u003cbr\u003e    \"runner_group\": null,\u003cbr\u003e    \"create_runner_group\": true,\u003cbr\u003e    \"namespace\": \"arc-runners\",\u003cbr\u003e    \"create_namespace\": true,\u003cbr\u003e    \"version\": \"0.13.0\",\u003cbr\u003e    \"min_runners\": 1,\u003cbr\u003e    \"max_runners\": 5,\u003cbr\u003e    \"runner_image\": \"ghcr.io/actions/actions-runner:latest\",\u003cbr\u003e    \"pull_always\": true,\u003cbr\u003e    \"container_mode\": \"dind\",\u003cbr\u003e    \"visibility\": \"all\",\u003cbr\u003e    \"workflows\": null,\u003cbr\u003e    \"repositories\": null\u003cbr\u003e  }\u003cbr\u003e}\u003c/pre\u003e | no |\n| \u003ca name=\"input_github_token\"\u003e\u003c/a\u003e [github\\_token](#input\\_github\\_token) | GitHub Token (use either token or GitHub App credentials) | `string` | `null` | no |\n| \u003ca name=\"input_github_app_id\"\u003e\u003c/a\u003e [github\\_app\\_id](#input\\_github\\_app\\_id) | GitHub App ID (use either token or GitHub App credentials) | `number` | `null` | no |\n| \u003ca name=\"input_github_app_installation_id\"\u003e\u003c/a\u003e [github\\_app\\_installation\\_id](#input\\_github\\_app\\_installation\\_id) | GitHub App Installation ID | `number` | `null` | no |\n| \u003ca name=\"input_github_app_private_key\"\u003e\u003c/a\u003e [github\\_app\\_private\\_key](#input\\_github\\_app\\_private\\_key) | GitHub App private key (PEM format) | `string` | `null` | no |\n| \u003ca name=\"input_github_repositories\"\u003e\u003c/a\u003e [github\\_repositories](#input\\_github\\_repositories) | All repositories in the organization. If not provided, they will be fetched by the module | `any` | `null` | no |\n| \u003ca name=\"input_private_registry\"\u003e\u003c/a\u003e [private\\_registry](#input\\_private\\_registry) | Private container registry URL | `string` | `null` | no |\n| \u003ca name=\"input_private_registry_username\"\u003e\u003c/a\u003e [private\\_registry\\_username](#input\\_private\\_registry\\_username) | Private container registry username | `string` | `null` | no |\n| \u003ca name=\"input_private_registry_password\"\u003e\u003c/a\u003e [private\\_registry\\_password](#input\\_private\\_registry\\_password) | Private container registry password | `string` | `null` | no |\n\n## Outputs\n\n| Name | Description |\n|------|-------------|\n| \u003ca name=\"output_controller\"\u003e\u003c/a\u003e [controller](#output\\_controller) | The Helm release name of the controller |\n| \u003ca name=\"output_scale_set\"\u003e\u003c/a\u003e [scale\\_set](#output\\_scale\\_set) | List of scale set names created |\n\n## Authentication Methods\n\nThis module supports two authentication methods with GitHub:\n\n### Personal Access Token (PAT)\n\n```hcl\nmodule \"github_runners\" {\n  source       = \"path/to/module\"\n  github_org   = \"my-organization\"\n  github_token = var.github_token  # Classic PAT with admin:org scope\n}\n```\n\n**Required Scopes:**\n- `admin:org` (for runner group management)\n- `repo` (if managing repository runners)\n\n### GitHub App\n\n```hcl\nmodule \"github_runners\" {\n  source                     = \"path/to/module\"\n  github_org                 = \"my-organization\"\n  github_app_id              = var.github_app_id\n  github_app_installation_id = var.github_app_installation_id\n  github_app_private_key     = file(\"github-app-key.pem\")\n}\n```\n\n**Required Permissions:**\n- Repository permissions: `Actions: Read \u0026 Write`, `Administration: Read \u0026 Write`\n- Organization permissions: `Self-hosted runners: Read \u0026 Write`\n\n## Scale Set Configuration\n\n### Container Modes\n\n- **`dind`** (Docker-in-Docker): Runs Docker daemon inside the runner container\n- **`kubernetes`**: Uses Kubernetes-native container execution\n- **`null`**: No container mode (bare runner)\n\n### Visibility Options\n\n- **`all`**: Runners available to all repositories in the organization\n- **`selected`**: Runners limited to specific repositories\n- **`private`**: Runners available only to private repositories\n\n### Runner Groups\n\nRunner groups organize runners and control access:\n\n```hcl\nscale_sets = {\n  \"backend-runners\" = {\n    runner_group        = \"backend-team\"\n    create_runner_group = true\n    visibility          = \"selected\"\n    repositories        = [\"api\", \"database\", \"worker\"]\n    workflows           = [\".github/workflows/deploy.yml\"]\n  }\n}\n```\n\n## Testing\n\nThis module includes comprehensive Terraform native tests using mock providers:\n\n```bash\nterraform test\n```\n\nTests cover:\n- Controller creation\n- Multiple scale sets\n- GitHub App authentication\n- Private registry configuration\n- Runner groups\n- Variable validations\n- Container modes\n- Resource dependencies\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request.\n\n## Authors\n\nCreated and maintained by [Your Name/Organization]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvmvarela%2Fterraform-github-actions-runner-scale-set","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvmvarela%2Fterraform-github-actions-runner-scale-set","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvmvarela%2Fterraform-github-actions-runner-scale-set/lists"}