ci-templates/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Overview

This is a collection of reusable GitLab CI templates for Unbound Software projects. These templates are designed to be included in other projects' `.gitlab-ci.yml` files to provide standardized CI/CD workflows.

## Architecture

### Template Files

- **Defaults.gitlab-ci.yml**: Default retry configuration for all jobs (handles runner failures, timeouts, etc.)
- **Pre-Commit-Go.gitlab-ci.yml**: Pre-commit job for Go projects using `unbound/pre-commit` Docker image
- **Pre-Commit-Node.gitlab-ci.yml**: Pre-commit job for Node.js projects using `unbound/pre-commit-node` Docker image
- **Release.gitlab-ci.yml**: Automated release management using git-cliff for changelog generation and version bumping

### Release Pipeline Workflow

The Release template implements a sophisticated automated release workflow:

1. **unbound_release_preconditions_failed**: Validates that `UNBOUND_RELEASE_TOKEN` is set
2. **unbound_release_changelog**: Generates changelog using git-cliff and bumps version
3. **unbound_release_handle_mr**: Creates or updates a "next-release" branch and merge request with CHANGELOG.md and .version file
4. **unbound_release_prepare_release**: Prepares release artifacts (CHANGES.md, VERSION)
5. **unbound_release_create_release**: Creates GitLab release (when `UNBOUND_RELEASE_TAG_ONLY != "true"`)
6. **unbound_release_tag**: Creates git tag only (when `UNBOUND_RELEASE_TAG_ONLY == "true"`)

### Key Environment Variables

- `UNBOUND_RELEASE_TOKEN`: Personal/Project/Group Access Token with API access (required for release pipeline)
- `UNBOUND_RELEASE_TAG_ONLY`: Set to "true" to only create tags without full releases
- `CI_DEFAULT_BRANCH`: The default branch (usually "main") where releases are created
- `GOPRIVATE`: Set to `gitlab.com/unboundsoftware` in Go pre-commit template for private Go modules
- `PRE_COMMIT_HOME`: Cache directory for pre-commit hooks

## Docker Images

All images use SHA256 pinning for reproducibility and security:

- `unbound/pre-commit:v0.3.5` - Go pre-commit environment
- `unbound/pre-commit-node:v0.0.23` - Node.js pre-commit environment
- `orhunp/git-cliff:2.10.1` - Changelog generation tool
- `amd64/alpine:3.22.2` - Lightweight base for shell scripts

## Modifying Templates

When editing templates:

1. Ensure Docker image references include both version tags and SHA256 digests
2. Test changes by including the modified template in a test project's `.gitlab-ci.yml`
3. Release pipeline jobs should maintain backward compatibility or increment major version
4. Pre-commit templates should cache `PRE_COMMIT_HOME` for performance

## Common Patterns

### Including Templates in Projects

Projects typically include these templates in their `.gitlab-ci.yml`:

```yaml
include:
  - project: 'unboundsoftware/ci-templates'
    ref: main
    file: 'Defaults.gitlab-ci.yml'
  - project: 'unboundsoftware/ci-templates'
    ref: main
    file: 'Pre-Commit-Go.gitlab-ci.yml'
  - project: 'unboundsoftware/ci-templates'
    ref: main
    file: 'Release.gitlab-ci.yml'
```

### Version Management

- Version bumping follows conventional commits via git-cliff
- `.version` file stores current version as JSON: `{"version":"1.2.3"}`
- `CHANGELOG.md` is automatically maintained with full history
- `CHANGES.md` contains only the latest/unreleased changes

### Authentication

- Pre-commit Go template uses GitLab CI token for private Go module access via `.netrc`
- Release jobs use `UNBOUND_RELEASE_TOKEN` for API operations (creating MRs, releases, tags)

## Testing Changes

Since this repository contains templates only (no executable code), testing requires:

1. Create a test project or use an existing project
2. Point the include reference to your branch: `ref: your-feature-branch`
3. Trigger the relevant pipeline in the consuming project
4. Verify job behavior and outputs