0
# CI Integration
1

2
Cibuildwheel provides built-in support for major CI/CD platforms with platform-specific optimizations and output formatting.
3

4
## Capabilities
5

6
### CI Provider Detection
7

8
Automatic detection of the current CI/CD platform.
9

10
```python { .api }
11
class CIProvider(Enum):
12
    travis_ci = "travis"
13
    circle_ci = "circle_ci" 
14
    azure_pipelines = "azure_pipelines"
15
    github_actions = "github_actions"
16
    gitlab = "gitlab"
17
    cirrus_ci = "cirrus_ci"
18
    appveyor = "appveyor"
19
    other = "other"
20

21
def detect_ci_provider() -> CIProvider | None:
22
    """
23
    Detect the current CI provider based on environment variables.
24
    
25
    Returns:
26
        CIProvider enum value for detected provider, or None if not detected
27
    """
28
```
29

30
### Output Formatting
31

32
CI-specific output formatting and ANSI code handling.
33

34
```python { .api }
35
def fix_ansi_codes_for_github_actions(text: str) -> str:
36
    """
37
    Fix ANSI escape codes for proper display in GitHub Actions logs.
38
    
39
    Args:
40
        text: Text containing ANSI escape codes
41
        
42
    Returns:
43
        Text with ANSI codes adjusted for GitHub Actions
44
    """
45

46
def filter_ansi_codes(text: str, /) -> str:
47
    """
48
    Remove ANSI escape codes from text.
49
    
50
    Args:
51
        text: Text containing ANSI escape codes
52
        
53
    Returns:
54
        Text with ANSI codes removed
55
    """
56
```
57

58
## Supported CI Platforms
59

60
### GitHub Actions
61

62
Native first-class support with specialized output formatting.
63

64
**Configuration:**
65
```yaml
66
name: Build wheels
67

68
on: [push, pull_request]
69

70
jobs:
71
  build_wheels:
72
    name: Build wheels on ${{ matrix.os }}
73
    runs-on: ${{ matrix.os }}
74
    strategy:
75
      matrix:
76
        os: [ubuntu-latest, windows-latest, macos-latest]
77

78
    steps:
79
      - uses: actions/checkout@v4
80

81
      - uses: actions/setup-python@v4
82
        with:
83
          python-version: '3.11'
84

85
      - name: Install cibuildwheel
86
        run: python -m pip install cibuildwheel
87

88
      - name: Build wheels
89
        run: python -m cibuildwheel --output-dir wheelhouse
90

91
      - uses: actions/upload-artifact@v4
92
        with:
93
          name: wheels
94
          path: ./wheelhouse/*.whl
95
```
96

97
**Features:**
98
- Automatic ANSI code adjustment for log readability
99
- Matrix build support for multiple platforms
100
- Artifact upload integration
101
- Environment variable detection
102

103
### Azure Pipelines
104

105
Full support with multi-platform build capabilities.
106

107
**Configuration:**
108
```yaml
109
trigger:
110
- main
111

112
pool:
113
  vmImage: 'ubuntu-latest'
114

115
strategy:
116
  matrix:
117
    linux:
118
      imageName: 'ubuntu-latest'
119
    mac:
120
      imageName: 'macOS-latest'  
121
    windows:
122
      imageName: 'windows-latest'
123

124
steps:
125
- task: UsePythonVersion@0
126
  inputs:
127
    versionSpec: '3.11'
128

129
- script: python -m pip install cibuildwheel
130
  displayName: 'Install cibuildwheel'
131

132
- script: python -m cibuildwheel --output-dir wheelhouse
133
  displayName: 'Build wheels'
134

135
- task: PublishBuildArtifacts@1
136
  inputs:
137
    pathToPublish: 'wheelhouse'
138
    artifactName: 'wheels'
139
```
140

141
### Travis CI
142

143
Support for Linux and Windows builds.
144

145
**Configuration:**
146
```yaml
147
language: python
148
python: "3.11"
149

150
services:
151
  - docker
152

153
matrix:
154
  include:
155
    - os: linux
156
      python: "3.11"
157
    - os: windows
158
      language: shell
159
      python: "3.11"
160

161
install:
162
  - python -m pip install cibuildwheel
163

164
script:
165
  - python -m cibuildwheel --output-dir wheelhouse
166

167
deploy:
168
  provider: releases
169
  api_key: $GITHUB_TOKEN
170
  file_glob: true
171
  file: wheelhouse/*.whl
172
  skip_cleanup: true
173
  on:
174
    tags: true
175
```
176

