name: GitHub Workflow Security description: Automatically scan and harden GitHub Actions workflow files by adding security configurations and pinning action versions to immutable commit SHAs

GitHub Workflow Security

[!NOTE] Skills Home Directory: $SKILL_GH_WS_HOME = ~/.gemini/antigravity/skills

This skill automatically scans and hardens GitHub Actions workflow files by adding security configurations and pinning action versions to immutable commit SHAs to improve supply chain security.

When to Activate

This skill should be activated when the user mentions:

• workflow security / workflow 安全
• github actions security / GitHub Actions 安全
• action commit hash / action 提交哈希
• workflow permissions / workflow 权限
• harden workflow / 加固 workflow
• scan workflow / 扫描 workflow
• supply chain security for GitHub Actions

Core Functionality

1. Scan GitHub Workflow Files

• Automatically find all YAML files in .github/workflows/
• Parse workflows to identify security issues
• Support both .yml and .yaml formats

2. Add/Check Permissions Configuration

• Check if workflow has permissions field
• If missing, add minimal permissions:

  permissions:
    contents: read
  

• If custom permissions needed, use user-specified configuration
• Skip if permissions already exist to avoid conflicts

3. Pin Action Versions to Commit SHAs

• Replace mutable tags (e.g., @v4) with immutable commit SHAs
• Format: actions/checkout@<commit-sha> # v4.3.1
• Prevents tag manipulation and improves supply chain security
• Maintains version comment for readability

4. Automatic Commit SHA Retrieval

• Use mapping table from data/action-commit-map.json
• For unmapped actions, automatically fetch from GitHub API
• Report unmapped actions so user can add them to mapping table

Implementation Approach

When the user requests workflow hardening, follow these steps:

Step 1: Execute Hardening Script

Run the main hardening script from the skill's scripts directory:

python3 $SKILL_GH_WS_HOME/github-workflow-security/scripts/harden-workflows.py

Script Options:

• --dir DIR: Specify workflow directory (default: .github/workflows)
• --permissions PERMISSIONS: Custom permissions configuration
• --map-file MAP_FILE: Path to action mapping JSON file

Default behavior:

• Scans all workflow files in .github/workflows/
• Adds permissions: { contents: read } if missing
• Replaces action tags with commit SHAs
• Reports statistics and unmapped actions

Step 2: Review Changes (Optional)

After execution, offer to review the changes:

1. Run git diff .github/workflows/ to show modifications
2. Ask if user wants AI to review the changes
3. If yes, analyze the diff to verify correctness and completeness

Step 3: Report Unmapped Actions

List any actions not in the mapping table:

⚠️ Found unmapped actions - consider adding to mapping table:
- some/action@v1 → some/action@abc123... # v1.2.3

To get commit hash and save to mapping table:
python3 $SKILL_GH_WS_HOME/github-workflow-security/scripts/get-action-commit.py some/action v1 --save

Helper Scripts

All scripts are located in the skill's scripts directory: $SKILL_GH_WS_HOME/github-workflow-security/scripts/

Main Hardening Script

File: harden-workflows.py

Usage Examples:

# Basic usage - harden all workflows with default permissions
python3 $SKILL_GH_WS_HOME/github-workflow-security/scripts/harden-workflows.py

# Custom permissions
python3 $SKILL_GH_WS_HOME/github-workflow-security/scripts/harden-workflows.py \
  --permissions "permissions:\n  contents: read\n  pull-requests: write\n"

# Specify workflow directory
python3 $SKILL_GH_WS_HOME/github-workflow-security/scripts/harden-workflows.py \
  --dir .github/workflows

Get Action Commit Hash

File: get-action-commit.py

Usage Examples:

# Query commit hash
python3 $SKILL_GH_WS_HOME/github-workflow-security/scripts/get-action-commit.py actions/checkout v4

# Query and save to mapping table
python3 $SKILL_GH_WS_HOME/github-workflow-security/scripts/get-action-commit.py actions/checkout v4 --save

Output includes:

• Action name and tag
• Resolved version number
• Full commit SHA
• Formatted uses: statement
• Mapping table format (for manual addition)

Usage Examples

Example 1: Basic Hardening

User: Use the github-workflow-security skill to scan and harden all workflows

Agent: I'll harden your GitHub Actions workflows for improved security.

[Executes: python3 $SKILL_GH_WS_HOME/github-workflow-security/scripts/harden-workflows.py]

