#Action/PR debugging

Use this page when you fired an Action and the expected change didn't reach your repository, or an ActionRun is stuck.

#Diagnose the GitHub App first

Most PR-trigger failures trace back to the GitHub App: it isn't configured on the server, the installation doesn't cover the target repo, or the org has no installation. Run the built-in smoke check before digging into Action YAML:

terrantula github diagnose --org-id <org-id>

It runs these checks and prints a per-check pass/fail summary (add --json for a machine-readable report; exit code is non-zero if any check fails):

• CLI authenticated to the configured base URL.
• Server-side GitHub App configured — fails if the server reports the App isn't configured.
• Installations found — lists installations for the org.
• Granted repos per installation — confirms the App can see the repo your Action targets.

See the GitHub App reference for installation details.

#An Action fired but no PR appeared

Work down this list — the cause is usually one of these, in rough order of likelihood.

#The ActionRun failed before opening the PR

Cause — parameter validation, a missing recommendation, an interpolation error, or a missing secret can fail the run before the PR step. Terrantula validates parameters, evaluates conditions, and runs placement first.

Fix — inspect the ActionRun's status and error. The run record is your audit trail: it captures who fired what, the parameters, and how it ended. A failed run with an error mentioning a parameter or recommendations field means the PR step was never reached.

#A{{ … }} interpolation didn't resolve

Symptom — the PR opens with a literal {{ … }} in the title/body/path, or the run fails with an interpolation error.

Cause — the template references a value that isn't in scope: a parameter the operator didn't supply, a recommendations.<name> that returned nothing, or a secret name that doesn't exist.

Fix — confirm every {{ parameters.* }} maps to a declared parameter, every {{ recommendations.<name>.* }} matches a recommendation name that actually resolved (an empty cell yields no recommendation), and every {{ secrets.<name> }} references a declared, value-set secret. See Interpolation.

#The PR auth token is missing or under-scoped

Symptom — the run fails at the PR step with a GitHub auth or permission error.

Cause — the pull-request trigger's auth.token references a secret that's unset, or the token can't push a branch / open a PR on the target repo.

Fix — declare the secret and set its value (the value is encrypted at rest and never logged — you reference it by name only):

terrantula secrets set-value github-token --value "$GITHUB_TOKEN"

Confirm the token (PAT or GitHub App token) can write to trigger.repo. If you use the GitHub App path, github diagnose confirms repo access.

#The trigger targets a repo the App can't see

Cause — trigger.repo (often interpolated from a parameter like {{ parameters.target_repo }}) names a repo outside the installation's granted set.

Fix — grant the repo to the installation, or correct the repo value. Run github diagnose to confirm the granted-repos list.

#Delivery failed (webhook trigger)

Symptom — for a webhook trigger, the ActionRun error carries a [delivery] prefix.

Cause — Terrantula couldn't deliver the outbound POST: a 4xx (other than 429) fails immediately; 5xx/429/network errors retry with backoff then fail. A [delivery] prefix distinguishes a delivery failure from a failure your downstream workflow reported back via the callback.

Fix — fix the target URL/auth for a 4xx; for repeated 5xx, the downstream endpoint is the problem. See the webhook trigger docs.

#An ActionRun is stuckrunning

#The PR merged but the run never completed

Symptom — the PR (or TFC run) finished, but the ActionRun stays running and the entity never transitions to active.

Cause — auto-completion needs a callback. For PR triggers, that's a GitHub webhook with the action's webhookSecret. If webhookSecret is omitted, or the repo has no webhook pointing at Terrantula, the merge isn't observed.

Fix

1. Set webhookSecret: "{{ secrets.github-webhook-secret }}" on the trigger and configure a GitHub webhook on the repo pointing to POST /webhooks/github with that secret. Terrantula verifies X-Hub-Signature-256 per-PR using the action-specific secret — there's no global webhook config.
2. Without auto-completion, transition the run manually (via the entity/relationship API) or have a GitHub Actions workflow POST to the run's callback URL.
3. If neither happens, the reaper times the run out after the Action's timeout (default 60 minutes) and marks it failed.

#A TFC trigger transitioned too early (or too late)

Cause — with autoApply: false (the default), Terrantula treats the TFC run as complete when it reaches planned — before infrastructure is provisioned. The entity transitions to onSuccess at plan time.

Fix — if the entity must only go active after a real apply, set autoApply: true so completion waits for the applied status. See the Terraform Cloud trigger details.

#Where to look

• The ActionRun carries the trigger metadata: for PR triggers { prNumber, prUrl, repo }, for TFC { runId, runUrl, … }. Use it to jump straight to the PR/run.
• terrantula github diagnose --org-id <id> --json for a scriptable App health report.
• Set TERRANTULA_DEBUG=1 to see the full API error body on any failing CLI call.

#Related

• Action triggers reference — every trigger type (webhook, pull-request, TFC, Atmos workflow, Atlantis) and its fields.
• GitHub App reference — App configuration and installation.
• Wire an Action — how an Action ties parameters → placement → operation → trigger.
• Action — the Action schema.
• Common errors — auth and apply failures that also block Actions.