Skip to content

Commit 1062785

Browse files
frankbriafrankbria
committed
refactor: use GitHub Actions environments with generic secret names
BREAKING CHANGE: Deployment workflow now uses environment-scoped secrets - Changed from repository-wide secrets to environment-specific secrets - Added 'environment: staging' to deployment job - Renamed secrets without STAGING_ prefix: - STAGING_SSH_KEY → SSH_KEY - STAGING_HOST → HOST - STAGING_USER → USER - STAGING_PROJECT_PATH → PROJECT_PATH - Updated documentation to reflect environment-based configuration - Added section on using multiple environments (staging, production) - Secrets now configured in Settings → Environments → staging Benefits: - Same secret names can be reused across environments - Better separation of concerns per environment - Supports environment protection rules and approvals
1 parent 839e71f commit 1062785

3 files changed

Lines changed: 69 additions & 46 deletions

File tree

‎.github/workflows/deploy-staging.yml‎

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ jobs:
1111
deploy:
1212
name: Deploy to Staging Server
1313
runs-on: ubuntu-latest
14+
environment: staging
1415
needs: []
1516
# Note: To enforce CI before deploy, add this after CI workflow is tested:
1617
# needs: [ci-tests]
@@ -21,8 +22,8 @@ jobs:
2122

2223
- name: Configure SSH
2324
env:
24-
SSH_KEY: ${{ secrets.STAGING_SSH_KEY }}
25-
SSH_HOST: ${{ secrets.STAGING_HOST }}
25+
SSH_KEY: ${{ secrets.SSH_KEY }}
26+
SSH_HOST: ${{ secrets.HOST }}
2627
run: |
2728
mkdir -p ~/.ssh
2829
echo "$SSH_KEY" > ~/.ssh/staging_key
@@ -31,18 +32,18 @@ jobs:
3132
3233
- name: Pre-deployment health check
3334
env:
34-
SSH_HOST: ${{ secrets.STAGING_HOST }}
35-
SSH_USER: ${{ secrets.STAGING_USER }}
35+
SSH_HOST: ${{ secrets.HOST }}
36+
SSH_USER: ${{ secrets.USER }}
3637
run: |
3738
ssh -i ~/.ssh/staging_key -o StrictHostKeyChecking=no \
3839
"$SSH_USER@$SSH_HOST" \
3940
'echo "Server reachable"'
4041
4142
- name: Deploy to staging
4243
env:
43-
SSH_HOST: ${{ secrets.STAGING_HOST }}
44-
SSH_USER: ${{ secrets.STAGING_USER }}
45-
PROJECT_PATH: ${{ secrets.STAGING_PROJECT_PATH }}
44+
SSH_HOST: ${{ secrets.HOST }}
45+
SSH_USER: ${{ secrets.USER }}
46+
PROJECT_PATH: ${{ secrets.PROJECT_PATH }}
4647
BRANCH: ${{ github.ref_name }}
4748
run: |
4849
ssh -i ~/.ssh/staging_key -o StrictHostKeyChecking=no \
@@ -84,8 +85,8 @@ jobs:
8485

8586
- name: Post-deployment health checks
8687
env:
87-
SSH_HOST: ${{ secrets.STAGING_HOST }}
88-
SSH_USER: ${{ secrets.STAGING_USER }}
88+
SSH_HOST: ${{ secrets.HOST }}
89+
SSH_USER: ${{ secrets.USER }}
8990
run: |
9091
ssh -i ~/.ssh/staging_key -o StrictHostKeyChecking=no \
9192
"$SSH_USER@$SSH_HOST" << 'ENDSSH'
@@ -121,8 +122,8 @@ jobs:
121122
echo "✅ Deployment to staging successful"
122123
echo "Branch: ${{ github.ref_name }}"
123124
echo "Commit: ${{ github.sha }}"
124-
echo "Frontend: http://${{ secrets.STAGING_HOST }}:14100"
125-
echo "Backend: http://${{ secrets.STAGING_HOST }}:14200"
125+
echo "Frontend: http://${{ secrets.HOST }}:14100"
126+
echo "Backend: http://${{ secrets.HOST }}:14200"
126127
127128
- name: Cleanup SSH key
128129
if: always()

‎docs/github-actions-ssh-setup.md‎

Lines changed: 52 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# GitHub Actions SSH Setup for Staging Deployment
1+
# GitHub Actions SSH Setup for Deployments
22

3-
This document describes how to configure SSH access for GitHub Actions to deploy to the staging server.
3+
This document describes how to configure SSH access for GitHub Actions to deploy to staging (and other environments).
44

55
## Prerequisites
66

@@ -52,16 +52,23 @@ ssh -i ~/.ssh/github_actions_staging your-user@staging-server 'echo "Connection
5252

5353
Expected output: "Connection successful"
5454

55-
## Step 4: Add Secrets to GitHub Repository
55+
## Step 4: Configure GitHub Environment and Secrets
56+
57+
### Create Environment
5658

5759
1. Go to your repository on GitHub
58-
2. Navigate to: **Settings** → **Secrets and variables** → **Actions**
59-
3. Click **New repository secret**
60-
4. Add the following secrets:
60+
2. Navigate to: **Settings** → **Environments**
61+
3. Click **New environment**
62+
4. Name: `staging`
63+
5. Click **Configure environment**
64+
65+
### Add Environment Secrets
6166

62-
### STAGING_SSH_KEY
67+
In the staging environment configuration, add the following secrets:
6368

