# GitHub Actions Workflows Documentation

This document describes the GitHub Actions workflows used in this repository.

## Workflow Overview

```mermaid
graph LR
    PR[Pull Request] --> VALIDATE[Validate]
    VALIDATE --> TEST[Test & Build]

    PUSH[Push to Main] --> MAIN[Main Workflow]
    MAIN --> VERSION[Version Packages]
    VERSION --> RELEASE[Create Release]
    RELEASE --> PUBLISH[Publish Workflow]
    PUBLISH --> NPM[NPM Package]
    PUBLISH --> DOCKER[Docker Image]
```

## Important Setup Requirements

### Personal Access Token for Release Workflow

The Main workflow creates GitHub releases that should trigger the Publish workflow. However, due to GitHub's security features, workflows triggered by the default `GITHUB_TOKEN` cannot trigger other workflows (this prevents infinite loops).

**To enable the Publish workflow to trigger automatically:**

1. Create a Personal Access Token (PAT) with the following permissions:
   - `contents:write` - To create releases
   - `actions:read` - To trigger workflows

2. Add the PAT as a repository secret named `RELEASE_TOKEN`:
   - Go to Settings → Secrets and variables → Actions
   - Click "New repository secret"
   - Name: `RELEASE_TOKEN`
   - Value: Your PAT

3. The Main workflow will automatically use `RELEASE_TOKEN` if available, falling back to `GITHUB_TOKEN` if not configured.

## Workflows

### 1. Pull Request Workflow (`pr.yml`)

**Purpose**: Validates and tests all pull requests.

**Triggers**: Pull requests to `main` branch

**Jobs**:

- **validate**: Checks changeset status
- **security-audit**: Runs security audit
- **type-checking**: TypeScript type checking
- **linting**: ESLint checks
- **format-checking**: Prettier formatting checks
- **test**: Runs test suite with coverage
- **codeql**: Security analysis
- **osv-scan**: Vulnerability scanning

### 2. Main Workflow (`main.yml`)

**Purpose**: Handles versioning and release creation when changes are merged to main.

**Triggers**: Push to `main` branch

**Jobs**:

- **build**:
  - Checks for changesets (fails if releasable commits lack changesets)
  - Versions packages using changesets
  - Builds artifacts and generates SBOM
  - Creates GitHub release with artifacts
  - Generates build attestations

**Important**: Requires `RELEASE_TOKEN` secret to trigger the publish workflow.

### 3. Publish Workflow (`publish.yml`)

**Purpose**: Publishes packages to registries after a release.

**Triggers**:

- Release published event
- Manual workflow dispatch

**Jobs**:

- **npm**: Publishes to NPM (requires `ENABLE_NPM_RELEASE` variable and `NPM_TOKEN` secret)
- **docker**: Builds and publishes Docker images (requires `ENABLE_DOCKER_RELEASE` variable)

## Configuration

### Required Secrets

| Secret               | Purpose                                       | Required For    |
| -------------------- | --------------------------------------------- | --------------- |
| `RELEASE_TOKEN`      | PAT to trigger publish workflow from releases | Auto-publish    |
| `NPM_TOKEN`          | NPM authentication                            | NPM publishing  |
| `DOCKERHUB_USERNAME` | Docker Hub username                           | Docker Hub push |
| `DOCKERHUB_TOKEN`    | Docker Hub access token                       | Docker Hub push |

### Repository Variables

| Variable                | Purpose                    | Default |
| ----------------------- | -------------------------- | ------- |
| `ENABLE_NPM_RELEASE`    | Enable NPM publishing      | `false` |
| `ENABLE_DOCKER_RELEASE` | Enable Docker distribution | `false` |

## Setup Instructions

### 1. Create a Personal Access Token for Releases

Create a fine-grained PAT with:

- **Repository access**: Your repository
- **Permissions**: Contents (Write), Actions (Read)

Add as `RELEASE_TOKEN` secret.

### 2. Configure NPM Publishing

1. Get NPM token from npmjs.com
2. Add as `NPM_TOKEN` secret
3. Set `ENABLE_NPM_RELEASE=true` variable

### 3. Enable Docker Distribution (Optional)

1. Set `ENABLE_DOCKER_RELEASE=true` variable
2. Add Docker Hub credentials if using Docker Hub

## How It Works

1. **Developer creates PR** with changes and changeset
2. **CI validates** the PR (tests pass, changeset present)
3. **PR is merged** to main branch
4. **Main workflow runs**:
   - Checks for changesets
   - Versions packages
   - Builds artifacts
   - Creates GitHub release
5. **Publish workflow triggers** (if `RELEASE_TOKEN` configured):
   - Publishes to NPM
   - Builds Docker images
   - Deploys to configured targets

## Troubleshooting

### Publish Workflow Not Triggering

- Verify `RELEASE_TOKEN` secret is configured
- Ensure the PAT has `contents:write` and `actions:read` permissions
- Check that the release was created (not draft)

### NPM Publish Failing

- Verify `NPM_TOKEN` is valid
- Check `ENABLE_NPM_RELEASE` variable is set to `true`
- Ensure package.json version doesn't already exist

### Missing Changesets

- Main workflow will fail if releasable commits lack changesets
- Add changesets with `pnpm changeset`

## Best Practices

1. **Always include changesets** in PRs with changes
2. **Configure `RELEASE_TOKEN`** for automatic publishing
3. **Keep secrets secure** and rotate regularly
4. **Monitor workflow runs** for failures
5. **Use `pnpm verify`** before pushing code