Managing sensitive credentials like API keys across multiple GitHub repositories is challenging. It leads to duplicate secrets, a lack of versioning, and potential inconsistencies between environments.
The solution is to use HashiCorp Vault Secrets on the HashiCorp Cloud Platform (HCP) to create a single, secure source of truth that automatically synchronizes secrets to your GitHub Actions workflows.
Step 1: Define the Problem with a Failing Workflow
First, we establish a baseline by creating a simple GitHub Actions workflow that will fail because the necessary secret is missing. This mirrors the real-world issue before centralization.
Example Workflow (.github/workflows/vault-demo.yaml)
This workflow is manually triggered and checks for the existence of an AWS_API_KEY.
YAML
name: Vault Demo
on:
# Manually trigger the workflow from the GitHub UI
workflow_dispatch:
jobs:
echo-vault-secret:
runs-on: ubuntu-latest
steps:
- name: Verify AWS_API_KEY exists
run: |
# Check if the secret is empty (i.e., not found)
if [[ -z "${{ secrets.AWS_API_KEY }}" ]]; then
echo "::error::Secret Not Found"
# Exit with a non-zero code to indicate failure
exit 1
else
echo "::notice::Secret Found"
fi
Purpose:
When you run this workflow, it will immediately fail because the AWS_API_KEY secret has not been defined in the repository settings.
We use HashiCorp Vault Secrets on the HashiCorp Cloud Platform (HCP) to create a secure, centralized store.
Details and Purpose:
Access HCP Vault Secrets: Log in to the HCP dashboard and select Vault Secrets (the fully managed service).
Create an Application: Create a new application (e.g., Secret App) within your project. This acts as a logical container for your secrets.
Add the Secret: Within the application, add the sensitive key-value pair.
This action ensures that your secret is now stored centrally with versioning and audit logs.
Step 3: Integrate Vault Secrets with GitHub Actions
Now we establish the automatic synchronization connection between Vault and your GitHub repository.
Details and Purpose:
Navigate to Integrations: In the Vault Secrets console, go to Integrations on the left menu.
Select GitHub Actions: Choose the GitHub Actions option for integration.
Authorize GitHub: You will be prompted to authorize Vault's access to your GitHub account.
Configure Sync Destination: Select the specific repository (e.g., action-one-repository) that contains the Vault Demo workflow.
Save & Sync: Configure the sync destination and click Save and Sync Secrets.
- Purpose: Vault automatically pushes the
AWS_API_KEY secret to the target repository's secrets store. This process synchronizes the secret, eliminating the need to manually update it in GitHub.
Step 4: Verify Success and Centralized Management
The final step is to confirm that the synchronization worked and that your workflow can now successfully access the secret.
Verification:
Check GitHub Secrets: Navigate to your GitHub repository's Settings → Secrets and variables → Actions. The AWS_API_KEY secret, which was manually added by the Vault integration, should now be present.
Rerun the Workflow: Rerun the Vault Demo workflow from the GitHub Actions tab.
Expected Result:
The workflow will now successfully execute. In the logs, you will see the output confirming that the secret was found:
::notice::Secret Found
Note: GitHub's security features ensure that the actual value of ${{ secrets.AWS_API_KEY }} is automatically masked with asterisks (***) in the logs, even if you try to print it.
Key Benefits
By centralizing, you gain:
Single Source of Truth: Manage secrets for all repositories from one place.
Automatic Synchronization: Changes in Vault are instantly reflected in GitHub.
Auditability: Vault provides a detailed log of all secret access and changes.
