feat: bootstrap diagnostics (phone-home tags, fast-fail, console capture, cleanup on failed start)#50
Merged
Merged
Conversation
…ture, cleanup on failed start When a runner failed to bootstrap, the action previously waited out the full registration timeout and left the instance running with no diagnostics. It now: - Phone-home tags: user-data tags the instance with its bootstrap phase (preparing → installing → creating-user → downloading → configuring → registered) and writes failed:<step> via an ERR trap. Best-effort — needs ec2:CreateTags on the instance role, degrades to timeout detection otherwise. - Fast-fail: the start wait loop (new src/wait.js) polls the tag alongside GitHub registration and fails within one interval naming the failing step. - Console capture: on fast-fail or timeout, GetConsoleOutput is fetched and the tail printed in a collapsible group, with the registration token redacted. - cleanup-on-start-failure (default true): terminate the instance after capturing diagnostics so failed starts don't leak billing. false preserves it and prints a ready-to-paste get-console-output/terminate command. Adds unit tests for buildUserData, the diagnostics helpers, and the wait loop (83 tests total). README troubleshooting + IAM docs and action.yml updated. Closes #41 Signed-off-by: kurok <22548029+kurok@users.noreply.github.com>
This was referenced Jul 2, 2026
kurok
added a commit
that referenced
this pull request
Jul 2, 2026
Adds CHANGELOG.md documenting the 4.0.0 capability wave (features #50-#59) and its breaking changes (ec2:CreateTags now always required; cleanup-on-start-failure defaults to terminate; DeleteOnTermination forced). Updates all README/docs/example usage snippets from @V3 to @v4 and adds a Changelog pointer. Signed-off-by: kurok <22548029+kurok@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #41 — first item in the roadmap (#49, Phase 1).
What & why
A failed bootstrap used to wait out the full 5-minute registration timeout, leave the instance running (billing leak), and give no diagnostics — you had to run
aws ec2 get-console-outputby hand. This makes the action diagnose failures itself.1. Phone-home bootstrap status (fast-fail)
buildUserData(extracted, now unit-tested) tags the instanceec2-github-runner:bootstrap=preparing → installing → creating-user → downloading → configuring → registered, and anERRtrap writesfailed:<step>on abort — in both the root and runner-user shells.src/wait.jswaitForRunnerReadypolls the tag alongside GitHub registration and fails within one poll interval, naming the step, instead of timing out.ec2:CreateTags(self-scoped) on the instance role; degrades to timeout detection with no error when absent. Read viaec2:DescribeTags.2. Console-output capture on failure
GetConsoleOutputis fetched, decoded, tailed (last 200 lines / 64 KiB), and printed in a collapsible group. The registration token is redacted from the output.3. Cleanup on failed start
cleanup-on-start-failure(defaulttrue): terminate after capturing diagnostics so failed starts don't leak billing.falsepreserves the instance and prints ready-to-pasteget-console-output/terminate-instancescommands.Tests
tests/userdata.test.js,tests/diagnostics.test.js,tests/wait.test.js— buildUserData phases/trap,getBootstrapStatus,getConsoleOutputTail(decode/tail/cap/redact),handleStartFailure(capture→terminate order, preserve mode, redaction), and the wait loop (fast-fail/timeout/success). 83 tests pass (was 52).Docs / IAM
cleanup-on-start-failureinput row, top-of-file callout updated.ec2:DescribeTags+ec2:GetConsoleOutputto the base policy; documented the self-scopedec2:CreateTagson the instance role.Compatibility
npm run packagedist rebuilt & committed (verify-dist green); lint clean.