GitHub Actions Setup Guide for Codity.ai

This guide covers best practices for configuring GitHub Actions workflows to work seamlessly with Codity.ai's automated test generation and monitoring.

Why GitHub Actions Works Well with Codity.ai

GitHub Actions is well-integrated with Codity.ai and requires minimal configuration. Most workflows work out-of-the-box because:

• Automatic path handling (no manual PYTHONPATH needed)
• Job names are typically descriptive by default
• Workflow files are easily discoverable in .github/workflows/

Critical Configuration Points

1. Workflow Name

• Should contain keywords: test, ci, or build (recommended)
• Works without keywords, but better detection with them
• Why: Codity identifies CI workflows by checking names

Examples:

• CI Tests
• Run Tests
• Build and Test
• Main Workflow (works, but less specific)

2. Job Name

• Should contain keywords: test, python, go, ruby, javascript, jest, pytest
• Why: Helps filter out non-test jobs (lint, deploy, etc.)

Examples:

• test
• run-tests
• python-tests
• build (might be skipped if no test keyword)

3. Working Directory (Optional)

• Only needed if your project files are in a subdirectory
• Use working-directory in step configuration
• Important: The path must actually exist in your repository

4. Pull Request Triggers

• Include pull_request trigger
• Why: Without this, CI won't run on PRs

5. Verbose Output (Recommended)

• Use -v or --verbose flags for better logs
• Why: Provides detailed error information for auto-fixing

Sample GitHub Actions Workflows

Python with pytest

name: Python CI Tests

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3

    - name: Set up Python 3.11
      uses: actions/setup-python@v4
      with:
        python-version: '3.11'

    - name: Install dependencies
      run: |
        pip install pytest
        pip install -r requirements.txt
      # Only set working-directory if requirements.txt is in a subdirectory
      # working-directory: ./backend

    - name: Run pytest
      run: pytest -v
      # Only set working-directory if tests are in a subdirectory
      # working-directory: ./backend

Go with testing

name: Go CI Tests

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3

    - name: Set up Go
      uses: actions/setup-go@v4
      with:
        go-version: '1.21'

    - name: Run Go tests
      run: go test -v ./...
      # Only set working-directory if go.mod is in a subdirectory
      # working-directory: ./services

JavaScript/TypeScript with Jest

name: JavaScript CI Tests

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3

    - name: Set up Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'

    - name: Install dependencies
      run: npm install
      # Only set working-directory if package.json is in a subdirectory
      # Example: working-directory: ./frontend

    - name: Run Jest tests
      run: npm test -- --verbose
      # Only set working-directory if tests are in a subdirectory
      # Example: working-directory: ./frontend

Ruby with RSpec

name: Ruby CI Tests

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3

    - name: Set up Ruby
      uses: ruby/setup-ruby@v1
      with:
        ruby-version: '3.2'
        bundler-cache: true

    - name: Install dependencies
      run: bundle install
      # Only set working-directory if Gemfile is in a subdirectory
      # working-directory: ./api

    - name: Run RSpec tests
      run: bundle exec rspec --format documentation
      # Only set working-directory if tests are in a subdirectory
      # working-directory: ./api

Java with JUnit/Gradle

name: Java CI Tests

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3

    - name: Set up JDK 17
      uses: actions/setup-java@v3
      with:
        java-version: '17'
        distribution: 'temurin'

    - name: Grant execute permission for gradlew
      run: chmod +x gradlew
      # Only set working-directory if build.gradle is in a subdirectory
      # working-directory: ./service

    - name: Run tests with Gradle
      run: ./gradlew test --info
      # Only set working-directory if build.gradle is in a subdirectory
      # working-directory: ./service

Multi-language Monorepo

name: Monorepo CI Tests

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  backend-tests:
    name: Python Backend Tests
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-python@v4
      with:
        python-version: '3.11'
    - name: Install dependencies
      run: pip install pytest
      working-directory: ./backend
    - name: Run tests
      run: pytest -v
      working-directory: ./backend

  frontend-tests:
    name: JavaScript Frontend Tests
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-node@v3
      with:
        node-version: '18'
    - name: Install dependencies
      run: npm install
      working-directory: ./frontend
    - name: Run tests
      run: npm test -- --verbose
      working-directory: ./frontend

  services-tests:
    name: Go Services Tests
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-go@v4
      with:
        go-version: '1.21'
    - name: Run tests
      run: go test -v ./...
      working-directory: ./services

Understanding Working Directory

Important: Paths Must Actually Exist

When you set working-directory: ./backend, the directory must exist in your repository:

✅ CORRECT - Directory exists:
my-repo/
├── backend/              ← This directory EXISTS
│   ├── requirements.txt
│   ├── src/
│   └── tests/
└── .github/
    └── workflows/
        └── ci.yml

❌ INCORRECT - Directory doesn't exist:
my-repo/
├── src/                  ← Your code is here, not in /backend
│   ├── requirements.txt
│   └── tests/
└── .github/
    └── workflows/
        └── ci.yml        ← Says working-directory: ./backend (WRONG!)

How to Check Your Project Structure

Run this command in your repository root:

ls -la

