Skip to content

IMPLEMENTATION_SUMMARY.md

Latest commit

 

History

History
144 lines (113 loc) · 3.78 KB

IMPLEMENTATION_SUMMARY.md

File metadata and controls

144 lines (113 loc) · 3.78 KB
Raw

GitHub Action Implementation Summary

Repository Structure

apisec-bolt-code-discovery-action/
├── .github/
│   └── workflows/
│       ├── test-action.yml      # Test workflow for the action
│       └── publish.yml          # Publishing workflow
├── action.yml                   # Main action definition (REQUIRED)
├── README.md                    # Documentation
├── LICENSE                      # MIT License
├── .gitignore                   # Git ignore rules
└── IMPLEMENTATION_SUMMARY.md    # This file

Key Features Implemented

✅ Simplified Inputs

  • Required: api-endpoint, api-token
  • Optional: repo-path, config-path, pr-title, pr-body, dry-run
  • Removed: output-path, output-format, commit-spec, create-pr, cli-version

✅ Hardcoded Values

  • Output Path: apisec-bolt-code-discovery/openapi_spec.yaml
  • Output Format: Always YAML
  • CLI Version: Pinned to 0.2.0
  • PR Creation: Always enabled (never direct commit)

✅ State Management

  • State file location: apisec-bolt-code-discovery/state.yaml
  • Same directory as OpenAPI spec (no extra folders)
  • Automatically committed in PR

✅ Error Handling

  • Non-blocking: Uses continue-on-error: true
  • Warnings don't fail workflow
  • Graceful degradation

✅ PR Creation Flow

  1. Creates new branch: code-discovery/update-openapi-{timestamp}
  2. Commits generated files
  3. Pushes branch
  4. Creates PR using gh CLI
  5. Handles existing PRs (reuses if branch exists)

Action Workflow Steps

  1. Install Code Discovery CLI

    • Upgrades pip
    • Installs code-discovery==0.2.0

  2. Configure API Credentials

    • Creates ~/.apisec file
    • Sets permissions (600)

  3. Run API Discovery

    • Executes CLI with proper arguments
    • Extracts outputs from state file
    • Sets GitHub outputs

  4. Create Pull Request

    • Only runs if discovery succeeded and not dry-run
    • Creates branch, commits, pushes, creates PR
    • Handles edge cases (existing PRs, no changes, etc.)

Outputs

  • spec-path: Path to OpenAPI spec
  • application-id: From state file
  • instance-id: From state file
  • pr-url: Created PR URL
  • success: Boolean

Required Permissions

permissions:
  contents: write      # To commit files
  pull-requests: write # To create PRs

Next Steps for Publishing

  1. Initialize Git Repository

    cd /Users/mohsinniyazi/apisec-bolt-code-discovery-action
git init
git add .
git commit -m "Initial commit: Code Discovery GitHub Action"

  2. Create GitHub Repository

    • Create public repository: apisec-bolt/code-discovery-action
    • Push code

  3. Create First Release

    • Tag: v1.0.0
    • This makes the action available as @v1 or @v1.0.0

  4. Publish to Marketplace

    • Go to repository Settings → Marketplace
    • Click "Publish to GitHub Marketplace"
    • Fill in details:
      • Category: Security
      • Icon: search
      • Color: blue
    • Submit for review

Testing

The action includes a test workflow (.github/workflows/test-action.yml) that can be used to test the action locally or in CI.

Usage Example

name: API Discovery

on:
  push:
    branches: [main]

jobs:
  discover:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: apisec-bolt/code-discovery-action@v1
        with:
          api-endpoint: ${{ secrets.API_DISCOVERY_ENDPOINT }}
          api-token: ${{ secrets.API_DISCOVERY_TOKEN }}

Notes

  • Action name: apisec-bolt-code-discovery-action
  • Marketplace category: Security
  • All files are in the same directory: apisec-bolt-code-discovery/
  • State management is automatic and default behavior