GitHub Action Development - Best Practices Used

This document outlines the best practices we implemented while creating the CODEANT QUALITY GATE SCAN GitHub Action.

1. Action Metadata (action.yml)

✅ Proper Action Definition

Clear naming: Used descriptive name and description fields
Author identification: Set proper author field
Branding: Added icon and color for marketplace visibility
```
branding:
  icon: "shield"
  color: "blue"
```

✅ Input Configuration

Clear descriptions: Each input has a detailed description
Required vs Optional: Properly marked required inputs
Default values: Provided sensible defaults (e.g., api_base)
Documentation: Included examples in descriptions

2. Composite Action Best Practices

✅ Shell Specification

Critical for composite actions: Always specify shell in run steps

- name: Step name
  shell: bash
  run: |
    # commands here

✅ Error Handling

Fail fast: Used set -e to exit on any error

Explicit error messages: Added conditional checks with helpful error messages

if ! curl -fsSL ...; then
  echo "Error: Failed to fetch scan script"
  exit 1
fi

✅ Informative Logging

Added echo statements to track progress
Clear messages at each step for debugging

3. Dependency Management

✅ Version Pinning

Updated to actions/checkout@v4 (latest stable version)
Avoid using @master or @latest in production

✅ Minimal External Dependencies

Used standard tools available in GitHub runners (curl, base64, bash)
No need for additional setup steps

4. Security Best Practices

✅ Token Handling

Never hardcode tokens
Use inputs with clear security requirements
Document required permissions in README

✅ Secure Script Handling

Validate downloaded scripts before execution
Check curl exit codes
Verify base64 decoding success

✅ Fail-Safe Execution

Use curl -fsSL flags:
- -f: Fail on HTTP errors
- -s: Silent mode
- -S: Show errors
- -L: Follow redirects

5. Documentation Best Practices

✅ Comprehensive README

Clear feature list
Input/output documentation in table format
Multiple usage examples (basic and advanced)
Testing instructions before marketplace publication
Required permissions documentation
Publishing checklist

✅ Usage Examples

Provided complete workflow examples
Showed both simple and complex use cases
Included testing from another repository instructions

6. Code Organization

✅ Clean Repository Structure

codeant-quality-gates/
├── action.yml          # Action definition
├── README.md           # User documentation
├── README_LOCAL.md     # Development documentation
└── LICENSE             # License file (recommended)

✅ No Unnecessary Files

Removed boilerplate code (main.py)
Keep only essential files

7. Action Steps Structure

✅ Logical Step Separation

Checkout: Get repository code
Fetch: Download scan script
Prepare: Decode and make executable
Execute: Run the analysis

✅ Clear Step Naming

Use descriptive names for each step
Avoid generic names like "Run script"

8. Testing Strategy

✅ Before Publishing

Local testing: Test in another repository using branch reference
```
uses: username/repo@branch-name
```
Commit testing: Test specific commits
```
uses: username/repo@commit-sha
```
Tag testing: Create and test release tags
```
uses: username/repo@v1.0.0
```

✅ Test Scenarios

Test with minimal required inputs
Test with all optional inputs
Test error conditions (invalid tokens, unreachable API)
Test on different runners (ubuntu, macos, windows if applicable)

9. Marketplace Preparation

✅ Pre-Publication Checklist

Add LICENSE file (required for marketplace)
Create semantic version release (v1.0.0)
Test thoroughly from another repository
Verify branding displays correctly
Ensure README has no placeholder text
Add repository topics/tags
Configure repository description
Add GitHub repository metadata

✅ Release Strategy

Use semantic versioning (MAJOR.MINOR.PATCH)
Create major version tags (v1) pointing to latest minor/patch
Document breaking changes in release notes

10. Common Pitfalls Avoided

❌ Missing Shell Specification

Composite actions MUST specify shell for run steps

❌ No Error Handling

Always handle potential failures gracefully

❌ Outdated Action Versions

Keep dependencies up-to-date (checkout@v4, not v2)

❌ Poor Input Documentation

Users need to know what each input does and requires

❌ No Branding

Actions without branding are less discoverable in marketplace

❌ Incomplete README

Missing usage examples make actions hard to adopt

❌ No Testing Instructions

Users should know how to test before publishing

11. GitHub Actions Specific Features Used

✅ Context Variables

${{ github.repository }}                      # Current repository
${{ github.event.pull_request.head.sha }}     # Pull request head commit SHA
${{ github.ref_name }}                        # Branch/tag name
${{ secrets.GITHUB_TOKEN }}                   # Auto-generated token

✅ Environment Variables

env:
  API_BASE: ${{ inputs.api_base }}

✅ Input References

${{ inputs.access_token }}
${{ inputs.api_base }}

12. Performance Considerations

✅ Efficient Script Fetching

Single API call to fetch script
No unnecessary downloads or processing

✅ Minimal Checkout

Uses default checkout settings (fast)
Only checks out when needed

13. Maintainability

✅ Clear Code Comments

Self-documenting step names
Informative echo messages

✅ Version Control

Proper git usage
Clean commit history
Semantic versioning for releases

✅ Documentation

Both user-facing (README.md) and developer-facing (README_LOCAL.md)
Inline documentation in action.yml

Summary

This action follows GitHub's official best practices for:

Composite action structure
Security and token handling
Error handling and logging
Documentation and examples
Testing and marketplace publication

Following these practices ensures a reliable, secure, and maintainable GitHub Action that users can trust and easily integrate into their workflows.

FilesExpand file tree

README_LOCAL.md

Latest commit

History