claude-code-gitea-action/CONTRIBUTING.md

Contributing to Claude Code Action

Thank you for your interest in contributing to Claude Code Action! This document provides guidelines and instructions for contributing to the project.

Getting Started

Prerequisites

• Bun runtime
• Docker (for running GitHub Actions locally)
• act (installed automatically by our test script)
• An Anthropic API key (for testing)

Setup

1. Fork the repository on GitHub and clone your fork:

   git clone https://github.com/your-username/claude-code-action.git
   cd claude-code-action
   

2. Install dependencies:

   bun install
   

3. Set up your Anthropic API key:

   export ANTHROPIC_API_KEY="your-api-key-here"
   

Development

Available Scripts

• bun test - Run all tests
• bun run typecheck - Type check the code
• bun run format - Format code with Prettier
• bun run format:check - Check code formatting

Testing

Running Tests Locally

1. Unit Tests:

   bun test
   

2. Integration Tests (using GitHub Actions locally):

   ./test-local.sh
   

   This script:

   • Installs act if not present (requires Homebrew on macOS)
   • Runs the GitHub Action workflow locally using Docker
   • Requires your ANTHROPIC_API_KEY to be set

   On Apple Silicon Macs, the script automatically adds the --container-architecture linux/amd64 flag to avoid compatibility issues.

Pull Request Process

1. Create a new branch from main:

   git checkout -b feature/your-feature-name
   

2. Make your changes and commit them:

   git add .
   git commit -m "feat: add new feature"
   

3. Run tests and formatting:

   bun test
   bun run typecheck
   bun run format:check
   

4. Push your branch and create a Pull Request:

   git push origin feature/your-feature-name
   

5. Ensure all CI checks pass

6. Request review from maintainers

Action Development

Testing Your Changes

When modifying the action:

1. Test locally with the test script:

   ./test-local.sh
   

2. Test in a real GitHub Actions workflow by:

   • Creating a test repository
   • Using your branch as the action source:

     uses: your-username/claude-code-action@your-branch
     

Debugging

• Use console.log for debugging in development
• Check GitHub Actions logs for runtime issues
• Use act with -v flag for verbose output:

  act push -v --secret ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY"
  

Common Issues

Docker Issues

Make sure Docker is running before using act. You can check with:

docker ps