GitHub Action
Relevant source files
The following files were used as context for generating this wiki page:
The SecretForge GitHub Action, also known as SecretForge Shield, is a security automation tool designed to prevent the accidental exposure of API keys and credentials within pull requests. It integrates directly into the GitHub CI/CD pipeline to scan code changes for sensitive data, provide actionable feedback via PR comments, and optionally provision secure replacements through the SecretForge AI platform.
The action serves as a "first-line-of-defense" mechanism in the SecretForge ecosystem, reaching contributors and maintainers at the point of code submission. By identifying 50+ types of secrets with high confidence, it helps teams avoid the significant financial and security risks associated with leaked credentials.
Sources: packages/github-action/README.md:3-12, BUILT.md:7-18, AUTOMATION_SUMMARY.md:16-22
Core Architecture and Execution Flow
The GitHub Action is implemented as a TypeScript application that utilizes the @actions/core and @actions/github SDKs to interact with the GitHub environment and the Pull Request API. It follows a linear execution path triggered primarily by pull_request events.
Workflow Execution Process
The following diagram illustrates the high-level logic performed by the action when a pull request is scanned:
The action identifies the scope of changes by retrieving the PR diff and scanning the decoded content of added or modified files using regex patterns.
Sources: packages/github-action/src/index.ts:33-91, packages/github-action/README.md:15-25
Detection Engine
The detection logic is centered around the detectSecrets function, which performs pattern-based scanning. It includes a series of optimized regex patterns for common services and generic API key structures.
Supported Secret Patterns
The engine is configured to detect various specific credential formats:
| Type | Pattern/Service | Source Identifier |
|---|---|---|
| AWS | AWS Access Key IDs | aws |
| Stripe | Live and Test secret keys | stripe |
| OpenAI | OpenAI API Keys | openai |
| Anthropic | Anthropic Claude API Keys | anthropic |
| GitHub | GitHub Personal Access Tokens | github |
| JWT | JSON Web Tokens | jwt |
| Generic | api_key patterns (20+ chars) | generic_api_key |
Sources: packages/github-action/src/index.ts:107-133, packages/github-action/README.md:66-74
Exclusion Logic
To minimize false positives, the action implements "Zero False Positive" logic which ignores specific contexts:
- Lines starting with comments (
//or#). - Files explicitly named
.env.exampleor.env.template. - Files identified as test fixtures.
Sources: packages/github-action/src/index.ts:137-138, packages/github-action/README.md:30
Auto-Provisioning System
A unique feature of SecretForge Shield is its ability to automatically provision secure replacements for detected secrets. When the auto-provision input is enabled and a valid secretforge-api-key is provided, the action communicates with the SecretForge backend.
Provisioning Sequence
The provisionSecrets function iterates through detected matches, filtering for those with a known service type, and makes a POST request to https://api.secretforge.ai/api/secrets.
Sources: packages/github-action/src/index.ts:154-191, BUILT.md:12-14
Configuration and Inputs
The action behavior is controlled via standard GitHub Action inputs defined in the workflow YAML.
Input Parameters
| Input | Required | Default | Description |
|---|---|---|---|
github-token | Yes | - | Used for authenticating API calls to list files and post comments. |
auto-provision | No | false | Enables automatic key generation via SecretForge API. |
secretforge-api-key | No | - | Required if auto-provision is true. |
fail-on-secrets | No | true | Determines if the action status should be 'failed' if secrets are found. |
Sources: packages/github-action/src/index.ts:25-30, packages/github-action/README.md:55-63
Technical Implementation Details
Dependencies
The action is built as a standalone bundle using @vercel/ncc to package TypeScript and its dependencies into a single dist/index.js file suitable for GitHub's runner environment.
Key dependencies include:
@actions/core: For input handling and status reporting.@actions/github: For Octokit client and context access.@anthropic-ai/sdk: Included for future AI-powered detection integration.
Sources: packages/github-action/package.json:17-21, packages/github-action/src/index.ts:1-3
Data Structures
The internal logic relies on structured interfaces to track matches and provisioning results:
// packages/github-action/src/index.ts:5-12
interface SecretMatch {
line: number;
file: string;
type: string;
value: string; // Masked value (first 20 chars)
confidence: number;
service?: string;
}
// packages/github-action/src/index.ts:14-19
interface ProvisionResult {
service: string;
environment: string;
secretId: string;
envVar: string;
}
The GitHub Action acts as a critical security gateway within the SecretForge AI ecosystem, providing automated secret scanning and remediation. By combining pattern-based detection with an optional auto-provisioning API, it ensures that developers can recover from accidental leaks immediately while maintaining a secure CI/CD pipeline.