Add GitHub Actions Runner Setup Guide to README.md

README.md

@@ -1,2 +1,107 @@
 # ghe-runners
 Manage Repo Specific Runners
+
+# GitHub Actions Runner Setup Guide
+
+This repository contains infrastructure code to manage repository-specific GitHub Actions runners using AWS ECS Fargate.
+
+## Prerequisites
+
+- AWS Account with appropriate permissions
+- Terraform installed
+- GitHub Organization Admin access
+- AWS CLI configured with appropriate credentials
+- GitHub Personal Access Token with admin:org permissions
+
+## Quick Start
+
+1. Clone this repository:
+```bash
+git clone <repository-url>
+cd ghe-runner
+```
+
+2. Create a `terraform.tfvars` file with your configuration:
+```hcl
+repo_org         = "your-organization"
+aws_account      = "your-aws-account-name"
+server_url       = "https://github.your-domain.com"
+vpc_id           = "vpc-xxxxxx"
+subnets          = ["subnet-xxxxx", "subnet-yyyyy"]
+security_groups  = ["sg-xxxxxx"]
+image_name       = "github-runner"
+image_version    = "latest"
+desired_count    = 2  # Number of runners
+```
+
+3. Initialize and apply Terraform:
+```bash
+terraform init
+terraform workspace new <environment>
+terraform plan
+terraform apply
+```
+
+## Configuration Details
+
+### Required Variables
+
+- `repo_org`: Your GitHub organization name
+- `aws_account`: AWS account identifier
+- `server_url`: GitHub Enterprise Server URL
+- `vpc_id`: VPC ID where runners will be deployed
+- `subnets`: List of subnet IDs for runner deployment
+- `security_groups`: Security group IDs for runners
+- `image_name`: GitHub runner container image name
+- `image_version`: Container image version tag
+
+### Optional Variables
+
+- `create_vpc_endpoint`: Set to true to create VPC endpoints (default: false)
+- `create_ecs_cluster`: Create new ECS cluster (default: false)
+- `assign_public_ip`: Assign public IP to runners (default: false)
+- `desired_count`: Number of runner instances (default: 2)
+
+## Runner Labels
+
+Runners are automatically configured with the following labels:
+- AWS account identifier
+- Organization name
+- Region
+- ECS identifier
+- Ubuntu-latest
+
+## Security Considerations
+
+1. Runners are deployed in private subnets by default
+2. VPC endpoints can be created for ECR/S3 access
+3. GitHub token is stored securely in AWS Secrets Manager
+4. Runners use IAM roles with least privilege
+
+## Monitoring
+
+- CloudWatch Log Group: `/ecs-ghe-runners/{workspace}-{account-id}-{region}`
+- Runner logs are retained for 90 days
+- ECS task metrics available in CloudWatch
+
+## Troubleshooting
+
+1. Check ECS task status in AWS Console
+2. Review CloudWatch logs for runner issues
+3. Verify GitHub organization permissions
+4. Ensure VPC endpoints are accessible
+5. Validate security group rules
+
+## Support
+
+For issues or questions:
+1. Check existing GitHub issues
+2. Review AWS ECS and GitHub Actions documentation
+3. Contact repository maintainers
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Submit a pull request with detailed description
+4. Ensure tests pass and documentation is updated