This document provides comprehensive security guidance for using the AI-powered workflow template safely and securely.

Before using this template, ensure you have:

• Set up secure API key management
• Configured repository security settings
• Understood workflow security implications
• Set up monitoring and audit procedures
• Reviewed security troubleshooting procedures
• Established regular security audit schedule

NEVER commit API keys to your repository. Always use GitHub Secrets for sensitive credentials.

Use the minimum required permissions for GitHub Personal Access Tokens. Start with repo scope only.

ALWAYS review AI-generated code before merging. AI can introduce security vulnerabilities or expose sensitive information.

• Prompt injection attacks: Malicious content in issue descriptions
• Information leakage: AI may expose sensitive data in responses
• Cost-based DoS: Excessive API usage can drain resources
• Code quality issues: AI may generate insecure or inefficient code

If your repository is public, be extra cautious about:

• Configuration files that might expose internal architecture
• Comments or documentation that reveal sensitive business logic
• Test data that might contain real information

# Interactive secure input (preferred)
gh secret set OPENROUTER_API_KEY
# Enter your API key when prompted

# Verify secret is set
gh secret list

# Use .env file (never commit)
cp .env.example .env
# Edit .env with your API key
echo ".env" >> .gitignore  # Ensure it's ignored

• Monthly: For production environments
• Quarterly: For development environments
• Immediately: If compromise suspected

1. Generate new API key at OpenRouter
2. Update GitHub secrets
3. Test workflows with new key
4. Revoke old key
5. Document rotation date

• Monitor API costs in OpenRouter dashboard
• Set up billing alerts
• Review usage patterns regularly

• Check for unusual API activity
• Monitor failed authentication attempts
• Review workflow logs for errors

# Enable security features
gh repo edit --enable-vulnerability-alerts
gh repo edit --enable-automated-security-fixes
gh repo edit --enable-dependency-graph

• Require pull request reviews
• Dismiss stale reviews
• Require status checks
• Restrict pushes to main branch

• Enable secret scanning
• Configure custom patterns
• Review and resolve alerts

• Admin: Repository owners only
• Write: Core contributors
• Read: General team members

• Use minimum required scopes
• Prefer fine-grained tokens
• Regular rotation schedule

Use minimum required permissions:

permissions:
  contents: read
  issues: write
  pull-requests: write
  actions: read
  # Add only what's needed

• Pin action versions to specific commits
• Use official actions when possible
• Avoid storing secrets in workflow files
• Limit workflow triggers appropriately

• Always review AI-generated code
• Test thoroughly before merging
• Check for security vulnerabilities
• Validate business logic

• Avoid including sensitive data in prompts
• Sanitize user input in issue descriptions
• Review AI responses for information leakage

• Set spending limits to prevent abuse
• Monitor unusual cost patterns
• Implement circuit breakers

# Access secrets securely
- name: Use API Key
  env:
    API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
  run: |
    # Use $API_KEY in commands

• Use GitHub environments for sensitive workflows
• Implement approval requirements
• Restrict environment access

• Review GitHub Actions logs for unusual activity
• Check API usage patterns for anomalies
• Monitor repository access logs

• Audit active GitHub tokens and their permissions
• Review recent AI-generated code changes
• Check for new security alerts or vulnerabilities

• Complete security audit checklist
• Review and rotate API keys
• Update security documentation
• Assess and update security policies

1. Revoke compromised credentials immediately
2. Disable affected workflows
3. Review recent repository activity
4. Document the incident
5. Notify team members

1. Identify the scope of the potential breach
2. Review logs and audit trails
3. Assess what data or systems may be affected
4. Determine root cause
5. Implement fixes and preventive measures

1. Generate new API keys and tokens
2. Update all affected secrets
3. Review and update security policies
4. Re-enable workflows with enhanced monitoring
5. Conduct post-incident review

Issue: Workflows failing with authentication errors Solutions:

• Verify secret is set: gh secret list
• Check key validity at OpenRouter
• Regenerate key if needed
• Ensure proper secret name

Issue: GitHub Actions permission denied Solutions:

• Check workflow permissions
• Verify token scopes
• Review repository settings
• Update team permissions

Issue: Security scans reporting false positives Solutions:

• Review and whitelist known safe patterns
• Update security tool configurations
• Add pragma comments for exceptions
• Update vulnerable dependencies

# Check security settings
gh repo view --json securityAndAnalysis

# List security alerts
gh api repos/:owner/:repo/security-advisories

# Check workflow permissions
gh workflow list

# List repository secrets
gh secret list

# Test API key (without exposing it)
gh workflow run ai-task.yml

# Check workflow logs
gh run list --workflow=ai-task.yml
gh run view <run-id> --log

1. Immediate Actions:

   • Disable all workflows
   • Revoke all API keys
   • Change all passwords
   • Review recent activity

2. Investigation:

   • Check workflow logs
   • Review repository access
   • Analyze API usage patterns
   • Document findings

3. Recovery:

   • Generate new credentials
   • Update all secrets
   • Re-enable workflows gradually
   • Monitor for issues

• Review and update branch protection rules
• Check security alert status
• Verify secret scanning is enabled
• Audit team access permissions
• Review recent security-related commits

• Rotate API keys (if due)
• Review API usage patterns
• Check for unused or expired keys
• Verify billing alerts are configured
• Document key rotation dates

• Review workflow permissions
• Check for security issues in AI-generated code
• Verify pre-commit hooks are working
• Test security scanning workflows
• Review workflow logs for anomalies

• Update security documentation
• Review and update incident response procedures
• Check that security contacts are current
• Verify security training is up to date

• Complete risk assessment
• Review all security policies
• Test incident response procedures
• Conduct penetration testing (if applicable)
• Review compliance requirements

• Audit GitHub organization settings
• Review third-party integrations
• Check for security updates
• Verify backup and recovery procedures

• Review team security training
• Conduct security awareness sessions
• Update security contact information
• Review and update security responsibilities

• Report security vulnerabilities: https://github.com/security
• GitHub Support: https://support.github.com

• OpenRouter Security: Contact through their support channels
• Report API key compromise immediately

• GitHub Community: https://github.com/community
• Security best practices documentation
• Stack Overflow for technical issues

• GitHub Security Best Practices
• OpenRouter Security Documentation
• OWASP Secure Coding Practices
• NIST Cybersecurity Framework

This security documentation is regularly updated. Check for updates:

• When updating the template
• Monthly during security audits
• After any security incidents
• When new features are added

Remember: Security is everyone's responsibility. When in doubt, err on the side of caution.