Overview
envcheck uses standard Unix exit codes to indicate the validation results. These exit codes are essential for integrating envcheck into CI/CD pipelines, scripts, and automated workflows.
Exit Code Reference
0 - Success
Meaning: All validations passed or only warnings were found.
When it occurs:
- All checks passed successfully
- Some non-critical warnings were found, but no errors
Example scenarios:
# All checks pass
$ envcheck
✓ All checks passed!
$ echo $?
0
# Warnings present but no errors
$ envcheck
⚠ 2 warning(s) found, but you can proceed.
$ echo $?
0
- Pipeline should continue
- Deployment can proceed
- No action required
1 - Validation Failure
Meaning: One or more validation checks failed with errors.
When it occurs:
- Required tools are missing or have incorrect versions
- Required environment variables are not set
- Required ports are unavailable
- Required files do not exist
- Network endpoints are unreachable or return unexpected status codes
Example scenarios:
# Required tool missing
$ envcheck
✗ node not found
❌ 1 issue(s) found. Fix them to continue.
$ echo $?
1
# Version mismatch
$ envcheck
✗ node version 16.14.0 does not satisfy >=18.0.0
❌ 1 issue(s) found. Fix them to continue.
$ echo $?
1
# Port in use
$ envcheck
✗ Port 3000 is already in use
❌ 1 issue(s) found. Fix them to continue.
$ echo $?
1
- Pipeline should fail
- Deployment should be blocked
- Errors must be fixed before proceeding
Implementation Details
The exit code logic is implemented in src/reporter.rs:92-98:
pub fn exit_code(&self) -> i32 {
if self.has_errors() {
1
} else {
0
}
}
has_errors() method checks if any validation result has an Error status:
pub fn has_errors(&self) -> bool {
self.results.iter().any(|r| matches!(r.status, ValidationStatus::Error))
}
Validation Status Levels
envcheck uses three validation status levels that affect the exit code:
Success
- Validation check passed
- Does not affect exit code
- Displayed with ✓ symbol
Warning
- Non-critical issue detected
- Does not cause exit code 1
- Displayed with ⚠ symbol
- Includes optional suggestions for improvement
Error
- Critical validation failure
- Causes exit code 1
- Displayed with ✗ symbol
- Includes optional suggestions for remediation
Using Exit Codes in Scripts
Bash Script
#!/bin/bash
envcheck
if [ $? -eq 0 ]; then
echo "Environment is ready"
npm start
else
echo "Environment validation failed"
exit 1
fi
CI/CD Pipeline Examples
GitHub Actions
name: Validate Environment
on: [push, pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Run envcheck
run: |
envcheck
# Exits with code 1 if validation fails
- name: Deploy
if: success()
run: ./deploy.sh
GitLab CI
validate-environment:
stage: test
script:
- envcheck
# Job fails if exit code is non-zero
deploy:
stage: deploy
script:
- ./deploy.sh
needs:
- validate-environment
CircleCI
version: 2.1
jobs:
validate:
docker:
- image: cimg/base:stable
steps:
- checkout
- run:
name: Validate environment
command: envcheck
# Step fails if exit code is 1
workflows:
build-and-deploy:
jobs:
- validate
- deploy:
requires:
- validate
JSON Output and Exit Codes
When using --json flag, the exit code behavior remains the same:
$ envcheck --json
{
"results": [...],
"summary": {
"errors": 1,
"warnings": 0,
"successes": 2
},
"passed": false
}
$ echo $?
1
passed field in JSON output indicates whether the exit code will be 0 (true) or 1 (false).
Best Practices
Use exit codes in automation:
- Always check exit codes in scripts and pipelines
- Fail fast when exit code is 1
- Log results for debugging failed validations
Warning status does not fail:
Remember that warnings do not cause a non-zero exit code. If you need warnings to fail your pipeline, you’ll need to parse the JSON output and check the warning count.
# Fail on warnings
RESULT=$(envcheck --json)
WARNINGS=$(echo $RESULT | jq '.summary.warnings')
if [ $WARNINGS -gt 0 ]; then
echo "Warnings are not allowed in production"
exit 1
fi
