{"id":29275377,"url":"https://github.com/tab/gh-runner","last_synced_at":"2026-04-01T23:04:58.724Z","repository":{"id":302517438,"uuid":"1012729280","full_name":"tab/gh-runner","owner":"tab","description":"GitHub Self-Hosted Runner","archived":false,"fork":false,"pushed_at":"2025-07-02T20:07:53.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-02T20:37:50.224Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":false,"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/tab.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}},"created_at":"2025-07-02T19:38:09.000Z","updated_at":"2025-07-02T20:07:23.000Z","dependencies_parsed_at":"2025-07-02T20:49:10.420Z","dependency_job_id":null,"html_url":"https://github.com/tab/gh-runner","commit_stats":null,"previous_names":["tab/gh-runner"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/tab/gh-runner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tab%2Fgh-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tab%2Fgh-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tab%2Fgh-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tab%2Fgh-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tab","download_url":"https://codeload.github.com/tab/gh-runner/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tab%2Fgh-runner/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263692940,"owners_count":23496945,"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","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-07-05T06:10:29.932Z","updated_at":"2026-04-01T23:04:58.716Z","avatar_url":"https://github.com/tab.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub Self-Hosted Runner\n\nA containerized GitHub Actions runner that can be deployed to run CI/CD workflows for your GitHub repositories. This Docker-based solution provides a secure, scalable way to execute GitHub Actions workflows on your own infrastructure.\n\n## Features\n\n- **Containerized**: Runs in Docker with minimal dependencies\n- **Secure**: Non-root execution with limited sudo permissions\n- **Multi-architecture**: Supports both AMD64 and ARM64\n- **Auto-registration**: Dynamically registers with GitHub using API tokens\n- **Graceful cleanup**: Properly removes runner registration on shutdown\n- **Persistent work directory**: Mounts work directory for build artifacts\n\n## Quick Start\n\n### Prerequisites\n\n- Docker installed and running\n- GitHub Personal Access Token with repository access\n- GitHub repository where you want to run workflows\n\n### Running the Runner\n\n1. **Build the container:**\n   ```bash\n   docker build -t gh-runner .\n   ```\n\n2. **Run the container:**\n   ```bash\n   docker run -d \\\n     --name my-github-runner \\\n     -e GITHUB_REPO=\"owner/repository-name\" \\\n     -e GITHUB_PAT=\"your_personal_access_token_here\" \\\n     -v /path/to/work:/home/runner/_work \\\n     gh-runner\n   ```\n\n3. **Check the logs:**\n   ```bash\n   docker logs my-github-runner\n   ```\n\n## Environment Variables\n\n### Required\n\n| Variable      | Description                              | Example            |\n|---------------|------------------------------------------|--------------------|\n| `GITHUB_REPO` | GitHub repository in format \"owner/repo\" | `myorg/myrepo`     |\n| `GITHUB_PAT`  | Personal Access Token with repo access   | `ghp_xxxxxxxxxxxx` |\n\n### Optional\n\n| Variable        | Description            | Default                       |\n|-----------------|------------------------|-------------------------------|\n| `RUNNER_NAME`   | Name for the runner    | `gh-runner-{hostname}`        |\n| `RUNNER_LABELS` | Comma-separated labels | `docker,linux,{architecture}` |\n\n## GitHub Personal Access Token Setup\n\nYour Personal Access Token needs the following permissions:\n- `repo` (Full control of private repositories)\n- Or `public_repo` (Access public repositories) if only using public repos\n\nTo create a token:\n1. Go to GitHub Settings → Developer settings → Personal access tokens\n2. Generate new token (classic)\n3. Select appropriate repository permissions\n4. Copy the token and use it as `GITHUB_PAT`\n\n## Docker Compose Example\n\n```yaml\nversion: '3.8'\nservices:\n  github-runner:\n    build: .\n    environment:\n      - GITHUB_REPO=myorg/myrepo\n      - GITHUB_PAT=ghp_xxxxxxxxxxxx\n      - RUNNER_NAME=docker-runner-1\n      - RUNNER_LABELS=docker,linux,self-hosted\n    volumes:\n      - ./work:/home/runner/_work\n    restart: unless-stopped\n```\n\n## Volume Mounts\n\nThe runner requires a work directory to be mounted:\n\n```bash\n-v /host/path/to/work:/home/runner/_work\n```\n\n**Important**: The work directory must be writable by UID 1001:\n```bash\nsudo chown -R 1001:1001 /host/path/to/work\n```\n\n## Architecture\n\nThe runner consists of:\n\n1. **Multi-stage Dockerfile**:\n   - Downloads GitHub Actions runner (v2.325.0)\n   - Downloads Goose database migration tool (v3.24.3)\n   - Uses Debian 12.6-slim as runtime base\n\n2. **Entrypoint script**:\n   - Handles runner registration with GitHub API\n   - Manages graceful shutdown and cleanup\n   - Configures runner with proper labels and work directory\n\n3. **Security model**:\n   - Runs as non-root user (UID 1001)\n   - Limited sudo permissions for package management\n   - Isolated container environment\n\n## Troubleshooting\n\n### Runner not appearing in GitHub\n\n1. Check container logs: `docker logs container-name`\n2. Verify `GITHUB_REPO` format is correct (`owner/repo`)\n3. Ensure Personal Access Token has correct permissions\n4. Check if repository exists and token has access\n\n### Permission errors\n\n1. Ensure work directory has correct ownership:\n   ```bash\n   sudo chown -R 1001:1001 /path/to/work\n   ```\n\n### Runner registration fails\n\n1. Verify Personal Access Token is valid and not expired\n2. Check if repository name is correct\n3. Ensure network connectivity to GitHub API\n\n## Development\n\n### Building locally\n```bash\ndocker build -t gh-runner .\n```\n\n### Testing the entrypoint\n```bash\ndocker run --rm -it \\\n  -e GITHUB_REPO=\"owner/repo\" \\\n  -e GITHUB_PAT=\"token\" \\\n  gh-runner\n```\n\n### Debugging\n```bash\ndocker run --rm -it \\\n  -e GITHUB_REPO=\"owner/repo\" \\\n  -e GITHUB_PAT=\"token\" \\\n  gh-runner bash\n```\n\n## License\n\nSee [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftab%2Fgh-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftab%2Fgh-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftab%2Fgh-runner/lists"}