You should see your actual directories. Examples:

Scenario 1: Root-level project

my-repo/
├── package.json          ← Files at root level
├── src/
├── tests/
└── .github/

Solution: Don't set working-directory (or use ./)

Scenario 2: Backend subdirectory

my-repo/
├── backend/              ← Backend code is here
│   ├── requirements.txt
│   └── tests/
└── .github/

Solution: working-directory: ./backend

Scenario 3: Multiple subdirectories

my-repo/
├── frontend/
│   └── package.json
├── backend/
│   └── requirements.txt
├── services/
│   └── go.mod
└── .github/

Solution: Different working-directory for each job

Common Issues and Solutions

Issue: "Error: Unable to locate executable file: pytest"

Cause: Dependencies not installed or wrong working directory Solution:

1. Check if working-directory path exists in your repo
2. Ensure pip install step runs before tests
3. Verify requirements.txt is in the correct location

Issue: "ENOENT: no such file or directory, open 'package.json'"

Cause: npm commands running in wrong directory Solution:

1. Find where package.json actually is: find . -name "package.json"
2. Set working-directory to match that location
3. Example: If package.json is in ./frontend, use working-directory: ./frontend

Issue: "go.mod file not found"

Cause: Go commands running in wrong directory Solution:

1. Find where go.mod actually is: find . -name "go.mod"
2. Set working-directory to match that location

Issue: "Could not find Gemfile"

Cause: Bundle commands running in wrong directory Solution:

1. Find where Gemfile actually is: find . -name "Gemfile"
2. Set working-directory to match that location

Issue: "Workflow doesn't run on pull requests"

Cause: Missing pull_request trigger Solution: Add to your workflow:

on:
  pull_request:
    branches: [ main ]

Checklist Before Committing

• Workflow file is in .github/workflows/ directory
• Workflow name contains test, ci, or build (recommended)
• Job name contains test-related keywords
• pull_request trigger is included
• If using working-directory, verify the path actually exists with ls -la
• Test commands use verbose flags (-v, --verbose)
• Workflow runs successfully on test PR

Language-Specific Notes

Python

• GitHub handles PYTHONPATH automatically - no manual setup needed!
• Use actions/setup-python@v4 for Python version
• Install dependencies before running tests
• Common locations: /, /backend, /api, /src

JavaScript/TypeScript

• Must have package.json in the directory where you run npm install
• Use actions/setup-node@v3 for Node version
• If using workspaces/monorepo, set working-directory for each package
• Common locations: /, /frontend, /web, /client, /app

Go

• Must have go.mod in the directory where you run go test
• Use actions/setup-go@v4 for Go version
• Use ./... to run all tests in subdirectories
• Common locations: /, /services, /cmd, /pkg

Ruby

• Must have Gemfile in the directory where you run bundle install
• Use ruby/setup-ruby@v1 with bundler-cache: true for faster builds
• Common locations: /, /app, /api, /lib

Java

• Must have build.gradle or pom.xml in the directory where you run gradle/maven
• Use actions/setup-java@v3 for Java version
• Make gradlew executable: chmod +x gradlew
• Common locations: /, /service, /app, /backend

How Codity.ai Monitors GitHub Actions

1. Workflow Discovery: Finds workflows in .github/workflows/ containing test keywords
2. Check Run Detection: Monitors check runs on PR commits
3. Log Retrieval: Fetches logs from completed check runs
4. Failure Analysis: Identifies failed tests and error patterns
5. Auto-Fix: Automatically fixes failing tests (up to 3 attempts)
6. Status Updates: Posts comments on PR with test results

Testing Your Workflow

1. Create workflow file in .github/workflows/test.yml
2. Commit and push to a branch
3. Create a pull request
4. Check that workflow runs automatically
5. Verify Codity.ai detects and monitors the workflow
6. Check workflow logs in GitHub Actions tab for any errors

Best Practices

DO

• Use descriptive workflow and job names
• Include pull_request trigger
• Set working-directory only when files are actually in subdirectories
• Use verbose test output flags
• Keep workflows simple and focused

DON'T

• Don't set working-directory if files are at repository root
• Don't use incorrect paths that don't exist
• Don't skip pull_request trigger
• Don't mix multiple languages in one job (use separate jobs instead)
• Don't forget to install dependencies before running tests

Quick Reference: Finding Your Project Files

# Find all package.json files
find . -name "package.json"

# Find all go.mod files
find . -name "go.mod"

# Find all Gemfiles
find . -name "Gemfile"

# Find all requirements.txt files
find . -name "requirements.txt"

# Find all build.gradle files
find . -name "build.gradle"

# List directory structure (first 2 levels)
tree -L 2
# or
ls -R | grep ":$" | sed -e 's/:$//' -e 's/[^-][^\/]*\//--/g' -e 's/^/   /' -e 's/-/|/'

The output will show you exactly where your files are, so you can set working-directory correctly.

Example: Determining Correct Working Directory

Command:

find . -name "package.json"

Output:

./frontend/package.json

Conclusion: Your package.json is in ./frontend, so use:

working-directory: ./frontend

---

Need help? Check the GitHub Actions documentation