Skip to content

Bash Runner Modules

This document describes the bash runner system that orchestrates GitTinkerer. It covers execution flow, module responsibilities, environment variables, payload parsing, and failure artifacts.

Flow of Modules

graph TD
  A[CLI args
  lib/args.sh] --> B[Env + secrets
  lib/env.sh]
  B --> C[Payload parse
  lib/payload.sh]
  C --> D[Artifacts init
  lib/artifacts.sh]
  D --> E[Workspace prep
  lib/workspace.sh]
  E --> F[Codex run
  lib/codex.sh]
  F --> G[Diff/commit/push
  lib/git.sh]
  F --> H[Metrics
  lib/metrics.sh]
  G --> H
  F --> I[Reply selector]
  G --> I
  I --> J[PR reply
  lib/reply/github.sh]
  I --> K[Web reply
  lib/reply/web.sh]
  B --> L[Logging
  lib/log.sh]
  B --> M[Sentry
  lib/sentry.sh]
  L -. errors .-> D
  M -. optional alerts .-> D

Run Lifecycle (sequence)

sequenceDiagram
  participant CLI as bin/gittinkerer
  participant Args as args.sh
  participant Env as env.sh
  participant Payload as payload.sh
  participant Art as artifacts.sh
  participant WS as workspace.sh
  participant Codex as codex.sh
  participant Git as git.sh
  participant Reply as reply (github/web)
  participant Metrics as metrics.sh
  participant Sentry as sentry.sh
  participant Log as log.sh

  CLI->>Args: parse_args()
  Args->>Env: load_env()
  Env-->>Log: logging configured
  Env-->>Sentry: DSN (optional)
  Env->>Payload: parse_payload()
  Payload-->>Metrics: PAYLOAD_RUN_ID
  Payload->>Art: init_artifacts()
  Art->>WS: workspace_dir prepared
  WS->>Codex: run_codex_operations()
  Codex->>Metrics: record_token/seconds
  Codex->>Git: run_git_operations()
  Git->>Reply: publish reply (PR/web)
  Reply-->>Metrics: flush_metrics()
  Git-->>Sentry: on push/commit failures
  Note over Art,Reply: write_failure_artifacts on any stage error

Module Reference

  • lib/args.sh: CLI entry; enforces run command, required --payload-file, optional --workspaces-dir, --artifacts-dir, --timestamp, --dry-run.
  • lib/env.sh: Loads .env, sets REPO_ROOT, default git identity, normalizes ARTIFACTS_DIR/WORKSPACES_DIR, requires GITHUB_TOKEN.
  • lib/payload.sh: Validates JSON schema (source in {pr,web}); extracts repo/PR/web/run fields; exports PAYLOAD_* variables using node helpers.
  • lib/artifacts.sh: Creates run folder at ARTIFACTS_DIR/<timestamp>/agent-run; seeds prompt.txt, pr_comment.txt, diff.patch, files_changed.json, commit_sha.txt, summary.md.
  • lib/workspace.sh: Validates clone URL, clones or fetches repo into WORKSPACES_DIR/<safe_name>, checks out/pulls target ref (PAYLOAD_PR_HEAD_REF or main).
  • lib/codex.sh: Builds prompt from comment + repo + contract; runs codex exec --sandbox danger-full-access; writes summary.md; records prompt tokens and completion seconds.
  • lib/git.sh: Generates diff.patch and files_changed.json, computes DIFF_LOC, commits with truncated comment-derived message, pushes to PAYLOAD_PR_HEAD_REF or main unless DRY_RUN.
  • lib/metrics.sh: Estimates prompt tokens, calculates diff LOC, queues metrics and POSTs to $SERVICE_URL/api/runs/$PAYLOAD_RUN_ID/metrics with RUNNER_METRICS_TOKEN.
  • lib/sentry.sh: Builds Sentry store URL from SENTRY_DSN; sends events tagged with run/repo/PR/source/stage.
  • lib/log.sh: Sanitizes secrets; emits timestamped INFO/WARN/ERROR/DEBUG; forwards ERRORs to Sentry when configured.
  • lib/reply/github.sh: Posts CODEX_RESPONSE as PR comment (skips on DRY_RUN); targets issues/<PR>/comments endpoint.
  • lib/reply/web.sh: Sends CODEX_RESPONSE to $SERVICE_URL/api/runs/$PAYLOAD_RUN_ID/reply (skips on DRY_RUN).

Environment Variables (concise)

