Add install script for client repo setup #1
Open
mikemindel wants to merge 26 commits intochriswickett:mainfrom
Open
Add install script for client repo setup #1mikemindel wants to merge 26 commits intochriswickett:mainfrom
mikemindel wants to merge 26 commits intochriswickett:mainfrom
Conversation
The manual setup instructions (inline YAML, PAT steps, env var tables) are now handled by bin/install. The README becomes a high-level guide: what agentic does, how to set it up, and how the PR loop works. - Move Repo Setup to the top as the first section - Replace inline workflow YAML with template reference table - Trim Bot Identity from 38 lines to 4 - Remove duplicate env var inheritance section - Add diagnostics and custom env var sections - Rewrite opening paragraph in clear-speak - Remove completed TODO item
Interactive setup script that automates the full client repo onboarding: repo creation, settings, workflow files, secrets, bot collaborator access, and CLAUDE.md template. - bin/install: main script with interactive prompts - bin/prerequisites: gate that explains bot account + PAT setup - bin/diagnostics: verifies a client repo is wired up correctly - templates/workflows/: 4 thin caller workflow templates using __AGENTIC_REPO__ placeholder for composite action references
Colors and helpers were duplicated across install, prerequisites, and diagnostics. A single source file makes them easier to maintain and keeps the scripts focused on their own logic. - Create bin/lib/common.sh with colors and helpers - Source it from install, prerequisites, and diagnostics - Diagnostics keeps local overrides for checklist format
The monolithic install script (310 lines) made it impossible to re-run a single step after a mid-run failure. Each section is now its own script in bin/steps/, sourced by a slim orchestrator. A require_vars guard in common.sh lets each step validate its inputs and fail fast — steps also work standalone via env vars (e.g. FULL_REPO=acme/app bin/steps/settings). - Add require_vars helper to bin/lib/common.sh - Create 7 step scripts: repo, settings, workflows, secrets, collaborator, claude-md, commit-push - Rewrite bin/install as ~40-line orchestrator that sources steps
The script previously pushed without asking. Now it shows staged files and asks Push to main? [Y/n] before proceeding. Declining leaves files staged but uncommitted so you can inspect or adjust.
The interactive prompts made it impossible to re-run the install from CI or to skip questions you've already answered. The --repo and --path flags bypass the repo selection step, and -y skips all remaining prompts (secrets, collaborator, CLAUDE.md, push confirm). - Add flag parser to bin/install (--repo, --path, -y) - Skip interactive prompts in steps/repo when both vars are set - Gate prompts in secrets, collaborator, claude-md, commit-push on NONINTERACTIVE flag - Document non-interactive usage in README
Running install against a repo that already has workflow files would silently clobber them. Now it lists existing files and asks Overwrite? [y/N] before proceeding. Non-interactive mode (-y) overwrites automatically with a log message.
Previously you had to remember to run bin/diagnostics manually after setup. Now the install orchestrator runs it automatically to verify settings, workflows, secrets, and bot access are all wired up correctly.
Multi-line echo sequences are harder to read and maintain than heredocs. Converted the display blocks in install, collaborator, and secrets to cat << EOF for clearer formatting.
Flat procedural blocks replaced with named functions so readers can scan intent without parsing implementation. Shared helpers added to common.sh: - require_commands, require_gh_auth, detect_remote Local functions extracted in: - diagnostics: 7 check functions, main body is now a checklist - collaborator: add_collaborator, accept_invitation - workflows: find_existing_workflows, confirm_overwrite, render_templates - commit-push: commit_and_push
A single grab-bag file made it hard to know what you were sourcing. Two focused files let the source line communicate intent: output.sh for colors and messages, guards.sh for precondition checks and environment detection. - output.sh: colors, info, ok, warn, err - guards.sh: sources output.sh, adds require_vars, require_commands, require_gh_auth, detect_remote - diagnostics and prerequisites source output.sh directly - All other scripts source guards.sh
Diagnostics hardcoded four workflow names while the install step iterated the templates directory. Adding a fifth workflow template would silently skip the diagnostics check. - Iterate templates/workflows/*.yml instead of a fixed list - Same source of truth as bin/steps/workflows
Sed treats & as "matched text" and \ as escape in the replacement string. If AGENTIC_REPO ever contained these characters, the rendered YAML would be silently corrupted. - Escape \ and & before passing to sed replacement
The --silent flag suppressed both the response body and error messages. A permissions failure would kill the script with no explanation of what went wrong. - Redirect stdout to suppress success JSON - Let stderr through for gh error details - Add explicit error message on failure
The non-interactive path and the "skip" path both printed the same gh secret/variable set commands with slightly different formatting. Now both call print_manual_commands with their own intro message. - Extract print_manual_commands function - Non-interactive path also gets the setup-token hint and Secrets/Variables headings it was missing
The success message hardcoded "4 files" which would be wrong if a template were added or removed.
The && short-circuit on the last loop iteration leaked a non-zero exit code when no matching file existed. This became the function's return value, which set -e caught and killed the script silently after "Writing workflow files...". The pattern was safe inline but broke when extracted into a function — the function's exit status matters under set -e. - Replace [[ -f ]] && append with if/then/fi which always returns 0 from the if statement
Setting up multiple client repos meant re-typing the same 4 secrets each time. Now drop a .env in the agentic root and the install script picks it up — no prompts, no typos. - bin/install sources .env before running steps - bin/steps/secrets checks env vars before prompting - bin/diagnostics uses AGENTIC_BOT_TOKEN from env if available - Add .env.example with the 4 required values - Document .env usage in README
The prerequisites wall of text explains how to create a bot account and get an OAuth token. When .env already has all 4 values, the user has done this — no need to ask again. - Source .env and check all 4 values before showing the prompt - Skip silently in non-interactive mode when .env is missing
Diagnostics runs as a subprocess, so it doesn't inherit env vars from the parent install script. Source .env directly so the bot access check uses AGENTIC_BOT_TOKEN without prompting.
Users had to manually look up the bot's GitHub username and noreply email. Both can be derived from the bot token via the GitHub API, cutting the setup from 4 values to 2. - Add derive_bot_identity to secrets step (gh api /user) - Prerequisites now only checks for the 2 tokens - Update .env.example and README to reflect 2 required values - Remove 'note the noreply email' from prerequisites text
gh repo create --clone tries to add an origin remote in the current directory. When running bin/install from inside the agentic repo, origin already exists and the command fails. Split into two steps: create the repo, then clone it into a subdirectory.
When re-running after a failure, the target directory may already exist from the previous attempt. Instead of failing on clone, check for the directory first and reuse it. Applies to both the 'create new repo' and 'clone existing repo' paths.
The directory-exists check was duplicated across the 'create new' and 'clone existing' paths. One function handles both.
mikemindel
force-pushed
the
install-script
branch
2 times, most recently
from
1b3f0f5 to
a922076
Compare
The key insight — workflows are installed once, actions update automatically via @main — was buried in the .env section. Moved it to the workflow templates section and expanded it so readers understand why the system is structured this way.
chriswickett
force-pushed
the
main
branch
2 times, most recently
from
9d26c30 to
5dfbabf
Compare
Owner
|
Love this. The install script, diagnostics, step architecture, The architecture has moved on since this was branched though — main now uses a single dispatch workflow ( Can you rebase and adapt for the dispatch pattern?
The README from this PR can't merge as-is since it documents the old architecture, so that'll need rewriting against what's on main now. Thoughts? |
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
2 participants
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.
Interactive script that sets up a client repo with agentic workflows end-to-end:
prerequisites check, repo creation/connection, settings configuration, workflow
file templating, secrets/variables, bot collaborator access, CLAUDE.md scaffold,
and commit-push — plus a diagnostics tool to verify the result.
The installed workflow files are thin callers — they contain only triggers and
job configuration. The actual logic lives in this repo's composite actions,
referenced via
uses: <agentic-repo>/.github/actions/<action>@main. When theagentic repo's actions are updated, all client repos pick up the changes
automatically on the next workflow run. No reinstall needed.
bin/installorchestrates the full setup as sourced stepsbin/diagnosticschecks auth, settings, workflows, secrets, variables, and bot accessbin/lib/output.shandbin/lib/guards.shprovide shared helpers--repo/--pathflags for non-interactive use and resuming after failure