Skip to content

Latest commit

 

History

History
226 lines (159 loc) · 8.62 KB

troubleshooting.md

File metadata and controls

226 lines (159 loc) · 8.62 KB

troubleshooting

"missing environment variables: ..."

the message names exactly which ones. locally, you probably didn't load the file:

set -a; source .env; set +a

in actions, the secret isn't set, or is set under a different name — the names are case-sensitive and must match setup exactly.

the run timed out while deleting

api2 is slow on this server and the operation may well have gone through anyway. check cpanel → domains before retrying: a blind retry can act twice.

"the domain ... does not belong to ..."

the subdomain isn't on the account — already deleted, a typo, or the wrong ROOT_DOMAIN. deleting a folder through cpanel's file manager can also remove the subdomain entry with it, so it may already be gone.

check what's actually there:

curl -s "https://$CPANEL_HOST:2083/execute/DomainInfo/list_domains" \
  -H "Authorization: cpanel $CPANEL_USER:$CPANEL_API_TOKEN" | python3 -m json.tool

https shows a certificate warning

expected until autossl has issued the subdomain's certificate — about a minute after creation. without a certificate of its own the subdomain is served the server's default one — which on a shared ip belongs to some other site entirely, so you may even get redirected somewhere unrelated. plain http:// still redirects correctly; it's only the certificate that's missing.

if it lasts, read SSL::get_autossl_problems (or run the create step with --autossl-wait); see ssl.

the subdomain doesn't resolve

the wildcard * record should make this immediate. check it still exists in namecheap, and confirm what dns is actually returning:

dig +short lab.example.com

if that's empty, it's dns, not the script — the subdomain can exist in cpanel and still not resolve.

the delete workflow failed before doing anything

the confirm field has to match the subdomain name exactly. that's the guard working: it runs before checkout, so nothing is installed and nothing is touched.

the folder is still there after deleting

--delete on its own leaves files alone by design. use --with-files, or delete the folder from the file manager.

if you did pass --with-files and it's still there, check ~/.trash — and remember it may have been renamed to <name>.1 if something with that name was already in the trash.

a run "succeeded" but nothing was deleted

fileop returns success for paths that don't exist, so a success line isn't proof by itself. verify directly:

curl -s -G "https://$CPANEL_HOST:2083/execute/Fileman/list_files" \
  -H "Authorization: cpanel $CPANEL_USER:$CPANEL_API_TOKEN" \
  -d "dir=." -d "types=dir" | python3 -m json.tool

the .htaccess step refused to run

it aborts rather than overwrite when it can't read the existing file — because saving replaces the file wholesale, and an unreadable file is not the same as an empty one. check the document root exists and the token can read it, then re-run.

"could not check index.html/index.php ... not writing the starter page"

same caution as the .htaccess step: not knowing whether an index file exists is different from knowing it doesn't, so the run stops rather than risk overwriting a real site. check the document root is readable, then re-run — --skip-starter-page if you'd rather skip it entirely.

setup_autodeploy warns "no posthog.init found in the repository's pages"

the target repo's html doesn't carry the snippet the starter page shipped with, so the first deploy will replace it and the subdomain stops reporting to PostHog. it's a warning, not a failure — the deploy still goes through. paste assets/posthog-snippet.html into the repo's <head> before (or after) the deploy to keep tracking it.

"could not update the Authorized URLs"

the PostHog step warns instead of failing, so the run still ends green. a 401 or 403 means POSTHOG_PERSONAL_API_KEY is wrong, expired, or lacks the project:write scope on the project; a 404 means POSTHOG_PROJECT_ID or POSTHOG_HOST points at the wrong place. there's no need to recreate the subdomain: add the url the warning names by hand in the project settings (authorized urls), and fix the key for next time.

namecheap

--with-dns-api is untested against a live api and the account doesn't meet namecheap's api requirements. if you hit an ip error, the machine's public ip has to be whitelisted in namecheap → api access — which is awkward from actions, where the runner's ip changes every run.

auto deploy: "repository non trovato (404)"

github answers 404 both for a repo that doesn't exist and for one the token can't see, so check the spelling and the token. a fine-grained pat has to list the target repo explicitly; a classic one needs repo.

auto deploy: the run stopped at the workflow file with a 403

the pat is missing the workflow scope (classic) or Workflows: write (fine-grained). github refuses writes under .github/workflows/ without it, even for a token that can write everywhere else in the repo.

the ftp account and the secrets already exist at that point — re-running after fixing the token will stop at the preflight, because the ftp account is now there. either delete it first:

python3 setup_autodeploy.py lab --repo you/lab --delete

or finish by hand with --skip-workflow-file, which prints the workflow for you to commit.

auto deploy: "l'account FTP ... esiste gia'"

the preflight found the account before creating anything, so nothing was touched. either pick another login with --ftp-user, or tear the old one down with --delete.

note the password isn't recoverable — cpanel doesn't return it. if you need the credentials for winscp, reset the password from cpanel → ftp accounts and update the FTP_PASSWORD secret to match, or just tear down and set up again.

auto deploy: it refused because deployTocPanel.yml exists

that repo was set up by hand from the confluence doc. adding a second workflow wouldn't replace the first — both would fire on every push and overwrite each other over ftp. delete the old file, then re-run.

auto deploy: "branch 'master' does not exist on ..."

the repo has commits, just not on that branch — its deploy branch is probably main. pass --branch (or the branch input) with the right name.

a repo with no commits at all doesn't end up here any more: it gets initialized instead, see an empty repo.

auto deploy: "could not fast-forward develop"

after initializing an empty repo, the run brings develop up to the commit that added the deploy workflow. if that fails it's only a warning — the deploy is set up either way — and develop is simply one commit behind. merge the production branch into it:

git switch develop
git merge master
git push

setup gitflow: 403 when changing the default branch

--default-develop changes a repository setting, which takes admin rights on the repo — a fine-grained pat needs Administration: write. the branches exist by then; fix the token and re-run, and only the missing step happens.

setup gitflow: "the repository already has commits but no 'master' branch"

the repo's production branch has another name — usually main. pass it with --branch main, or the branch input.

auto deploy: the site deployed to the wrong folder

the ftp account's home is where server-dir: ./ resolves to. if the account was created with a --dir that isn't the subdomain's document root, files land somewhere nothing serves. check what cpanel thinks the document root is:

curl -s -G "https://$CPANEL_HOST:2083/execute/DomainInfo/domains_data" \
  -H "Authorization: cpanel $CPANEL_USER:$CPANEL_API_TOKEN" \
  -d "format=list" | python3 -m json.tool

the deploy failed at checkout with "Repository not found"

on a private repo that usually means the workflow's permissions block doesn't grant contents: read, not that the repo is missing — actions/checkout reads through GITHUB_TOKEN, and with no permissions it gets a 404 that reads like a typo. workflows generated before this was fixed have permissions: {}; re-run with --force to replace the file.

a deploy ran the moment i set it up

expected. the workflow triggers on pushes to the branch, and the commit that adds it is one. use --skip-workflow-file if you want to control when the first deploy happens.

seeing what a run actually did

gh run list --workflow=create-subdomain.yml --limit 5
gh run list --workflow=setup-autodeploy.yml --limit 5
gh run list --workflow=setup-gitflow.yml --limit 5
gh run view <run-id> --log

or just add dry_run and read the plan before committing to it.