Module Inputs (expected) Outputs/Exports
args CLI flags populate PAYLOAD_FILE, WORKSPACES_DIR_ARG, ARTIFACTS_DIR_ARG, TIMESTAMP_ARG, DRY_RUN same exported
env GITHUB_TOKEN, optional .env, ARTIFACTS_DIR_ARG, WORKSPACES_DIR_ARG REPO_ROOT, ARTIFACTS_DIR, WORKSPACES_DIR, git identity vars, GITHUB_TOKEN
payload PAYLOAD_FILE, node PAYLOAD_SOURCE, PAYLOAD_REPO_FULL_NAME, PAYLOAD_REPO_CLONE_URL, PAYLOAD_COMMENT_BODY, PAYLOAD_COMMENT_RAW_BODY, PR fields, PAYLOAD_WEB_CONVERSATION_ID, PAYLOAD_RUN_ID
artifacts ARTIFACTS_DIR, TIMESTAMP_ARG, PAYLOAD_COMMENT_BODY, PAYLOAD_COMMENT_RAW_BODY ARTIFACTS_RUN_DIR; seeded artifacts files
workspace PAYLOAD_REPO_CLONE_URL, PAYLOAD_REPO_FULL_NAME, PAYLOAD_PR_HEAD_REF, WORKSPACES_DIR WORKSPACE_DIR
codex WORKSPACE_DIR, ARTIFACTS_RUN_DIR, PAYLOAD_COMMENT_BODY, PAYLOAD_REPO_FULL_NAME CODEX_PROMPT, CODEX_RESPONSE, CODEX_COMPLETION_SECONDS
git WORKSPACE_DIR, ARTIFACTS_RUN_DIR, PAYLOAD_COMMENT_BODY, PAYLOAD_PR_HEAD_REF, git identity vars, DRY_RUN DIFF_PATCH, FILES_CHANGED_JSON, DIFF_LOC, COMMIT_SHA
metrics PAYLOAD_RUN_ID, RUNNER_METRICS_TOKEN, SERVICE_URL, ARTIFACTS_RUN_DIR publishes metrics; clears queue
sentry SENTRY_DSN, optional PAYLOAD_*, USER sends events (no exported vars)
log optional DEBUG, optional Sentry function sanitized log output
reply/github PAYLOAD_SOURCE=pr, GITHUB_TOKEN, PAYLOAD_PR_NUMBER, PAYLOAD_REPO_FULL_NAME, CODEX_RESPONSE, DRY_RUN PR comment (id logged)
reply/web PAYLOAD_SOURCE=web, PAYLOAD_RUN_ID, CODEX_RESPONSE, SERVICE_URL, DRY_RUN web reply confirmation

Payload Parsing Examples

  • Schema enforcement: validate_payload_schema requires source in {pr,web}, repo.full_name, repo.clone_url, comment_body, plus pr.number/head_ref/head_sha for PRs or web.web_conversation_id for web runs (see lib/payload.sh).
  • Extraction pattern: 
    PAYLOAD_SOURCE="$(json_get "$PAYLOAD_FILE" "source")"
PAYLOAD_REPO_FULL_NAME="$(json_get "$PAYLOAD_FILE" "repo.full_name")"
PAYLOAD_PR_NUMBER="$(json_get "$PAYLOAD_FILE" "pr.number" 2>/dev/null || true)"
PAYLOAD_WEB_CONVERSATION_ID="$(json_get "$PAYLOAD_FILE" "web.web_conversation_id" 2>/dev/null || true)"
  • Guard rails: exits with code 2 on missing fields/invalid JSON; exits with code 1 if node is absent; rejects empty payload files; logs validation errors.

Failure Artifacts and Error Handling

  • Initialization: init_artifacts creates ARTIFACTS_RUN_DIR and seeds prompt.txt, pr_comment.txt, diff.patch, files_changed.json, commit_sha.txt, summary.md with Status: running (see lib/artifacts.sh).
  • Failure path: write_failure_artifacts <stage> <message> sanitizes secrets, ensures core files exist, writes summary.md with Status: failed and Failed stage: <stage>, then forwards the sanitized message to Sentry when configured.
  • Common callers: workspace validation/clone/pull, Codex invocation, diff/commit/push, replies, and any missing prerequisites call write_failure_artifacts before exiting non-zero.
  • Logging: log_error redacts tokens/secrets/passwords and sends Sentry events on ERROR when DSN is set.

Notes on Replies and Metrics

  • Reply routing: publish_github_reply handles PR sources; publish_web_reply handles web sources; both honor DRY_RUN and fail via artifacts on API errors.
  • Metrics: record_metric queues numeric values; flush_metrics POSTs them to the service using RUNNER_METRICS_TOKEN; token or run-id missing causes a logged skip, not a hard failure.