{"id":29943262,"url":"https://github.com/sourcefuse/terraform-aws-arc-github-runner","last_synced_at":"2025-08-03T02:15:48.496Z","repository":{"id":88256480,"uuid":"590073393","full_name":"sourcefuse/terraform-aws-arc-github-runner","owner":"sourcefuse","description":"Repo for managing the self hosted GitHub Actions Runner.","archived":false,"fork":false,"pushed_at":"2024-02-06T11:31:42.000Z","size":59,"stargazers_count":2,"open_issues_count":3,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-08-01T05:55:58.807Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sourcefuse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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}},"created_at":"2023-01-17T15:47:54.000Z","updated_at":"2025-03-14T09:45:10.000Z","dependencies_parsed_at":"2024-02-05T03:44:38.887Z","dependency_job_id":null,"html_url":"https://github.com/sourcefuse/terraform-aws-arc-github-runner","commit_stats":null,"previous_names":["sourcefuse/terraform-aws-arc-github-runner"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/sourcefuse/terraform-aws-arc-github-runner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcefuse%2Fterraform-aws-arc-github-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcefuse%2Fterraform-aws-arc-github-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcefuse%2Fterraform-aws-arc-github-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcefuse%2Fterraform-aws-arc-github-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sourcefuse","download_url":"https://codeload.github.com/sourcefuse/terraform-aws-arc-github-runner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sourcefuse%2Fterraform-aws-arc-github-runner/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268484362,"owners_count":24257660,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-03T02:00:12.545Z","response_time":2577,"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":[],"created_at":"2025-08-03T02:14:47.763Z","updated_at":"2025-08-03T02:15:48.479Z","avatar_url":"https://github.com/sourcefuse.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [terraform-aws-arc-github-runner](https://github.com/sourcefuse/terraform-aws-arc-github-runner)\n\n[![Quality gate](https://sonarcloud.io/api/project_badges/quality_gate?project=sourcefuse_terraform-aws-arc-github-runner)](https://sonarcloud.io/summary/new_code?id=sourcefuse_terraform-aws-arc-github-runner)\n\n[![Known Vulnerabilities](https://github.com/sourcefuse/terraform-refarch-github-runner/actions/workflows/snyk.yaml/badge.svg)](https://github.com/sourcefuse/terraform-refarch-github-runner/actions/workflows/snyk.yaml)\n\n## Overview\n\nSourceFuse AWS Reference Architecture (ARC) Terraform module for managing GitHub Runner.  \n\nThis module will create the following resources in a specified AWS Account:  \n* S3 bucket: used for storing the generated `docker-compose.yml`\n* EC2 instance: Used for running the runner container on\n* SSH Key Pair: Used for decrypting EC2 password\n* SSM Documents: Used for installing dependencies and updating the SSM Agent\n* IAM Policies: For accessing created resources\n* SSM Parameter: For storing the runner token\n\nThis module utilizes different `local-exec` provisioners to execute scripts for obtaining the needed GitHub Runner token\nand remove the runner from the organization when the resources are destroyed.\nSee [Pre-Requisites](#pre-requisites) for information on the needed permissions these scripts will require.  \n\n### Pre-Requisites\nYou will need to have a GitHub Personal Access Token (PAT) with `admin:org` permissions in order to manage GitHub runners for the Organization.\nIf you do not have sufficient permissions to GitHub, the runner will not register.  \n\nOnce you've obtained a PAT, you will need to set it so Terraform can access it.\nThe recommended approach to this is to save it in _Systems Manager Parameter Store_ with the Parameter name of: `/\u003cnamespace\u003e/\u003cenvironment\u003e/github/token`\nYou can reference this parameter via a data lookup:  \n```hcl\ndata \"aws_ssm_parameter\" \"github_token\" {\n  name = \"/${var.namespace}/${var.environment}/github/token\"\n}\n```\n\n## Usage\n:warning: At this time, this module only supports **Debian** / **Ubuntu** AMIs.\nWhen choosing an AMI, please be sure to select either **Ubuntu** or **Debian**.  \n\nTo see a full example, check out the [main.tf](https://github.com/sourcefuse/terraform-aws-arc-github-runner/blob/main/example/main.tf) file in the example folder.  \n\n```hcl\nmodule \"runner\" {\n  source  = \"sourcefuse/arc-github-runner/aws\"\n  version = \"0.2.6\"\n  namespace     = var.namespace\n  environment   = var.environment\n  region        = var.region\n  subnet_id     = local.private_subnet_ids[0]\n  vpc_id        = data.aws_vpc.this.id\n  instance_type = \"t2.micro\"\n  github_token  = data.aws_ssm_parameter.github_token.value\n  runner_labels = \"example,${var.namespace},${var.environment}\"\n\n  tags = module.tags.tags\n}\n```\n\n\u003c!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK --\u003e\n## Requirements\n\n| Name | Version |\n|------|---------|\n| \u003ca name=\"requirement_terraform\"\u003e\u003c/a\u003e [terraform](#requirement\\_terraform) | ~\u003e 1.3, \u003c 2.0.0 |\n| \u003ca name=\"requirement_aws\"\u003e\u003c/a\u003e [aws](#requirement\\_aws) | \u003e= 4.0 |\n| \u003ca name=\"requirement_null\"\u003e\u003c/a\u003e [null](#requirement\\_null) | \u003e= 3.0 |\n| \u003ca name=\"requirement_random\"\u003e\u003c/a\u003e [random](#requirement\\_random) | \u003e= 3.0 |\n\n## Providers\n\n| Name | Version |\n|------|---------|\n| \u003ca name=\"provider_aws\"\u003e\u003c/a\u003e [aws](#provider\\_aws) | 4.50.0 |\n| \u003ca name=\"provider_null\"\u003e\u003c/a\u003e [null](#provider\\_null) | 3.2.1 |\n| \u003ca name=\"provider_random\"\u003e\u003c/a\u003e [random](#provider\\_random) | 3.4.3 |\n\n## Modules\n\n| Name | Source | Version |\n|------|--------|---------|\n| \u003ca name=\"module_runner\"\u003e\u003c/a\u003e [runner](#module\\_runner) | git::https://github.com/cloudposse/terraform-aws-ec2-instance | 0.45.2 |\n| \u003ca name=\"module_ssh_key_pair\"\u003e\u003c/a\u003e [ssh\\_key\\_pair](#module\\_ssh\\_key\\_pair) | git::https://github.com/cloudposse/terraform-aws-key-pair | 0.18.3 |\n\n## Resources\n\n| Name | Type |\n|------|------|\n| [aws_iam_policy.runner_bucket_access](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_policy) | resource |\n| [aws_iam_role_policy_attachment.runner](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |\n| [aws_iam_role_policy_attachment.runner_bucket_access](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/iam_role_policy_attachment) | resource |\n| [aws_s3_bucket.runner](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket) | resource |\n| [aws_s3_bucket_acl.runner](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_acl) | resource |\n| [aws_s3_bucket_logging.runner](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_logging) | resource |\n| [aws_s3_bucket_public_access_block.runner](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_public_access_block) | resource |\n| [aws_s3_bucket_server_side_encryption_configuration.runner](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_server_side_encryption_configuration) | resource |\n| [aws_s3_bucket_versioning.runner](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket_versioning) | resource |\n| [aws_s3_object.docker_compose](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_object) | resource |\n| [aws_ssm_association.dependencies](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ssm_association) | resource |\n| [aws_ssm_association.runner_compose](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ssm_association) | resource |\n| [aws_ssm_document.dependencies](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ssm_document) | resource |\n| [aws_ssm_document.runner_compose](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/ssm_document) | resource |\n| [null_resource.cleanup](https://registry.terraform.io/providers/hashicorp/null/latest/docs/resources/resource) | resource |\n| [null_resource.prepare](https://registry.terraform.io/providers/hashicorp/null/latest/docs/resources/resource) | resource |\n| [random_string.runner](https://registry.terraform.io/providers/hashicorp/random/latest/docs/resources/string) | resource |\n| [aws_caller_identity.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source |\n| [aws_ssm_parameter.runner_token](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/ssm_parameter) | data source |\n\n## Inputs\n\n| Name | Description | Type | Default | Required |\n|------|-------------|------|---------|:--------:|\n| \u003ca name=\"input_ami\"\u003e\u003c/a\u003e [ami](#input\\_ami) | AMI information for the EC2 instance | \u003cpre\u003eobject({\u003cbr\u003e    id       = string\u003cbr\u003e    owner_id = string\u003cbr\u003e  })\u003c/pre\u003e | \u003cpre\u003e{\u003cbr\u003e  \"id\": \"ami-04505e74c0741db8d\",\u003cbr\u003e  \"owner_id\": \"099720109477\"\u003cbr\u003e}\u003c/pre\u003e | no |\n| \u003ca name=\"input_associate_public_ip_address\"\u003e\u003c/a\u003e [associate\\_public\\_ip\\_address](#input\\_associate\\_public\\_ip\\_address) | Associate a public IP address with the instance | `bool` | `false` | no |\n| \u003ca name=\"input_ec2_runner_iam_role_policy_arns\"\u003e\u003c/a\u003e [ec2\\_runner\\_iam\\_role\\_policy\\_arns](#input\\_ec2\\_runner\\_iam\\_role\\_policy\\_arns) | IAM role policies to attach to the Runner instance | `list(string)` | \u003cpre\u003e[\u003cbr\u003e  \"arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore\",\u003cbr\u003e  \"arn:aws:iam::aws:policy/service-role/AmazonEC2RoleforSSM\"\u003cbr\u003e]\u003c/pre\u003e | no |\n| \u003ca name=\"input_environment\"\u003e\u003c/a\u003e [environment](#input\\_environment) | Name of the environment, i.e. dev, stage, prod | `string` | n/a | yes |\n| \u003ca name=\"input_github_owner\"\u003e\u003c/a\u003e [github\\_owner](#input\\_github\\_owner) | GitHub Owner the runner belongs to. If you are adding a repo, the format will be `owner/repo` | `string` | `\"sourcefuse\"` | no |\n| \u003ca name=\"input_github_token\"\u003e\u003c/a\u003e [github\\_token](#input\\_github\\_token) | GitHub Personal Access Token with `admin:org` permission scope.\u003cbr\u003eThis is used to obtain a Runner Token used for registering the runner.\u003cbr\u003eFor more information, see [Create a registration token for an organization](https://docs.github.com/en/rest/actions/self-hosted-runners?apiVersion=2022-11-28#create-a-registration-token-for-an-organization). | `string` | n/a | yes |\n| \u003ca name=\"input_instance_type\"\u003e\u003c/a\u003e [instance\\_type](#input\\_instance\\_type) | The instance type for the EC2 instance. Default is t3a.medium. | `string` | `\"t3a.medium\"` | no |\n| \u003ca name=\"input_monitoring_enabled\"\u003e\u003c/a\u003e [monitoring\\_enabled](#input\\_monitoring\\_enabled) | Launched EC2 instance will have detailed monitoring enabled | `bool` | `true` | no |\n| \u003ca name=\"input_namespace\"\u003e\u003c/a\u003e [namespace](#input\\_namespace) | Namespace of the project, i.e. refarch | `string` | n/a | yes |\n| \u003ca name=\"input_region\"\u003e\u003c/a\u003e [region](#input\\_region) | AWS region | `string` | n/a | yes |\n| \u003ca name=\"input_repos_or_orgs\"\u003e\u003c/a\u003e [repos\\_or\\_orgs](#input\\_repos\\_or\\_orgs) | Whether the API will register / deregister the runner in repos or orgs. Options are `orgs` and `repos` | `string` | `\"orgs\"` | no |\n| \u003ca name=\"input_root_block_device_encrypted\"\u003e\u003c/a\u003e [root\\_block\\_device\\_encrypted](#input\\_root\\_block\\_device\\_encrypted) | Whether to encrypt the root block device | `bool` | `true` | no |\n| \u003ca name=\"input_root_block_device_kms_key_id\"\u003e\u003c/a\u003e [root\\_block\\_device\\_kms\\_key\\_id](#input\\_root\\_block\\_device\\_kms\\_key\\_id) | KMS key ID used to encrypt EBS volume. When specifying root\\_block\\_device\\_kms\\_key\\_id, root\\_block\\_device\\_encrypted needs to be set to true | `string` | `null` | no |\n| \u003ca name=\"input_root_volume_size\"\u003e\u003c/a\u003e [root\\_volume\\_size](#input\\_root\\_volume\\_size) | Size of the root volume in gigabytes | `string` | `\"80\"` | no |\n| \u003ca name=\"input_root_volume_type\"\u003e\u003c/a\u003e [root\\_volume\\_type](#input\\_root\\_volume\\_type) | Type of root volume. Can be standard, gp2, gp3, io1 or io2 | `string` | `\"gp2\"` | no |\n| \u003ca name=\"input_runner_image\"\u003e\u003c/a\u003e [runner\\_image](#input\\_runner\\_image) | Name of the image to use for the Actions Runner. | `string` | `\"sourcefuse/github-runner:0.3.0\"` | no |\n| \u003ca name=\"input_runner_labels\"\u003e\u003c/a\u003e [runner\\_labels](#input\\_runner\\_labels) | Labels to assign the GitHub Runner. If no values are given, the default labels will be:\u003cbr\u003e  - `self-hosted`\u003cbr\u003e  - Base OS, i.e. `Linux`\u003cbr\u003e  - Architecture, i.e. `X64`\u003cbr\u003eThese labels cannot be overridden.\u003cbr\u003eSeparate labels via comma, i.e. `dev,docker,another_label` | `string` | `\"\"` | no |\n| \u003ca name=\"input_runner_name\"\u003e\u003c/a\u003e [runner\\_name](#input\\_runner\\_name) | Name to assign the GitHub Runner. If no value is given, it will use the ec2 instance name. | `string` | `null` | no |\n| \u003ca name=\"input_runner_user\"\u003e\u003c/a\u003e [runner\\_user](#input\\_runner\\_user) | Name of the user to run the container as. | `string` | `\"runner\"` | no |\n| \u003ca name=\"input_security_group_rules\"\u003e\u003c/a\u003e [security\\_group\\_rules](#input\\_security\\_group\\_rules) | Security group rules for the EC2 instance running the GitHub Runner | \u003cpre\u003elist(object({\u003cbr\u003e    type        = string\u003cbr\u003e    from_port   = number\u003cbr\u003e    to_port     = number\u003cbr\u003e    protocol    = string\u003cbr\u003e    cidr_blocks = list(string)\u003cbr\u003e  }))\u003c/pre\u003e | \u003cpre\u003e[\u003cbr\u003e  {\u003cbr\u003e    \"cidr_blocks\": [\u003cbr\u003e      \"0.0.0.0/0\"\u003cbr\u003e    ],\u003cbr\u003e    \"from_port\": 0,\u003cbr\u003e    \"protocol\": \"-1\",\u003cbr\u003e    \"to_port\": 65535,\u003cbr\u003e    \"type\": \"egress\"\u003cbr\u003e  }\u003cbr\u003e]\u003c/pre\u003e | no |\n| \u003ca name=\"input_ssm_patch_manager_enabled\"\u003e\u003c/a\u003e [ssm\\_patch\\_manager\\_enabled](#input\\_ssm\\_patch\\_manager\\_enabled) | Whether to enable SSM Patch manager | `bool` | `true` | no |\n| \u003ca name=\"input_subnet_id\"\u003e\u003c/a\u003e [subnet\\_id](#input\\_subnet\\_id) | Subnet ID for the EC2 instance to be assigned to | `string` | n/a | yes |\n| \u003ca name=\"input_tags\"\u003e\u003c/a\u003e [tags](#input\\_tags) | Default tags to apply to every resource | `map(string)` | `{}` | no |\n| \u003ca name=\"input_volume_tags_enabled\"\u003e\u003c/a\u003e [volume\\_tags\\_enabled](#input\\_volume\\_tags\\_enabled) | Whether or not to copy instance tags to root and EBS volumes | `bool` | `true` | no |\n| \u003ca name=\"input_vpc_id\"\u003e\u003c/a\u003e [vpc\\_id](#input\\_vpc\\_id) | VPC ID for EC2 instance to reside in | `string` | n/a | yes |\n\n## Outputs\n\n| Name | Description |\n|------|-------------|\n| \u003ca name=\"output_ec2_runner_instance_id\"\u003e\u003c/a\u003e [ec2\\_runner\\_instance\\_id](#output\\_ec2\\_runner\\_instance\\_id) | Instance ID of the EC2 Runner |\n| \u003ca name=\"output_ec2_runner_instance_name\"\u003e\u003c/a\u003e [ec2\\_runner\\_instance\\_name](#output\\_ec2\\_runner\\_instance\\_name) | Instance Name of the EC2 Runner |\n| \u003ca name=\"output_ec2_runner_role\"\u003e\u003c/a\u003e [ec2\\_runner\\_role](#output\\_ec2\\_runner\\_role) | Instance role name |\n| \u003ca name=\"output_ec2_runner_role_arn\"\u003e\u003c/a\u003e [ec2\\_runner\\_role\\_arn](#output\\_ec2\\_runner\\_role\\_arn) | Instance role ARN |\n\u003c!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK --\u003e\n\n## Development\n\n### Prerequisites\n\n- [terraform](https://learn.hashicorp.com/terraform/getting-started/install#installing-terraform)\n- [aws cli](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)\n- [terraform-docs](https://github.com/segmentio/terraform-docs)\n- [pre-commit](https://pre-commit.com/#install)\n- [golang](https://golang.org/doc/install#install)\n- [golint](https://github.com/golang/lint#installation)\n\n### Configurations\n\n- Configure pre-commit hooks\n  ```sh\n  pre-commit install\n  ```\n\n### Git commits\n\nwhile Contributing or doing git commit please specify the breaking change in your commit message whether its major,minor or patch\n\nFor Example\n\n```sh\ngit commit -m \"your commit message #major\"\n```\nBy specifying this , it will bump the version and if you dont specify this in your commit message then by default it will consider patch and will bump that accordingly\n\n### Tests\n- Tests are available in `test` directory\n- Configure the dependencies\n  ```sh\n  cd test/\n  go mod init github.com/sourcefuse/terraform-aws-refarch-github-runner\n  go get github.com/gruntwork-io/terratest/modules/terraform\n  ```\n- Now execute the test  \n  ```sh\n  go test -timeout  30m\n  ```\n\n## Authors\n\nThis project is authored by:\n- SourceFuse ARC Team\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsourcefuse%2Fterraform-aws-arc-github-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsourcefuse%2Fterraform-aws-arc-github-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsourcefuse%2Fterraform-aws-arc-github-runner/lists"}