Reusable GitHub Action Workflows

This repository contains a comprehensive collection of reusable GitHub Action workflows designed to streamline CI/CD, security, testing, and operational processes across Story Protocol projects.

Quick Start

To use any of these workflows in your repository:

jobs:
  my-job:
    uses: storyprotocol/gha-workflows/.github/workflows/<workflow-filename>@main
    with:
      # workflow inputs
    secrets:
      # workflow secrets

Workflow Categories

🛠️ Utility Workflows

General-purpose workflows for common operations.

Workflow	Purpose	Key Features	When to Use
reusable-timestamp.yml	Generate timestamps in specific timezones	• Configurable timezone • Environment variable output • Useful for versioning	Creating time-based identifiers, logging execution times
reusable-lint-go-workflow.yml	Lint Go code with golangci-lint	• Configurable Go version • 5-minute timeout • Latest golangci-lint	Ensuring Go code quality in PRs and main branch
reusable-slack-notifs.yml	Send formatted Slack notifications	• Rich message formatting • Optional image support • Markdown support	Build notifications, deployment alerts, failure alerts

🚀 CI/CD Workflows

Build, test, and deployment workflows for various platforms and technologies.

Container Build & Push

Workflow	Purpose	Key Features	When to Use
reusable-ecr-build-push.yml	Build and push Go API Docker images to AWS ECR	• OIDC authentication • Go test execution • Trivy scanning • SHA + latest tags	Deploying Go API services to AWS
reusable-ecr-build-push-temporal-worker.yml	Build and push Temporal worker images to AWS ECR	• Custom image tags • OIDC authentication • Temporal-specific Dockerfile	Deploying Temporal workers to AWS
reusable-gcp-image-build-worker.yml	Build and push Docker images to GCP Container Registry	• Environment-aware • Flexible Dockerfile paths • Environment variables support	Deploying containerized apps to GCP
reusable-gcp-app-release-publisher.yml	Publish release messages to GCP Pub/Sub	• Triggers deployments • Environment mapping • Structured JSON messages	Triggering GCP deployments via Pub/Sub

Testing Workflows

Workflow	Purpose	Key Features	When to Use
reusable-build-test-workflow.yml	Full build and test for Node.js projects	• Mochawesome reports • GitHub Pages deployment • Test artifacts	Comprehensive testing with visual reports
reusable-build-unit-test-workflow.yml	Unit testing for Node.js projects	• Fast execution • No report generation • PR-friendly	Quick unit test validation
reusable-build-integration-test-workflow.yml	Integration testing for Node.js projects	• Isolated integration tests • Environment-specific	Testing external integrations
reusable-build-python-unit-test-workflow.yml	Unit testing for Python projects	• Multi-version testing • Coverage reports • Virtual environments	Python service testing
reusable-build-python-integration-test-workflow.yml	Integration testing for Python projects	• pytest-based • Coverage included • RPC testing support	Python integration validation

Release Management

Workflow	Purpose	Key Features	When to Use
reusable-create-release.yml	Create GitHub releases with changelogs	• Automated changelog • Tag creation • Previous tag detection	Creating versioned releases

🔒 Security Workflows

Security scanning, access management, and infrastructure security workflows.

Scanning & Monitoring

Workflow	Purpose	Key Features	When to Use
reusable-secrets-scanning.yml	Scan for hardcoded secrets with TruffleHog	• Verified secrets only • Slack notifications • Configurable depth	Preventing secret leaks
secrets-scanning.yml	Automatic secrets scanning on main branch	• Auto-triggers on push • Calls reusable workflow	Continuous security monitoring
scorecards.yml	OSSF Scorecards security assessment	• SARIF format output • Code scanning integration • Manual trigger	Security posture assessment

AWS Infrastructure Security

Workflow	Purpose	Key Features	When to Use
reusable-fetch-bastion-ips.yml	Fetch bastion host IP addresses	• Multi-environment • Conditional fetching • EC2 tag filtering	Getting bastion IPs for access
reusable-fetch-network-node-ips.yml	Fetch all network node IPs across regions	• Multi-region support • Bulk IP retrieval • Node metadata	Network-wide IP discovery
reusable-fetch-security-group-ids.yml	Fetch security group IDs	• Multi-region • Bastion + network SGs • Region mapping	Dynamic SG management
reusable-parse-bastion-access-files.yml	Parse YAML access configs to JSON	• YAML to JSON conversion • IP permissions format • Multi-environment	Preparing access rules
reusable-update-security-groups.yml	Update security groups with new IPs	• Bulk updates • Status tracking • Multi-region	Adding access rules
reusable-revoke-inbound-rules.yml	Revoke all inbound rules from SGs	• Clean slate approach • Multi-region • Conditional execution	Resetting security groups
reusable-remove-gha-ip-from-sg.yml	Remove GitHub Actions runner IPs	• Cleanup automation • Multi-SG support • Security hygiene	Post-deployment cleanup

🧪 QA Workflows

Quality assurance and code coverage workflows.

Workflow	Purpose	Key Features	When to Use
reusable-forge-code-coverage.yml	Generate code coverage for Solidity contracts	• Foundry/Forge integration • lcov + HTML reports • Path exclusion • Branch coverage	Smart contract test coverage

Common Usage Patterns

1. Complete CI/CD Pipeline

name: CI/CD Pipeline
on:
  push:
    branches: [main]
  pull_request:

