ctrlshiftleft/docs/GITHUB_INTEGRATION.md

AI-powered toolkit for embedding QA and security testing into development workflows

# GitHub Actions Integration for ctrl.shift.left

This document explains how to use the GitHub Actions integration for automating security analysis, test generation, and QA checklists in your development workflow.

## Overview

The ctrl.shift.left GitHub Action enables you to:

1. **Automate Security Analysis**: Scan your code for security vulnerabilities with every push or pull request
2. **Generate End-to-End Tests**: Automatically create Playwright tests for your components
3. **Create QA Checklists**: Generate comprehensive quality and security checklists
4. **Generate Status Badges**: Display your project's security and QA status in your README

All of this happens automatically when code is pushed, helping you shift security and QA "left" in the development process - finding and fixing issues during development rather than in production.

## Setup Instructions

### 1. Workflow File

The workflow file is located at `.github/workflows/security-qa.yml`. This file is already set up for you and will run automatically on:
- Pushes to main, master, or develop branches
- Pull requests to main, master, or develop branches
- Weekly (Sunday at midnight)
- Manual triggers

### 2. Adding Badges to Your README

To display your project's security and QA status in your README, add this section:

```markdown
## Security & QA Status

[![Security Score](./badges/security.svg)](./security-reports/) 
[![Test Coverage](./badges/tests.svg)](./tests/) 
[![QA Checklist](./badges/checklist.svg)](./checklists/)

_Generated by Ctrl+Shift+Left_
```

These badges will be automatically updated by the GitHub Action.

### 3. Viewing Results

After the workflow runs, you can find:

- **Security Reports**: In the `security-reports/` directory
- **Generated Tests**: In the `tests/` directory
- **QA Checklists**: In the `checklists/` directory
- **Status Badges**: In the `badges/` directory

You can also view the summary of each run in the GitHub Actions tab of your repository.

## Badge Meanings

| Badge | Meaning |
|-------|---------|
| **Security Score** | Calculated from the number and severity of detected security issues (0-100) |
| **Test Coverage** | Percentage of components with generated end-to-end tests |
| **QA Checklist** | Percentage of checklist items passing verification |

## Customizing the Workflow

### Changing Which Files Are Analyzed

To change which files are analyzed, modify these lines in the workflow file:

```yaml
- name: Run Security Analysis
  run: ./bin/ctrlshiftleft analyze ./path/to/your/files/

- name: Generate E2E Tests
  run: ./bin/ctrlshiftleft gen ./path/to/your/files/

- name: Create QA Checklist
  run: ./bin/ctrlshiftleft checklist ./path/to/your/files/
```

### Disabling Automatic Commits

If you don't want the workflow to automatically commit badge updates, remove or comment out the "Commit badge updates" step in the workflow file.

## Integration with Pull Requests

When a pull request is opened, the workflow will:

1. Run the security analysis, test generation, and QA checklist on the PR code
2. Upload the results as workflow artifacts
3. Provide a summary in the workflow run

This helps reviewers assess the security and quality impact of the PR before merging.

## Troubleshooting

### Common Issues

- **Missing Badges**: Ensure the `badges/` directory exists and is writable
- **Failed Builds**: Check if all dependencies are properly installed
- **Access Denied**: The workflow needs write permissions to update badges

### Getting Help

If you encounter any issues with the GitHub Actions integration:

1. Check the workflow run logs for error messages
2. Ensure all required directories exist
3. Verify that the CLI tools are executable

## Best Practices

To get the most out of the ctrl.shift.left GitHub integration:

1. **Address Critical Issues Promptly**: Pay special attention to issues with Critical or High severity
2. **Review Generated Tests**: While the tests are generated automatically, review them for completeness
3. **Integrate Into Code Review**: Use the security and QA reports as part of your code review process
4. **Update Regularly**: Keep the workflow file updated with the latest versions of the tooling

By following these practices, you'll successfully shift security and QA left in your development process.