177
### CircleCI
178

179
Docker-based builds with caching support.
180

181
**Configuration:**
182
```yaml
183
version: 2.1
184

185
orbs:
186
  python: circleci/python@2.0.3
187

188
jobs:
189
  build-wheels:
190
    docker:
191
      - image: cimg/python:3.11
192
    steps:
193
      - checkout
194
      - setup_remote_docker:
195
          version: 20.10.7
196
      - python/install-packages:
197
          pkg-manager: pip
198
          pip-dependency-file: requirements.txt
199
      - run:
200
          name: Install cibuildwheel
201
          command: python -m pip install cibuildwheel
202
      - run:
203
          name: Build wheels
204
          command: python -m cibuildwheel --output-dir wheelhouse
205
      - store_artifacts:
206
          path: wheelhouse
207

208
workflows:
209
  build-and-test:
210
    jobs:
211
      - build-wheels
212
```
213

214
### GitLab CI
215

216
Docker-based builds with GitLab-specific features.
217

218
**Configuration:**
219
```yaml
220
image: python:3.11
221

222
stages:
223
  - build
224

225
variables:
226
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
227

228
cache:
229
  paths:
230
    - .cache/pip/
231
    - venv/
232

233
build-wheels:
234
  stage: build
235
  services:
236
    - docker:dind
237
  variables:
238
    DOCKER_DRIVER: overlay2
239
  before_script:
240
    - python -m pip install cibuildwheel
241
  script:
242
    - python -m cibuildwheel --output-dir wheelhouse
243
  artifacts:
244
    paths:
245
      - wheelhouse/
246
    expire_in: 1 week
247
```
248

249
### Cirrus CI
250

251
Flexible cloud-based CI with multiple platform support.
252

253
**Configuration:**
254
```yaml
255
task:
256
  name: Build wheels
257
  compute_engine_instance:
258
    image_project: cirrus-images
259
    image: family/docker-builder
260
    platform: linux
261
    cpu: 4
262
    memory: 8G
263

264
  install_script:
265
    - python -m pip install cibuildwheel
266

267
  build_script:
268
    - python -m cibuildwheel --output-dir wheelhouse
269

270
  wheels_artifacts:
271
    path: "wheelhouse/*"
272
```
273

274
### AppVeyor
275

276
Windows-focused CI with Visual Studio integration.
277

278
**Configuration:**
279
```yaml
280
image: Visual Studio 2019
281

282
environment:
283
  matrix:
284
    - PYTHON: "C:\\Python311"
285
    - PYTHON: "C:\\Python311-x64"
286

287
install:
288
  - "%PYTHON%\\python.exe -m pip install cibuildwheel"
289

290
build_script:
291
  - "%PYTHON%\\python.exe -m cibuildwheel --output-dir wheelhouse"
292

293
artifacts:
294
  - path: wheelhouse\*.whl
295
    name: wheels
296
```
297

298
## CI-Specific Features
299

300
### Environment Variable Detection
301

302
Cibuildwheel automatically detects CI-specific environment variables:
303

304
```python
305
# GitHub Actions
306
GITHUB_ACTIONS = "true"
307
GITHUB_TOKEN = "secret_token"
308
GITHUB_REF = "refs/heads/main"
309

310
# Travis CI  
311
TRAVIS = "true"
312
TRAVIS_TAG = "v1.0.0"
313
TRAVIS_BRANCH = "main"
314

315
# Azure Pipelines
316
AZURE_PIPELINES = "true" 
317
BUILD_SOURCEBRANCH = "refs/heads/main"
318

319
# CircleCI
320
CIRCLECI = "true"
321
CIRCLE_TAG = "v1.0.0"
322
CIRCLE_BRANCH = "main"
323
```
324

325
### Output Formatting
326

327
Each CI platform receives optimized output formatting:
328

329
- **GitHub Actions**: ANSI codes adjusted for log viewer
330
- **Azure Pipelines**: Compatible with Azure DevOps log display
331
- **GitLab CI**: Optimized for GitLab's CI interface
332
- **Others**: Standard ANSI formatting or plain text
333

334
### Artifact Handling
335

336
Platform-specific artifact upload patterns:
337

