pre-deploy-check

Type	Skill
Plugin	awl-cicd · v0.0.22
Invoke	/awl-cicd:pre-deploy-check
Tools	Read, Bash, Glob, Grep
Source	plugins/awl-cicd/skills/pre-deploy-check/SKILL.md

When Claude uses it

This skill should be used when the user asks to “check the deployment before merging”, “pre-deploy check”, “will this deploy work”, “verify deploy config”, “check gitlabSecrets”, “check ci variables”, “is the pipeline ready to merge”, “can I merge this”, or before merging any change to a deploy job or DEPLOYMENT_VALUES. Verifies an AWL autodeploy setup against the project’s GitLab state: referenced CI variables exist with the right scope, image-pull membership, protected branches, static DEPLOYMENT_VALUES rules, and pipeline lint. Reports blockers before ArgoCD turns red.

Trigger phrases: check the deployment before merging · pre-deploy check · will this deploy work · verify deploy config · check gitlabSecrets · check ci variables · is the pipeline ready to merge · can I merge this

Definition

Run before merging any change that touches deploy-* jobs, DEPLOYMENT_VALUES, or CI variables. Every check maps to a deployment that failed in a real project because nobody looked before merging.

Workflow

Step 1: run the automated checks

"${CLAUDE_PLUGIN_ROOT}/skills/pre-deploy-check/scripts/check-deploy.sh"

Run it from the project root. Options:

Option	Use
--file <path>	Pipeline file other than ./.gitlab-ci.yml
--project group/project	Check another project’s variables (skips lint)
--env <name>	Environment name(s) to require a scope for. Default: environment.name values found in the file, else staging testing production
--skip-lint	Skip glab ci lint

Exit code 1 means blockers. The script never prints variable values.

What it checks:

• Blockers (facts from the GitLab API or lint): every left-hand gitlabSecrets name exists, has a value for each environment (scope * or the environment name), is not hidden; unquoted numbers or booleans in configmap; glab ci lint passes.
• Warnings (AWL conventions that can change): comments inside DEPLOYMENT_VALUES, unmasked variables, image-pull not a Maintainer, main/testing/production not protected.
• Printed for manual review: the gitlabSecrets mappings as GITLAB_VAR -> POD_ENV.

The script header lists its assumptions (A1–A6) with the template commit they were verified against. When a warning contradicts what a current project does, check devops/ci-cd-templates and the ClickUp Natron Deployment guide first, then update the assumption in the script. The script is a snapshot of conventions; the templates are the source of truth.

Prerequisite: glab auth status is logged in to gitlab.appswithlove.net with Maintainer access to the project. A 404 from the script means missing access, not a missing project.

Step 2: review what the script can’t see

Read the deploy jobs in .gitlab-ci.yml and check by hand:

1. Mapping direction. gitlabSecrets is GITLAB_VARIABLE: POD_ENV. Compare the printed mappings with what the application reads (process.env.X, appsettings, .env.example). A swapped pair leaves the pod variable undefined.
2. environment: on every job that reads scoped variables. Build jobs that pass a scoped token as build arg need environment: { name: <env>, action: verify }.
3. healthz exists in the image being deployed. Grep the app for the route. /healthz and /api/healthz are different.
4. Name length. DEPLOYMENT_NAME + - + namespace + -in-cluster must stay under 53 characters.
5. Stop jobs match deploy jobs. If the deploy job overrides DEPLOYMENT_NAME, DEPLOYMENT_NAMESPACE, DEPLOYMENT_CLUSTER, or ARGO_INSTANCE, the matching stop-* job needs the same override.
6. Monorepo changes: rules. With app-dir, nothing deploys unless files under app-dir, .gitlab-ci.yml, or a watch path changed. Shared packages need watch.
7. New services or storage exist. A database, S3 bucket, or Redis referenced in configmap must be provisioned first (see natron-deployment).
8. Secrets are not duplicated across projects. A key copied from another project’s variables is a leak waiting to happen; use fetch-secrets or an instance variable.
9. Template revision. If the last green pipeline is older than the latest commit in devops/ci-cd-templates, run glab ci lint again; the contract may have changed.

Step 3: report

Summarize as a short table with three columns: check, result, action. Blockers first. Quote the script output lines for blockers instead of paraphrasing them.

If variables are missing, list the names and ask the user for the values or where they live (1Password item). Never guess or fabricate a value, never paste a value into chat or a commit. Set them with:

glab variable set NAME --scope '*' --masked

The command reads the value from stdin; let the user run it, or run it with the value piped from op read if the 1Password item reference is known.

Step 4: what a clean result means

Blockers 0 means the deploy job will most likely trigger and the ExternalSecret will sync. It does not prove the application starts (health check, migrations, runtime config) or that data is present. After the merge, watch the ArgoCD application and the deployment URL, and trigger any cron-driven import the app depends on.

Common results

Script output	Meaning	Fix
variable X is referenced ... but does not exist	ExternalSecret will fail with 404, ArgoCD red	Create the variable or remove the mapping
variable X has no value for environment 'staging'	Scope mismatch	Add a *-scoped value or match the job’s environment name
variable X is hidden	External Secrets can’t read hidden variables	Recreate as masked, not hidden
comment inside DEPLOYMENT_VALUES (warning)	Generator rejected comments until at least August 2026; a fix was announced	Move the comment above the variable unless DevOps confirmed the fix
configmap X: 5432 must be a quoted string	Helm fails with Cannot convert int64 to string	Quote it
image-pull user is not a Maintainer (warning)	With the current secret store pods can’t pull, secrets can’t sync	Add image-pull as Maintainer
cannot read project via glab	No Maintainer access for the token	Ask for project membership
branch production is not protected (warning)	Only matters once production is used	Protect it before the first production deploy

When the script and the infrastructure disagree

The GitLab API checks stay valid as long as autodeploy reads secrets from GitLab CI variables. Everything else encodes conventions of the Helm chart and the templates as of September 2026. Signs that an assumption expired:

• A project deploys fine with a construct the script warns about.
• A pipeline fails with yaml invalid although the script passed: the template contract changed, see the pinning note in gitlab-cicd.
• DevOps moved secrets out of GitLab (OPS-5463): the variable checks then need a new source.

In each case fix the assumption in scripts/check-deploy.sh, bump the verified commit in its header, and mention it in the MR. Don’t work around the script in the project pipeline.

The long-term home for these checks is the GitOps generator itself; a DevOps ticket asks for fail-fast validation there.

Additional resources

• scripts/check-deploy.sh: the automated checks. Read it before changing the static rules; the DEPLOYMENT_VALUES parser is indentation-based and assumes the | block style used by the AWL templates.
• deploying-to-kubernetes skill: the full pre-merge checklist and DEPLOYMENT_VALUES contract.
• natron-deployment skill: provisioning databases, storage, and ArgoCD operations.