Agent: ✅ Successfully hardened 3 workflow files:
- Added permissions to 1 workflow
- Pinned 12 action versions to commit SHAs

Would you like me to review the changes?

Example 2: Custom Permissions

User: Harden workflows with permissions for contents: read and pull-requests: write

Agent: I'll harden workflows with your custom permissions configuration.

[Executes: python3 $SKILL_GH_WS_HOME/github-workflow-security/scripts/harden-workflows.py \
  --permissions "permissions:\n  contents: read\n  pull-requests: write\n"]

Example 3: Add New Action to Mapping

User: Add actions/cache v4 to the mapping table

Agent: I'll query and save the commit hash for actions/cache v4.

[Executes: python3 $SKILL_GH_WS_HOME/github-workflow-security/scripts/get-action-commit.py actions/cache v4 --save]

Agent: ✅ Added actions/cache@v4 to mapping table:
- Commit SHA: 1234567890abcdef...
- Version: v4.1.0

Expected Output Format

When the hardening script runs, it produces output like:

🔍 Scanned 3 workflow files

📄 Processing file: .github/workflows/ci.yml
  ℹ️  Permissions already configured, skipping
  ✓ Replaced actions/checkout@v4 → 34e114876b0b... # v4.3.1
  ✓ Replaced docker/setup-buildx-action@v3 → 8d2750c68a42... # v3.12.0
  ✅ File updated

============================================================
📊 Processing Summary
============================================================
  Files scanned: 3
  Added permissions: 1
  Replaced action versions: 12

✅ All workflow files have been processed

Pre-mapped Actions

The mapping table at data/action-commit-map.json includes:

• actions/checkout (v2, v3, v4)
• actions/setup-java (v3, v4)
• actions/setup-node (v4)
• actions/cache (v4)
• pnpm/action-setup (v2, v4)
• docker/setup-buildx-action (v3)
• docker/login-action (v3)
• docker/build-push-action (v5)
• stCarolas/setup-maven (v5)
• whelk-io/maven-settings-xml-action (v22)

Important Notes

1. GitHub API Rate Limits: Unauthenticated requests limited to 60/hour. The mapping table helps avoid hitting this limit.

2. Git-Managed Changes: All modifications are tracked by Git - no additional backup needed before running.

3. Validation Required: After hardening, verify workflows still function correctly. Test in a feature branch first.

4. File Format Support: Works with both .yml and .yaml files.

5. Permissions Verification: Ensure added permissions meet actual workflow requirements. Too restrictive permissions may cause workflow failures.

6. Self-Contained: This skill is self-contained at $SKILL_GH_WS_HOME/github-workflow-security/.

Security Best Practices

1. Principle of Least Privilege: Only grant necessary permissions to workflows
2. Pin Versions: Always use commit SHAs instead of mutable tags
3. Regular Updates: Periodically check and update action versions to get security fixes
4. Audit Trail: Leverage Git history to track all modifications for compliance
5. Mapping Maintenance: Keep the mapping table up to date with latest stable versions
6. Review Changes: Always review modifications before committing to main branch
7. Test First: Test hardened workflows in a feature branch before merging

Error Handling

Common issues and solutions:

• Script not found: Ensure the skill is correctly installed at $SKILL_GH_WS_HOME/github-workflow-security/

• API rate limit exceeded: Wait for rate limit reset (1 hour) or:

  • Use authenticated GitHub API calls (set GITHUB_TOKEN environment variable)
  • Pre-populate mapping table for your commonly used actions

• Invalid workflow syntax: The script will report parsing errors

  • Fix YAML syntax issues manually
  • Validate with: actionlint .github/workflows/*.yml

• Network issues: If GitHub API is unreachable:

  • Retry after network is restored
  • Manually add commit SHA to mapping table

• Permission denied: Ensure scripts have execute permissions:

  • Run: chmod +x $SKILL_GH_WS_HOME/github-workflow-security/scripts/*.py

Follow-up Actions

After successfully hardening workflows, recommend:

1. Review changes: Offer to review the git diff
2. Test workflows: Suggest running workflows in a test branch
3. Add unmapped actions: Help user add any unmapped actions to mapping table
4. Documentation: Mention updating project documentation about pinned versions
5. Periodic audits: Recommend scheduling periodic security reviews
6. CI/CD integration: Suggest adding automated security checks to CI pipeline