338
```yaml
339
# GitHub Actions
340
- uses: actions/upload-artifact@v4
341
  with:
342
    name: wheels-${{ matrix.os }}
343
    path: ./wheelhouse/*.whl
344

345
# Azure Pipelines  
346
- task: PublishBuildArtifacts@1
347
  inputs:
348
    pathToPublish: 'wheelhouse'
349
    artifactName: 'wheels'
350

351
# GitLab CI
352
artifacts:
353
  paths:
354
    - wheelhouse/
355
  expire_in: 1 week
356
```
357

358
## Advanced CI Integration
359

360
### Matrix Builds
361

362
Configure builds across multiple platforms and Python versions:
363

364
```yaml
365
# GitHub Actions matrix
366
strategy:
367
  matrix:
368
    os: [ubuntu-latest, windows-latest, macos-latest]
369
    python-version: ['3.9', '3.10', '3.11']
370
    arch: [x86_64, aarch64]
371
    exclude:
372
      - os: windows-latest
373
        arch: aarch64  # Windows ARM not on all runners
374
```
375

376
### Conditional Builds
377

378
Build wheels only on specific conditions:
379

380
```yaml
381
# Build on tags only
382
on:
383
  push:
384
    tags:
385
      - 'v*'
386

387
# Or conditional job execution
388
jobs:
389
  build_wheels:
390
    if: startsWith(github.ref, 'refs/tags/')
391
```
392

393
### Caching
394

395
Speed up builds with dependency caching:
396

397
```yaml
398
# GitHub Actions
399
- uses: actions/cache@v3
400
  with:
401
    path: ~/.cache/pip
402
    key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
403

404
# Azure Pipelines
405
- task: Cache@2
406
  inputs:
407
    key: 'pip | "$(Agent.OS)" | requirements.txt'
408
    path: $(Pipeline.Workspace)/.pip
409
```
410

411
### Secret Management
412

413
Handle secrets securely in CI:
414

415
```yaml
416
# GitHub Actions
417
env:
418
  CIBW_ENVIRONMENT: API_TOKEN=${{ secrets.API_TOKEN }}
419

420
# Azure Pipelines
421
variables:
422
  - group: build-secrets
423
env:
424
  CIBW_ENVIRONMENT: API_TOKEN=$(API_TOKEN)
425
```
426

427
### Multi-Stage Builds
428

429
Separate build and deployment stages:
430

431
```yaml
432
# GitHub Actions
433
jobs:
434
  build:
435
    # Build wheels
436
  
437
  test:
438
    needs: build
439
    # Test wheels
440
    
441
  deploy:
442
    needs: [build, test]
443
    if: startsWith(github.ref, 'refs/tags/')
444
    # Deploy to PyPI
445
```
446

447
## Troubleshooting CI Issues
448

449
### Common CI Problems
450

451
```python
452
# Docker permission issues (Linux CI)
453
CIBW_CONTAINER_ENGINE = "podman"  # Alternative to Docker
454

455
# Memory constraints  
456
CIBW_BUILD = "cp311-*"  # Reduce build matrix
457

458
# Time limits
459
CIBW_TEST_SKIP = "*-linux_ppc64le *-linux_s390x"  # Skip slow tests
460
```
461

462
### Debugging CI Builds
463

464
```yaml
465
# Enable debug output
466
env:
467
  CIBW_DEBUG_TRACEBACK: 1
468

469
# Print build identifiers
470
- name: Debug build selection
471
  run: python -m cibuildwheel --print-build-identifiers
472
```
473

474
### Platform-Specific Issues
475

476
```yaml
477
# macOS code signing
478
env:
479
  CIBW_ENVIRONMENT_MACOS: CODESIGN_IDENTITY=""
480

481
# Windows long path support
482
env:
483
  CIBW_ENVIRONMENT_WINDOWS: CIBW_ENABLE_LONG_PATH_SUPPORT=1
484

485
# Linux emulation setup
486
- name: Set up QEMU
487
  uses: docker/setup-qemu-action@v2
488
  with:
489
    platforms: arm64,ppc64le,s390x
490
```
491

492
## Best Practices
493

494
### Security
495

496
- Use secrets for sensitive environment variables
497
- Limit artifact retention periods
498
- Validate inputs from external sources
499
- Use specific tool versions to avoid supply chain attacks
500

501
### Performance
502

503
- Use build matrices efficiently
504
- Cache dependencies when possible
505
- Skip unnecessary tests on emulated platforms
506
- Parallelize builds across runners
507

508
### Reliability
509

510
- Pin cibuildwheel version for consistency
511
- Use conditional builds to avoid unnecessary runs
512
- Implement proper error handling and retries
513
- Monitor build times and success rates