---
synced_from: "/home/josie/development/crystal/cr/crystal-github-actions/README.md"
last_sync: "2026-03-04T10:10:24.546Z"
readonly: true
---
# Crystal GitHub Actions

Reusable GitHub Actions workflows for Crystal projects and Kubernetes operators.

## Available Workflows

### 1. Crystal Build

Build Crystal projects with configurable options.

```yaml
jobs:
  build:
    uses: cloudnative-cr/crystal-github-actions/.github/workflows/crystal-build.yml@main
    with:
      crystal-version: '1.18.2'
      release-mode: true
      static-build: true
      upload-artifact: true
      artifact-name: 'my-binary'
```

**Inputs:**
- `crystal-version` (default: `1.18.2`) - Crystal version
- `build-target` - Specific shards build target
- `release-mode` (default: `true`) - Build in release mode
- `static-build` (default: `false`) - Build static binary
- `upload-artifact` (default: `false`) - Upload binary as artifact
- `artifact-name` (default: `binary`) - Artifact name
- `working-directory` (default: `.`) - Working directory

### 2. Crystal Test

Run Crystal specs.

```yaml
jobs:
  test:
    uses: cloudnative-cr/crystal-github-actions/.github/workflows/crystal-test.yml@main
    with:
      crystal-version: '1.18.2'
      spec-args: '--order=random --error-on-warnings'
```

**Inputs:**
- `crystal-version` (default: `1.18.2`) - Crystal version
- `working-directory` (default: `.`) - Working directory
- `spec-args` (default: `--order=random`) - Additional spec arguments

### 3. Kubernetes Operator E2E

End-to-end testing for K8s operators using kind.

```yaml
jobs:
  e2e:
    uses: cloudnative-cr/crystal-github-actions/.github/workflows/k8s-operator-e2e.yml@main
    with:
      kubernetes-version: 'v1.31.0'
      crd-path: 'config/crd'
      samples-path: 'config/samples'
      wait-seconds: 30
```

**Inputs:**
- `crystal-version` (default: `1.18.2`) - Crystal version
- `kubernetes-version` (default: `v1.31.0`) - K8s version for kind
- `working-directory` (default: `.`) - Working directory
- `crd-path` (default: `config/crd`) - CRD files path
- `samples-path` (default: `config/samples`) - Sample resources path
- `operator-binary` (default: `bin/*`) - Operator binary path
- `wait-seconds` (default: `30`) - Wait time after applying samples

### 4. Docker Build and Push

Build and push Docker images.

```yaml
jobs:
  docker:
    uses: cloudnative-cr/crystal-github-actions/.github/workflows/docker-build.yml@main
    with:
      image-name: 'myorg/my-operator'
      registry: 'quay.io'
      push: true
      platforms: 'linux/amd64,linux/arm64'
    secrets:
      registry-username: ${{ secrets.QUAY_USERNAME }}
      registry-password: ${{ secrets.QUAY_PASSWORD }}
```

**Inputs:**
- `image-name` (required) - Docker image name (org/name)
- `registry` (default: `quay.io`) - Container registry
- `dockerfile-path` (default: `Dockerfile`) - Dockerfile path
- `context` (default: `.`) - Build context
- `push` (default: `false`) - Push to registry
- `platforms` (default: `linux/amd64`) - Target platforms

**Secrets:**
- `registry-username` - Registry username
- `registry-password` - Registry password/token

## Complete Examples

### Basic CI Workflow

```yaml
# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    uses: cloudnative-cr/crystal-github-actions/.github/workflows/crystal-test.yml@main
    with:
      crystal-version: '1.18.2'

  build:
    needs: test
    uses: cloudnative-cr/crystal-github-actions/.github/workflows/crystal-build.yml@main
    with:
      crystal-version: '1.18.2'
      release-mode: true
      upload-artifact: true
```

### Kubernetes Operator CI/CD

```yaml
# .github/workflows/operator-ci.yml
name: Operator CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    uses: cloudnative-cr/crystal-github-actions/.github/workflows/crystal-test.yml@main
    with:
      crystal-version: '1.18.2'

  build:
    needs: test
    uses: cloudnative-cr/crystal-github-actions/.github/workflows/crystal-build.yml@main
    with:
      crystal-version: '1.18.2'
      release-mode: true
      upload-artifact: true
      artifact-name: 'operator'

  e2e:
    needs: build
    uses: cloudnative-cr/crystal-github-actions/.github/workflows/k8s-operator-e2e.yml@main
    with:
      kubernetes-version: 'v1.31.0'
      crd-path: 'config/crd'
      samples-path: 'config/samples'
      wait-seconds: 30

  docker:
    needs: e2e
    if: github.ref == 'refs/heads/main'
    uses: cloudnative-cr/crystal-github-actions/.github/workflows/docker-build.yml@main
    with:
      image-name: 'myorg/my-operator'
      registry: 'quay.io'
      push: true
    secrets:
      registry-username: ${{ secrets.QUAY_USERNAME }}
      registry-password: ${{ secrets.QUAY_PASSWORD }}
```

## Usage in Your Repository

1. Reference workflows using the full path:
   ```yaml
   uses: cloudnative-cr/crystal-github-actions/.github/workflows/workflow-name.yml@main
   ```

2. Pin to a specific version/tag for stability:
   ```yaml
   uses: cloudnative-cr/crystal-github-actions/.github/workflows/workflow-name.yml@v1.0.0
   ```

3. Use `@main` for latest features (less stable)

## Requirements

- Crystal >= 1.9.0
- For E2E tests: Kubernetes operator built with Crystal
- For Docker: Dockerfile in repository

## Contributing

Contributions welcome! Please submit PRs with:
- Clear description of changes
- Updated documentation
- Example usage

## License

Apache 2.0