{"id":22751873,"url":"https://github.com/stackguardian/sg-runner","last_synced_at":"2026-01-16T08:10:14.469Z","repository":{"id":183919698,"uuid":"488533457","full_name":"StackGuardian/sg-runner","owner":"StackGuardian","description":"Private runner for StackGuardian","archived":false,"fork":false,"pushed_at":"2026-01-13T23:40:34.000Z","size":302,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-01-14T00:51:49.215Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","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/StackGuardian.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":"2022-05-04T09:50:28.000Z","updated_at":"2025-09-03T11:18:33.000Z","dependencies_parsed_at":"2023-07-26T11:49:35.213Z","dependency_job_id":"182bea4f-94af-43ac-bf59-b7b0f02a96e6","html_url":"https://github.com/StackGuardian/sg-runner","commit_stats":null,"previous_names":["stackguardian/sg-runner"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/StackGuardian/sg-runner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StackGuardian%2Fsg-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StackGuardian%2Fsg-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StackGuardian%2Fsg-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StackGuardian%2Fsg-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StackGuardian","download_url":"https://codeload.github.com/StackGuardian/sg-runner/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StackGuardian%2Fsg-runner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28478047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T06:30:42.265Z","status":"ssl_error","status_checked_at":"2026-01-16T06:30:16.248Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":"2024-12-11T05:07:44.653Z","updated_at":"2026-01-16T08:10:14.461Z","avatar_url":"https://github.com/StackGuardian.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# StackGuardian Private Runner v1.0\n\n## Table of Contents\n\n- [1.0 Introduction](#10-introduction)\n- [2.0 How it works](#20-how-it-works)\n- [3.0 Setup](#30-setup)\n  - [3.1 Environment](#31-environment)\n  - [3.2 Registration](#32-registration)\n    - [3.2.1 Get credentials from StackGuardian](#331-get-credentials-from-stackguardian)\n    - [3.2.2 Run the script for registration](#332-run-the-script-for-registration)\n  - [3.3 De-registration](#34-de-registration)\n  - [3.4 Restart](#34-restart)\n- [Other options](#other-options)\n\n## 1.0 Introduction\n\n**StackGuardian Private Runner** represents infrastructure that supports\nregistering external (self-hosted) instances to the StackGuardian platform.\nConfiguration is very simple, get credentials from StackGuardian platform,\nand run `main.sh` script with credentials.\n\nCheck [Setup](#setup) for more details.\n\n## 2.0 How it works\n\nWhen instance is successfully registered, it is added as _External Instance_ to\n_AWS Elastic Cluster Service (ECS)_, and it represents customer **Node**.\n**Node** is further used for running _ECS tasks_, like docker images.\nEach requested _task run_ is placed on the **Node**.\nWhich means, anything described inside that task will be running on **Node** (self-hosted/external instance).\nOnly, _task definition_ will live on _AWS ECS_.\n\n## 3.0 Setup\n\n\u003e **IMPORTANT:**\n\u003e To ensure a smooth lifecycle for your instance, it is important to avoid having any IAM Roles attached to it.\n\u003e Having IAM Roles attached can potentially cause connection issues and disrupt the instance's functioning.\n\u003e Therefore, it is recommended to remove or detach any IAM Roles from the instance to prevent any complications during its lifecycle.\n\u003e This precaution will help maintain the stability and uninterrupted operation of the instance.\n\nSetup is very simple. We tried to make it as automated as possible.\nAll you have to do is run `main.sh` with wanted option that you want to execute:\n[Registration](#registration) or [De-registration](#de-registration), and\nprovided credentials from _StackGuardian_ platform.\n\n\u003e For more details the `main.sh` script has integrated _help_ menu:\n\u003e\n\u003e ```\n\u003e ./main.sh --help\n\u003e ```\n\n### 3.1 Environment\n\nThere are couple of environment variables that can be overridden for the purposes of testing:\n\n```\nSG_BASE_API\nLOG_DEBUG\nCGROUPSV2_PREVIEW\n```\n\n- `SG_BASE_API`: Change base of API. Default: `https://api.app.stackguardian.io/api/v1`\n- `LOG_DEBUG`: If set to `true`, print additional `DEBUG` logs\n- `CGROUPSV2_PREVIEW`: If set to `true`, enables management of `cgroupsv2`\n\nEnvironment variables can be exported using `export` or saved to `.env` which is loaded automatically.\n\n### 3.2 Registration\n\n\u003e Registration is more complex part, but it is packed to be as simple as possible\n\u003e on the surface.\n\nRegistration can be done in a few steps described below:\n\n#### 3.2.1 Get credentials from StackGuardian\n\n#### 3.2.2 Run the script for registration\n\nAfter getting credentials, run script like below while providing\n`SG_NODE_TOKEN`, `ORGANIZATION` and `RUNNER_GROUP`:\n\n```\nmain.sh register \\\n    --sg-node-token ${SG_NODE_TOKEN} \\\n    --organization ${ORGANIZATION} \\\n    --runner-group ${RUNNER_GROUP}\n```\n\n### 3.3 De-registration\n\nDe-registration is run almost the same way as registration:\n\n```\nmain.sh deregister \\\n    --sg-node-token ${SG_NODE_TOKEN} \\\n    --organization ${ORGANIZATION} \\\n    --runner-group ${RUNNER_GROUP}\n```\n\n\u003e In case local data is corrupted or API call fails, you can force clean everything.\n\u003e This is done by providing `-f` or `--force` while executing `deregister`.\n\u003e _Force deregister_ will remove all data related to runner script for fresh start.\n\n### 3.4 Restart\n\nAs of now, restart is not natively supported.\nBut, to achieve similar experience it is enough to [`deregister`](#33-de-registration) and then [`register`](#32-registration) again.\n\n\u003e This should fix all troubles if something is not working.\n\n## System diagnostics\n\nWe included 2 commands for easier system diagnostics and management.\nThese should help you keep your system clean and debug in case of errors.\n\n\u003e INFO: Any of following actions keep state in a file at `/tmp/diagnostic.json`.\n\nWith any command you can provide `--debug` flag.\nWith this, you will get more output while running commands.\n\n\u003e INFO: All logs are being kept at `/tmp/sg_runner.log`.\n\n### Health check\n\nBesides `register` and `deregister`, script offers easy health checking:\n\n```\n./main.sh status\n```\n\nThis command will print status of `ecs` and `docker` services.\nAlso, including all related Docker containers (`ecs-agent`, `fluentbit-agent`).\n\n### System prune\n\nAnother useful command is `prune` which can be used like:\n\n```\n./main.sh prune\n```\n\nThis command will execute `docker system prune` for everything that is older than **10 days**.\n\n## Managing `cgroupsv2`\n\nPrivate runner does not support `cgroupsv2`. Since `cgroupsv2` tend to have problems with `docker`.\nThere is integrated option to toggle between `v2` and `v1` of `cgroups`.\n\nTo disable `cgroupsv2` and revert to `cgroupsv1` there is 2 step process as of now:\n\n```\nexport CGROUPSV2_PREVIEW=true\n```\n\n\u003e Check [Environment](#31-environment) for details\n\nand then\n\n```\n./main.sh cgropusv2 disable\n```\n\n\u003e Reboot is required after such action.\n\nTo revert you can just run:\n\n```\n./main.sh cgroupsv2 enable\n```\n\n## Troubleshooting\n\n- StackGuardian uses AWS SSM to setup connection between SG control plane and runners, you can diagnose SSM client using `ssm-cli get-diagnostics --output table`\n\n- If the registration was successful but you can't see Ping Status and IP Address for the Runner on StackGuardian Platform inside the Runner Group's -\u003e Runner Instances tab please re-register runner using the following command:\n    ```bash\n    ./main.sh deregister --sg-node-token \"TOKEN\" --organization \"ORG\" --runner-group \"RUNNER_GROUP\" \u0026\u0026 \\\n    ./main.sh register --sg-node-token \"TOKEN\" --organization \"ORG\" --runner-group \"RUNNER_GROUP\"\n    ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackguardian%2Fsg-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstackguardian%2Fsg-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstackguardian%2Fsg-runner/lists"}