How 3ware/workflows works
Project Type and Purpose
• This is an open‑source library of reusable GitHub Actions workflows.
• Its purpose is to package common CI/CD steps (dependency scanning, PR title checks, semantic releases, Terraform docs, etc.) into standalone workflows that other repositories can “call” via GitHub’s workflow_call feature.
File Structure
• Top‑level files (.editorconfig, .gitignore, CHANGELOG.md, LICENSE) are repository‑level metadata.
• .github/workflows/ holds each reusable workflow as a separate YAML file:
• dependency-review.yaml
• get-terraform-dir.yaml
• get-workflow-token.yaml
• pr-title.yaml
• release.yaml (semantic‑release)
• scorecard.yaml
• terraform-docs.yaml
• wait-for-checks.yaml
• .trunk/ contains linting policies (markdownlint, yamllint) enforced via Trunk CI.
• Configuration for semantic‑release, commitlint, Renovate, and Trunk ensure consistent formatting, versioning, and dependency updates.
README for Additional Insights
• Each workflow encapsulates a specific task, often invoking a third‑party Action (e.g., actions/dependency-review-action, workflow-application-token-action, ossf-scorecard-action, tflint/terraform-docs-gh-actions).
• Some workflows have multi‑step logic: e.g., get-workflow-token generates, encrypts, and outputs a GitHub App token via PGP and base64 to safely pass secrets between jobs.
Main Components and Interactions
a. Reusable Workflow Definitions (internal): each YAML file in .github/workflows/.
b. GitHub Actions Runner (platform): executes the steps defined by a reusable workflow when invoked.
c. External Actions & Services (external):
• Official Actions (e.g., dependency-review-action, changed‑files, ossf-scorecard-action, terraform-docs-gh-actions, semantic-release).
• GitHub API (for token generation, status checks, releases).
• GitHub App (installation access token).
• PGP encryption (GPG) for safe secret transport.
d. Consumer Repositories: other GitHub repos that call these workflows
via uses: 3ware/workflows/.github/workflows/<name>@vX.Y.Z.
Interactions:
1. A consumer repo’s workflow invokes one of these reusable workflows (workflow_call).
2. GitHub Actions runner loads the reusable workflow from this repo.
3. Runner executes each step:
– Calls external actions (e.g., uses: actions/dependency-review-action).
– For get-workflow-token: requests a token from the GitHub App, runs a shell step to encrypt it via GPG/base64, sets outputs.
4. Steps pass outputs (encrypted or plain) to subsequent jobs or back to the consumer.
5. Some workflows perform Git operations (e.g., commit updated Terraform docs) using tokens.
Architectural Patterns & Design Principles
• Modularization: each CI function lives in its own workflow file.
• “workflow_call” Interface: standardized I/O via inputs/outputs for easy reuse.
• Secrets Handling: encrypt/decrypt secret outputs to avoid leaking.
• Infrastructure as Code: workflows defined declaratively; CI linted via Trunk.