Cloud Functions Buildkite Plugin

This buildkite plugin can be used to deploy code to Cloud Functions

See the plugin tester for testing examples and usage, and the Buildkite docs on writing plugins to understand everything in this repo.

Using the plugin

If the version number is not provided then the most recent version of the plugin will be used. Do not use version number as main or any branch name.

Simple

steps:
  - plugins:
      - wayfair-incubator/cloud-functions#v0.2.0:
          gcp_project: "gcp-us-project"
          gcp_region: "us-central1"
          cloud_function_name: "function-1"
          cloud_function_directory: "directory/function-code"

Configuration

Required

gcp_project (required, string)

The name of the GCP project you want to deploy to.

Example: gcp-us-project

gcp_region (required, string)

GCP region where the cloud function is hosted.

Example: us-central1

cloud_function_name (required, string)

Name of the cloud function in GCP.

Example: function-1

cloud_function_directory (required, string)

The directory in your repository where you are storing the code files for the cloud function.

Example: directory/function-code

Secret

This plugin expects GCP_SERVICE_ACCOUNT is placed as an environment variable. Make sure to store it securely!

env:
  gcp_service_account: '{"email": ""}'

Development

This project uses modern Python tooling for fast, efficient development:

• Python 3.13+: Latest stable Python versions (3.13 and 3.14 supported)
• uv: Fast Python package installer (10-100x faster than pip)
• Ruff: Unified linter and formatter (10-100x faster than black/flake8/isort)
• Docker: Consistent development environment

Requirements

• Docker and Docker Compose (v2 recommended: docker compose or legacy v1: docker-compose)
• Python 3.13 or 3.14 (for local development without Docker)
• uv (optional, for local development)

Quick Start

# Build the development container (Python 3.13)
docker-compose build

# Or build Python 3.14 container (when Python 3.14 is released)
docker-compose build devbox-py314

# Run all tests and linting
docker-compose run --rm py-test

# Format code automatically
docker-compose run --rm ruff-format

# Run linter with auto-fix
docker-compose run --rm ruff-lint

Testing with Python 3.14

When Python 3.14 is officially released, you can test your code against it:

# Build Python 3.14 container
docker-compose build devbox-py314

# Run tests in Python 3.14
docker-compose run --rm devbox-py314 pytest

# Open interactive shell with Python 3.14
docker-compose run --rm devbox-py314

Development Commands

Testing

# Run all tests with coverage
docker-compose run --rm py-test

# Run tests with formatting (formats code before running tests)
docker-compose run --rm py-test --format-code

# Run tests locally (requires Python 3.13 and dependencies)
pytest --cov plugin_scripts tests --cov-report html

Code Quality

# Format code with Ruff
docker-compose run --rm ruff-format

# Check formatting (without modifying files)
docker-compose run --rm ruff-format-check

# Run linter and auto-fix issues
docker-compose run --rm ruff-lint

# Run linter in check mode (no fixes)
docker-compose run --rm ruff-check

# Run type checking with mypy
docker-compose run --rm mypy

Dependency Management

# Lock requirements (creates requirements.lock file)
docker-compose run --rm lock-requirements

# Install dependencies locally with uv (fast!)
uv pip install --system -r requirements.txt -r requirements-test.txt

# Install dependencies locally with pip
pip install -r requirements.txt -r requirements-test.txt

Interactive Development

# Start an interactive shell in the container
docker-compose run --rm devbox

# Inside the container, you can:
#   - Run pytest
#   - Run ruff check/format
#   - Run mypy
#   - Debug code

Local Development (without Docker)

If you prefer to develop without Docker:

# Install uv (https://github.com/astral-sh/uv)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv pip install -r requirements.txt -r requirements-test.txt

# Run tests
pytest --cov plugin_scripts tests --cov-report html

# Format code
ruff format plugin_scripts tests

# Lint code
ruff check --fix plugin_scripts tests

# Type check
mypy plugin_scripts tests

Project Structure

cloud-functions-buildkite-plugin/
├── plugin_scripts/          # Main plugin code
│   ├── __init__.py
│   ├── deploy.py           # Deployment logic
│   └── pipeline_exceptions.py  # Custom exceptions
├── tests/                   # Test suite
│   ├── __init__.py
│   ├── test_deploy.py
│   └── test_pipeline_exceptions.py
├── docker/                  # Docker configuration
│   ├── devbox.dockerfile
│   ├── run_tests.sh        # Test runner script
│   └── lock_requirements.sh # Dependency locking script
├── hooks/                   # Buildkite plugin hooks
│   └── command             # Main plugin command
├── pyproject.toml          # All tool configurations
├── requirements.txt        # Production dependencies
├── requirements-test.txt   # Development dependencies
└── docker-compose.yaml     # Docker services

Configuration

All tool configurations are centralized in pyproject.toml:

• Ruff: Linting and formatting rules
• MyPy: Type checking configuration
• Pytest: Test runner configuration
• Coverage: Code coverage settings

See pyproject.toml for detailed configuration options.

Contributing

See the Contributing Guide for additional information.

Running Tests Locally

To execute tests locally (requires that docker and Docker Compose are installed):

docker compose run --rm py-test
# Or with legacy v1: docker-compose run --rm py-test

Code Style

This project uses Ruff for linting and formatting. Ruff is configured to:

• Enforce PEP 8 style guidelines
• Sort imports (replacing isort)
• Check for common bugs and security issues (replacing bandit)
• Enforce modern Python patterns (pyupgrade)
• Use pathlib for file operations

To format your code before committing:

docker-compose run --rm ruff-format
docker-compose run --rm ruff-lint

Type Checking

This project uses MyPy for static type checking. Run type checks with:

docker-compose run --rm mypy

What's New in v0.2.0

This release includes major modernization improvements:

• ⚡ 10-100x faster dependency installation with uv
• ⚡ 10-100x faster linting and formatting with Ruff
• 🐍 Python 3.13 & 3.14 support (upgraded from 3.10)
• 🔒 Security improvements: Better error handling and logging
• 📦 Latest dependencies: All packages updated to latest versions
• 🧪 Enhanced test coverage: 17+ new test cases with branch coverage
• 🎯 Better error messages: Custom exceptions with detailed information
• 📝 Comprehensive documentation: Full docstrings and type hints

See CHANGELOG.md for complete details.

Migration from v0.1.x

For users, no changes required - the plugin API is unchanged. Simply update your version reference.

For developers:

1. Rebuild Docker containers: docker-compose build
2. All old linting tools (black, isort, flake8, bandit) have been replaced with Ruff
3. Configuration moved from multiple files to pyproject.toml

See the CHANGELOG.md for detailed migration instructions.

Credits

This plugin was originally written by Jash Parekh for Wayfair.