Przejdź do treści
Biblioteka skilli
DevOps i chmura · Analiza

debug-ec2-runners

/debug-ec2-runners

Diagnozuje wdrożony stos ec2-runners, gdy zadanie czeka na maszynę, runner nie wystartował albo zadziałał alarm CloudWatch.

Repozytorium
ec2-runners ↗
Licencja
MIT
Ostatnia zmiana repozytorium
12.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Diagnozuje wdrożony stos ec2-runners, gdy zadanie czeka na maszynę, runner nie wystartował albo zadziałał alarm CloudWatch.

Oryginalny opis (EN)

Diagnoses a deployed ec2-runners stack. Use when a job waits for an ec2 or microvm runner, a runner failed or never started, or an ec2-runners alert or CloudWatch alarm fired.

Jak działa

  1. 1. Pin down the deployment and the symptom
  2. 2. An alert
  3. 3. A job
  4. 4. Report
Sekcje z nagłówków SKILL.md, w oryginale · 47 linii, 746 słów
Podgląd SKILL.md
---
name: debug-ec2-runners
description: Diagnoses a deployed ec2-runners stack. Use when a job waits for an ec2 or microvm runner, a runner failed or never started, or an ec2-runners alert or CloudWatch alarm fired.
---

# Debug ec2-runners

The goal is a **root cause backed by evidence**: a log line, an API response, or a table row that explains the symptom. The ec2-runners repository is three directories above this file (in Claude Code, `${CLAUDE_SKILL_DIR}/../../..`); its `docs/operations.md` describes every alert and log group, and `docs/architecture.md` describes how a job becomes a runner.

## 1. Pin down the deployment and the symptom

Get the AWS profile, region (`$REGION`), stack name (`$STACK`, default `ec2-runners`), and GitHub organization (`$ORG`). Confirm the stack exists with `aws cloudformation describe-stacks --region $REGION --stack-name $STACK`. The runner and runner group API calls in step 3 need an organization owner's `gh` login with the `admin:org` scope; when `gh auth status` does not list it, ask the person to run `gh auth refresh -h github.com -s admin:org`.

Get the symptom as one of:

- **A job**: its URL or `owner/repo` and job ID (`$REPO`, `$JOB`). A run URL gives the run; `gh run view <run id> --repo $REPO --json jobs --jq '.jobs[] | {databaseId, name, status}'` lists its job IDs.
- **An alert**: its title and text.

**Done when** you know the deployment and have either a job ID or an alert text.

## 2. An alert

Find the alert's row in the Alerts table in the repository's `docs/operations.md`, and carry out its action. Alerts about a job name the repository and job; continue with step 3 for that job when the alert's action does not resolve it.

**Done when** the alert's action is done or the cause is identified.

## 3. A job

Work through these checks in order, recording each result. Stop at the first one that explains the symptom.

1. **The job.** `gh api repos/$REPO/actions/jobs/$JOB --jq '{status, labels, runner_name, created_at}'`. The labels must include `ec2` or `microvm` (or the stack's `TriggerLabel` and `MicrovmLabel`). A job with `runner_name` set has a runner; the problem is in the job itself.
2. **The repository.** `gh api repos/$REPO --jq .private` must be `true`, unless the stack has `AllowPublicRepos=true`. The app must be installed on the repository: `gh api orgs/$ORG/installations --jq '.installations[] | {app_slug, repository_selection}'`, and for `selected`, the repository must be among the installation's repositories.
3. **The jobs table.** `aws dynamodb get-item --region $REGION --table-name $STACK-jobs --key '{"jobId":{"N":"'$JOB'"}}'`. No item means the webhook never recorded the job; the next scheduled reconcile adds it within 5 minutes, so check the webhook deliveries in the GitHub App's **Advanced** tab and the webhook log. `status` `failed` means the reconciler gave up on the job; its `error` text says whether the labels can never launch or the job's runners kept going unused. A high `launchFailures` means launches keep failing. `idleRunners` of 2 or more means GitHub is not assigning the job to its runners.
4. **The reconciler log.** Each line is JSON with a numeric `jobId`:
   ```bash
   aws logs tail /aws/lambda/$STACK-reconciler --region $REGION --since 2h --filter-pattern '{ $.jobId = '$JOB' }'
   ```
   `launched runner` or `launched MicroVM runner` names the runner. `launch failed, will retry` and `job cannot launch` carry EC2's or GitHub's error. `job never assigned to its runners` points to the runner group. Without the `--filter-pattern`, `runner group allows public repositories, launching nothing` means nothing launches for any job.
5. **The runner.** Runner names are `$STACK-$JOB-<launch time>`. `gh api orgs/$ORG/actions/runners --paginate --jq '.runners[] | select(.name | startswith("'$STACK-$JOB-'")) | {name, status, busy}'` shows its registration. A runner that is `online` and not `busy` while the job stays queued means GitHub will not give it the job: check the runner group's repository access with `gh api orgs/$ORG/actions/runner-groups/1 --jq '{visibility, allows_public_repositories}'` (use the stack's `RunnerGroupId`).
6. **The instance.** For an EC2 runner, read its boot log, which includes the runner's output:
   ```bash
   aws logs tail /ec2-runners/$STACK/boot --region $REGION --since 6h --log-stream-name-prefix $STACK-$JOB-
   ```
   The log is copied when the boot script exits or the instance terminates. For a running instance, find it with `aws ec2 describe-instances --region $REGION --filters "Name=tag:ec2-runners:runner-name,Values=$STACK-$JOB-*"` and read `/var/log/ec2-runner-boot.log` through `aws ssm start-session`. For a MicroVM runner, read `/aws/lambda-microvms/$STACK-runner`.

**Done when** one check explains the symptom with the evidence in hand, or every check has a recorded result.

## 4. Report

Tell the person the root cause, the evidence (quote the log line or API output), and the fix: the workflow, quota, runner group, or stack parameter to change. Apply a fix only with the person's approval. When every check passed and the job still waits, report each check's result and the time window searched, since `aws logs tail --since` may need widening.

Wersje

W bazie nie ma innych skilli o nazwie debug-ec2-runners.

Migawka bazy z 13.11.2026 · wersja paczki e6c17de589e4 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100cloudwatch-alarm-creator
    Prawdopodobnie tworzy alarmy Amazon CloudWatch do monitorowania zasobów AWS.
  • 100adopt-ec2-runners
    Przenosi zadania GitHub Actions na ec2-runners, dobierając etykiety i rozmiar dla każdego zadania.
  • 100glab-runner
    Zarządza runnerami GitLab CI/CD na poziomie projektu, grupy i instancji: wyświetla, przypisuje, wstrzymuje i usuwa je.
  • 100setup-ec2-runners
    Wdraża stos ec2-runners na koncie AWS i łączy go z organizacją GitHub, kończąc testowym workflow na nowych runnerach.
  • 100incus-gha-runners
    Konfiguruje, rozszerza i naprawia samodzielnie hostowane runnery GitHub Actions na jednym hoście Linux, każdy w osobnym nieuprzywilejowanym kontenerze systemowym Incus z własnym Dockerem.
  • 100glab-runner
    Zarządza runnerami GitLab CI/CD na poziomie projektu, grupy lub instancji: listowanie, przypisywanie, podgląd ostatnich jobów i managerów, wstrzymywanie oraz usuwanie wycofanych runnerów.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.