jobs:
  lint:
    uses: storyprotocol/gha-workflows/.github/workflows/reusable-lint-go-workflow.yml@main
    with:
      go-version: '1.22'

  test:
    uses: storyprotocol/gha-workflows/.github/workflows/reusable-build-test-workflow.yml@main
    with:
      sha: ${{ github.sha }}
      ENVIRONMENT: staging
    secrets:
      WALLET_PRIVATE_KEY: ${{ secrets.WALLET_PRIVATE_KEY }}
      TEST_WALLET_ADDRESS: ${{ secrets.TEST_WALLET_ADDRESS }}

  security-scan:
    uses: storyprotocol/gha-workflows/.github/workflows/reusable-secrets-scanning.yml@main
    with:
      branch: ${{ github.ref_name }}
    secrets:
      SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
      SLACK_CHANNEL_ID_GITHUB_NOTIFICATION: ${{ secrets.SLACK_CHANNEL_ID }}

  build-and-push:
    needs: [lint, test, security-scan]
    if: github.ref == 'refs/heads/main'
    uses: storyprotocol/gha-workflows/.github/workflows/reusable-ecr-build-push.yml@main
    with:
      ecr-repo: "my-api-service"
      ecr-repo-aws-region: "us-east-1"
    secrets:
      AWS_ACCOUNT: ${{ secrets.AWS_ACCOUNT }}
      AWS_ACCOUNT_TARGET: ${{ secrets.AWS_ACCOUNT_TARGET }}

  notify:
    needs: [build-and-push]
    if: always()
    uses: storyprotocol/gha-workflows/.github/workflows/reusable-slack-notifs.yml@main
    with:
      title: ${{ needs.build-and-push.result == 'success' && '✅ Deployment Successful' || '❌ Deployment Failed' }}
      short-desc: 'Build ${{ github.sha }} has ${{ needs.build-and-push.result }}'
      img-alt-text: 'Build status'
    secrets:
      channel-name: ${{ secrets.SLACK_CHANNEL_ID }}
      slack-bot-token: ${{ secrets.SLACK_BOT_TOKEN }}

2. Security Group Management Flow

name: Update Bastion Access
on:
  push:
    paths:
      - 'configs/bastion-access-*.yaml'

jobs:
  parse-configs:
    uses: storyprotocol/gha-workflows/.github/workflows/reusable-parse-bastion-access-files.yml@main
    with:
      devnet_file: "configs/bastion-access-devnet.yaml"
      testnet_file: "configs/bastion-access-testnet.yaml"

  fetch-sg-ids:
    uses: storyprotocol/gha-workflows/.github/workflows/reusable-fetch-security-group-ids.yml@main
    with:
      role_to_assume: ${{ secrets.AWS_ROLE }}
      aws_region: "us-east-1"
      # ... other inputs

  revoke-existing:
    needs: [fetch-sg-ids]
    uses: storyprotocol/gha-workflows/.github/workflows/reusable-revoke-inbound-rules.yml@main
    with:
      sg_ids_devnet: ${{ needs.fetch-sg-ids.outputs.security_group_ids_devnet }}
      # ... other inputs

  update-sgs:
    needs: [parse-configs, fetch-sg-ids, revoke-existing]
    uses: storyprotocol/gha-workflows/.github/workflows/reusable-update-security-groups.yml@main
    with:
      ips_devnet: ${{ needs.parse-configs.outputs.ips_devnet }}
      sg_ids_devnet: ${{ needs.fetch-sg-ids.outputs.security_group_ids_devnet }}
      # ... other inputs

3. Multi-Environment Testing

name: Multi-Environment Tests
on: [push, pull_request]

jobs:
  unit-tests:
    strategy:
      matrix:
        environment: [staging, production]
    uses: storyprotocol/gha-workflows/.github/workflows/reusable-build-unit-test-workflow.yml@main
    with:
      sha: ${{ github.sha }}
      ENVIRONMENT: ${{ matrix.environment }}
    secrets:
      WALLET_PRIVATE_KEY: ${{ secrets[format('WALLET_PRIVATE_KEY_{0}', matrix.environment)] }}
      TEST_WALLET_ADDRESS: ${{ secrets[format('TEST_WALLET_ADDRESS_{0}', matrix.environment)] }}

Best Practices

1. Version Pinning: All workflows use pinned action versions with SHA hashes for security. Regularly update these after security review.

2. Secret Management:

   • Use environment-specific secrets
   • Pass secrets explicitly through the secrets context
   • Never hardcode sensitive information

3. Conditional Execution: Many workflows support conditional execution based on environment changes. Use this to optimize CI/CD time.

4. Error Handling: Most workflows will fail fast on errors. Consider using if: always() for cleanup or notification steps.

5. Documentation: Each workflow has its own documentation in the docs/ directory. Keep these updated when modifying workflows.

Requirements

• GitHub Actions must be enabled in your repository
• Appropriate secrets must be configured at the repository or organization level
• For AWS workflows: OIDC provider must be configured
• For GCP workflows: Service account keys must be available
• For Slack workflows: Slack app with bot token must be configured

Contributing

When adding new reusable workflows:

1. Follow the naming convention: reusable-<purpose>.yml
2. Include comprehensive input validation
3. Use pinned action versions with SHA hashes
4. Create documentation in docs/<category>/readme-reusable-<name>.md
5. Update this README with the new workflow information
6. Test thoroughly in a separate repository before merging

Security

• All workflows use pinned action versions for security
• Secrets are handled through GitHub's encrypted secrets
• AWS workflows use OIDC for temporary credentials
• Regular security scanning with TruffleHog and OSSF Scorecards

License

[Include your license information here]