|
| 1 | +# CI/CD Integration Troubleshooting |
| 2 | + |
| 3 | +This guide helps resolve common issues when using Hatch in Continuous Integration/Continuous Deployment (CI/CD) pipelines and other automated environments. |
| 4 | + |
| 5 | +## Common CI/CD Issues |
| 6 | + |
| 7 | +### Package Installation Hangs in Pipelines |
| 8 | + |
| 9 | +**Problem:** Hatch package installation commands hang indefinitely in CI/CD pipelines, causing builds to timeout. |
| 10 | + |
| 11 | +**Cause:** Hatch prompts for user consent before installing dependencies, but CI/CD environments cannot provide interactive input. |
| 12 | + |
| 13 | +**Solution:** Use one of the following approaches to enable automatic approval: |
| 14 | + |
| 15 | +#### Option 1: Environment Variable (Recommended) |
| 16 | +Set the `HATCH_AUTO_APPROVE` environment variable in your CI/CD configuration: |
| 17 | + |
| 18 | +```yaml |
| 19 | +# GitHub Actions example |
| 20 | +env: |
| 21 | + HATCH_AUTO_APPROVE: "1" |
| 22 | + |
| 23 | +# GitLab CI example |
| 24 | +variables: |
| 25 | + HATCH_AUTO_APPROVE: "true" |
| 26 | + |
| 27 | +# Jenkins pipeline example |
| 28 | +environment { |
| 29 | + HATCH_AUTO_APPROVE = "yes" |
| 30 | +} |
| 31 | +``` |
| 32 | + |
| 33 | +#### Option 2: CLI Flag |
| 34 | +Add the `--auto-approve` flag to your package installation commands: |
| 35 | + |
| 36 | +```bash |
| 37 | +hatch package add my_package --auto-approve |
| 38 | +hatch package add registry_package --version 1.0.0 --auto-approve |
| 39 | +``` |
| 40 | + |
| 41 | +#### Option 3: Automatic Detection |
| 42 | +Hatch automatically detects non-TTY environments and skips user prompts. This works out-of-the-box in most CI/CD systems without additional configuration. |
| 43 | + |
| 44 | +### Environment Variable Values |
| 45 | + |
| 46 | +The `HATCH_AUTO_APPROVE` environment variable accepts the following values (case-insensitive): |
| 47 | +- `1` |
| 48 | +- `true` |
| 49 | +- `yes` |
| 50 | + |
| 51 | +Any other value will be ignored, and normal prompting behavior will occur in TTY environments. |
| 52 | + |
| 53 | +## CI/CD Platform Examples |
| 54 | + |
| 55 | +### GitHub Actions |
| 56 | + |
| 57 | +```yaml |
| 58 | +name: Build and Test |
| 59 | +on: [push, pull_request] |
| 60 | + |
| 61 | +jobs: |
| 62 | + test: |
| 63 | + runs-on: ubuntu-latest |
| 64 | + env: |
| 65 | + HATCH_AUTO_APPROVE: "1" |
| 66 | + |
| 67 | + steps: |
| 68 | + - uses: actions/checkout@v3 |
| 69 | + - name: Set up Python |
| 70 | + uses: actions/setup-python@v4 |
| 71 | + with: |
| 72 | + python-version: '3.9' |
| 73 | + |
| 74 | + - name: Install Hatch |
| 75 | + run: pip install hatch |
| 76 | + |
| 77 | + - name: Install dependencies |
| 78 | + run: hatch package add ./my_package |
| 79 | +``` |
| 80 | +
|
| 81 | +### GitLab CI |
| 82 | +
|
| 83 | +```yaml |
| 84 | +variables: |
| 85 | + HATCH_AUTO_APPROVE: "true" |
| 86 | + |
| 87 | +test: |
| 88 | + image: python:3.9 |
| 89 | + script: |
| 90 | + - pip install hatch |
| 91 | + - hatch env create test-env |
| 92 | + - hatch package add ./my_package --env test-env |
| 93 | +``` |
| 94 | +
|
| 95 | +### Jenkins Pipeline |
| 96 | +
|
| 97 | +```groovy |
| 98 | +pipeline { |
| 99 | + agent any |
| 100 | + environment { |
| 101 | + HATCH_AUTO_APPROVE = "yes" |
| 102 | + } |
| 103 | + stages { |
| 104 | + stage('Install Dependencies') { |
| 105 | + steps { |
| 106 | + sh 'pip install hatch' |
| 107 | + sh 'hatch package add ./my_package' |
| 108 | + } |
| 109 | + } |
| 110 | + } |
| 111 | +} |
| 112 | +``` |
| 113 | + |
| 114 | +### Docker Builds |
| 115 | + |
| 116 | +```dockerfile |
| 117 | +FROM python:3.9 |
| 118 | + |
| 119 | +# Set environment variable for non-interactive installation |
| 120 | +ENV HATCH_AUTO_APPROVE=1 |
| 121 | + |
| 122 | +# Install Hatch |
| 123 | +RUN pip install hatch |
| 124 | + |
| 125 | +# Copy and install your package |
| 126 | +COPY . /app |
| 127 | +WORKDIR /app |
| 128 | +RUN hatch package add ./my_package |
| 129 | +``` |
| 130 | + |
| 131 | +## Troubleshooting Steps |
| 132 | + |
| 133 | +If you're still experiencing issues: |
| 134 | + |
| 135 | +1. **Verify Environment Detection:** |
| 136 | + Check if your CI/CD environment is properly detected as non-TTY: |
| 137 | + ```bash |
| 138 | + python -c "import sys; print('TTY:', sys.stdin.isatty())" |
| 139 | + ``` |
| 140 | + This should print `TTY: False` in CI/CD environments. |
| 141 | + |
| 142 | +2. **Test Environment Variable:** |
| 143 | + Verify the environment variable is set correctly: |
| 144 | + ```bash |
| 145 | + echo "HATCH_AUTO_APPROVE: $HATCH_AUTO_APPROVE" |
| 146 | + ``` |
| 147 | + |
| 148 | +3. **Enable Verbose Logging:** |
| 149 | + Add verbose logging to see what Hatch is doing: |
| 150 | + ```bash |
| 151 | + hatch package add ./my_package --verbose |
| 152 | + ``` |
| 153 | + |
| 154 | +4. **Check for Blocking Input:** |
| 155 | + If the process still hangs, check for other interactive prompts in your package installation process. |
| 156 | + |
| 157 | +## Best Practices |
| 158 | + |
| 159 | +1. **Use Environment Variables:** Set `HATCH_AUTO_APPROVE=1` in your CI/CD environment variables for consistent behavior across all commands. |
| 160 | + |
| 161 | +2. **Test Locally:** Test your CI/CD configuration locally using tools like `act` (for GitHub Actions) or Docker to simulate the CI environment. |
| 162 | + |
| 163 | +3. **Timeout Protection:** Set reasonable timeouts in your CI/CD configuration to prevent indefinite hanging: |
| 164 | + ```yaml |
| 165 | + # GitHub Actions |
| 166 | + timeout-minutes: 10 |
| 167 | + |
| 168 | + # GitLab CI |
| 169 | + timeout: 10m |
| 170 | + ``` |
| 171 | +
|
| 172 | +4. **Explicit Dependencies:** Consider using explicit dependency lists in your CI/CD scripts to make builds more predictable and faster. |
| 173 | +
|
| 174 | +## Related Documentation |
| 175 | +
|
| 176 | +- [CLI Reference - Environment Variables](../CLIReference.md#environment-variables) |
| 177 | +- [CLI Reference - Package Add Command](../CLIReference.md#hatch-package-add) |
| 178 | +- [Getting Started Guide](../GettingStarted.md) |
0 commit comments