64-
- Name: `STAGING_SSH_KEY`
69+
### SSH_KEY
70+
71+
- Name: `SSH_KEY`
6572
- Value: Contents of `~/.ssh/github_actions_staging` (private key)
6673

6774
```bash
@@ -70,32 +77,35 @@ cat ~/.ssh/github_actions_staging
7077
# Copy the entire output including BEGIN and END lines
7178
```
7279

73-
### STAGING_HOST
80+
### HOST
7481

75-
- Name: `STAGING_HOST`
82+
- Name: `HOST`
7683
- Value: Staging server hostname or IP address
7784
- Example: `staging.example.com` or `192.168.1.100`
7885

79-
### STAGING_USER
86+
### USER
8087

81-
- Name: `STAGING_USER`
88+
- Name: `USER`
8289
- Value: SSH username on staging server
8390
- Example: `frankbria`
8491

85-
### STAGING_PROJECT_PATH
92+
### PROJECT_PATH
8693

87-
- Name: `STAGING_PROJECT_PATH`
94+
- Name: `PROJECT_PATH`
8895
- Value: Absolute path to the CodeFRAME project on staging server
8996
- Example: `/home/frankbria/projects/codeframe`
9097

91-
## Step 5: Verify Secrets
98+
**Note**: These generic secret names can be reused across different environments (staging, production, etc.) by configuring them in each environment separately.
99+
100+
## Step 5: Verify Environment Configuration
92101

93-
After adding all secrets, verify they appear in the secrets list:
102+
After adding all secrets, verify in **Settings** → **Environments** → **staging**:
94103

95-
- STAGING_SSH_KEY
96-
- STAGING_HOST
97-
- STAGING_USER
98-
- STAGING_PROJECT_PATH
104+
- ✅ Environment exists
105+
- ✅ SSH_KEY configured
106+
- ✅ HOST configured
107+
- ✅ USER configured
108+
- ✅ PROJECT_PATH configured
99109

100110
## Step 6: Test Deployment Workflow
101111

@@ -115,39 +125,51 @@ After adding all secrets, verify they appear in the secrets list:
115125
- Rotate SSH keys every 90 days
116126
- To rotate:
117127
1. Generate new key pair
118-
2. Add new public key to staging server
119-
3. Update `STAGING_SSH_KEY` secret in GitHub
120-
4. Remove old public key from staging server
128+
2. Add new public key to deployment server
129+
3. Update `SSH_KEY` secret in the environment (Settings → Environments → staging)
130+
4. Remove old public key from deployment server
121131
5. Delete old private key locally
122132

123133
### Access Control
124134
- Only grant repository admin access to trusted users
125-
- Consider using a dedicated deployment user on staging server
135+
- Consider using a dedicated deployment user on the server
126136
- Audit secret access logs regularly
137+
- Use environment protection rules to require approvals for sensitive deployments
127138

128139
## Troubleshooting
129140

130141
### "Permission denied (publickey)"
131-
- Verify public key is in `~/.ssh/authorized_keys` on staging server
142+
- Verify public key is in `~/.ssh/authorized_keys` on deployment server
132143
- Check file permissions: `authorized_keys` should be 600, `.ssh` should be 700
133-
- Verify `STAGING_SSH_KEY` secret contains the complete private key
144+
- Verify `SSH_KEY` environment secret contains the complete private key
134145

135146
### "Host key verification failed"
136147
- Workflow includes `ssh-keyscan` to add host key automatically
137148
- If issue persists, manually add host key to workflow
138149

139150
### "Connection refused"
140-
- Verify `STAGING_HOST` is correct
141-
- Ensure staging server is accessible from internet
151+
- Verify `HOST` environment secret is correct
152+
- Ensure deployment server is accessible from internet
142153
- Check firewall settings allow SSH (port 22)
143154

144155
### "No such file or directory" during deployment
145-
- Verify `STAGING_PROJECT_PATH` is correct
146-
- Ensure project directory exists on staging server
156+
- Verify `PROJECT_PATH` environment secret is correct
157+
- Ensure project directory exists on deployment server
147158
- Check user has read/write permissions to project directory
148159

160+
## Using Multiple Environments
161+
162+
To configure production or other environments:
163+
164+
1. Create a new environment (e.g., `production`)
165+
2. Add the same secret names (`SSH_KEY`, `HOST`, `USER`, `PROJECT_PATH`) with different values
166+
3. Update workflow to reference the appropriate environment
167+
168+
This pattern allows using the same secret names across all environments while maintaining environment-specific values.
169+
149170
## Additional Resources
150171

172+
- [GitHub Actions Environments](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment)
151173
- [GitHub Actions SSH documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers)
152174
- [SSH key generation guide](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent)
153175
- [PM2 deployment documentation](https://pm2.keymetrics.io/docs/usage/deployment/)

‎docs/testing-github-workflows.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -71,11 +71,11 @@ Test that CI fails on test failures:
7171
### Prerequisites
7272

7373
- [ ] SSH keys generated and configured (see `docs/github-actions-ssh-setup.md`)
74-
- [ ] GitHub Secrets added:
75-
- `STAGING_SSH_KEY`
76-
- `STAGING_HOST`
77-
- `STAGING_USER`
78-
- `STAGING_PROJECT_PATH`
74+
- [ ] GitHub Environment `staging` created with secrets:
75+
- `SSH_KEY`
76+
- `HOST`
77+
- `USER`
78+
- `PROJECT_PATH`
7979
- [ ] Health check endpoints implemented (`/health` on backend and frontend)
8080
- [ ] Staging server accessible from internet
8181

0 commit comments

Comments
 (0)