Skip to content

Commit fb79e92

Browse files
svidgensvidgen
authored
fix: dependabots + scripting and prompting to help with dependabots (#3417)
<!-- Please make sure to read the Pull Request Guidelines: https://github.com/aws-amplify/amplify-cli/blob/master/CONTRIBUTING.md#pull-requests --> #### Description of changes 1. Updates deps 2. Adds scripting to help work with dependabot 3. Adds prompting for agents to make resolving dependabots more hands-off <!-- Thank you for your Pull Request! Please provide a description above and review the requirements below. --> ##### CDK / CloudFormation Parameters Changed <!-- Please list any changes to the CDK/CFN params, with a link to references https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html e.g. * Conditionally added support for `Code` based AppSync Functions: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-appsync-functionconfiguration.html#cfn-appsync-functionconfiguration-code * Conditionally added support for `Code` based AppSync Resolvers: https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-appsync-resolver.html#cfn-appsync-resolver-code --> #### Issue #, if available <!-- Also, please reference any associated PRs for documentation updates. --> #### Description of how you validated changes #### Checklist <!-- Remove items that do not apply. For completed items, change [ ] to [x]. --> - [ ] PR description included - [ ] `yarn test` passes - [ ] E2E test run linked - [ ] Tests are [changed or added](https://github.com/aws-amplify/amplify-cli/blob/master/CONTRIBUTING.md#tests) - [ ] Relevant documentation is changed or added (and PR referenced) - [ ] New AWS SDK calls or CloudFormation actions have been added to relevant test and service IAM policies - [ ] Any CDK or CloudFormation parameter changes are called out explicitly By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
1 parent 6d16a28 commit fb79e92

19 files changed

Lines changed: 10064 additions & 446 deletions

File tree

‎.agent-docs/DEPENDABOT.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Dependabot Upgrade Workflow
2+
3+
Guide for handling Dependabot alerts, dependency upgrades, and security fixes.
4+
5+
## Checking Dependabot Alerts
6+
7+
**Prerequisites:** GitHub CLI (`gh`) must be installed and authenticated.
8+
9+
Install:
10+
11+
```bash
12+
# macOS
13+
brew install gh
14+
15+
# Windows
16+
winget install GitHub.cli
17+
18+
# Linux
19+
# See https://github.com/cli/cli#installation
20+
```
21+
22+
Authenticate:
23+
24+
```bash
25+
gh auth login
26+
```
27+
28+
Check alerts:
29+
30+
```bash
31+
npx ts-node scripts/check-dependabot.ts
32+
```
33+
34+
## Workflow for Agents
35+
36+
When asked to handle dependency upgrades, security fixes, or Dependabot issues:
37+
38+
### 1. Check Outstanding Alerts
39+
40+
Run the Dependabot checker to get current alerts.
41+
42+
### 2. Summarize and Categorize
43+
44+
Group alerts into categories:
45+
46+
- **Dependency updates only** - Simple version bumps in package.json
47+
- **Code changes required** - Breaking changes needing code modifications
48+
- **Security fixes** - CVE patches (prioritize by severity: critical > high > medium > low)
49+
50+
Present summary to user with counts per category.
51+
52+
### 3. Ask User for Scope
53+
54+
Confirm what to address:
55+
56+
- All alerts in a single PR?
57+
- Only dependency updates?
58+
- Only security fixes above a certain severity?
59+
- Specific packages?
60+
61+
### 4. Make Changes
62+
63+
For each change:
64+
65+
- Update package.json (or relevant package files)
66+
- Run `yarn install` to update yarn.lock
67+
- Run `yarn build` to verify build succeeds
68+
- Run `yarn test` to verify tests pass
69+
- Fix any breaking changes if needed
70+
71+
### 5. Commit and Push
72+
73+
```bash
74+
git checkout -b dependabot-fixes-YYYY-MM-DD
75+
git add .
76+
git commit -m "fix: address dependabot alerts
77+
78+
- Update package1 to vX.Y.Z
79+
- Update package2 to vX.Y.Z
80+
- Fix breaking changes in ..."
81+
git push origin dependabot-fixes-YYYY-MM-DD
82+
```
83+
84+
### 6. E2E Test
85+
86+
Follow the e2e workflow from AGENTS.md:
87+
88+
```bash
89+
yarn cloud-e2e
90+
yarn e2e-monitor {batchId}
91+
```
92+
93+
### 7. Resolve Errors
94+
95+
- If e2e tests fail due to code issues, fix and repeat from step 4
96+
- If timeouts/quota errors, retry the build
97+
- Ask user for guidance if errors persist after multiple attempts
98+
99+
## Notes
100+
101+
- Always run local tests before pushing
102+
- Group related updates together when possible
103+
- Document breaking changes in commit messages
104+
- Check for peer dependency conflicts after updates

‎.agent-docs/LOCAL_E2E_TESTING.md‎

Lines changed: 280 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,280 @@
1+
# Local E2E Testing and Build Simulation
2+
3+
This guide explains how to run e2e test steps and build jobs locally to debug failures before pushing to CI.
4+
5+
## Overview
6+
7+
E2E tests run in AWS CodeBuild with specific build steps defined in `codebuild_specs/*.yml`. Each build spec calls functions from `shared-scripts.sh`. You can simulate these steps locally to debug issues.
8+
9+
## Prerequisites
10+
11+
### Authentication
12+
13+
Most e2e operations require AWS credentials. The repository uses `ada` (Amazon's credential management tool) for authentication, which is called automatically by the scripts.
14+
15+
**Setup:**
16+
17+
1. Ensure you have `ada` and `mwinit` installed
18+
2. Create `scripts/.env` file with account details:
19+
```bash
20+
# scripts/.env
21+
E2E_ACCOUNT_PROD=<account-id>
22+
E2E_ACCOUNT_BETA=<account-id>
23+
```
24+
3. If you see authentication errors, run `mwinit` in your terminal
25+
26+
**Note:** The scripts automatically call `ada` for credential refresh. You don't need to run `ada` commands manually.
27+
28+
## Common Build Steps
29+
30+
### 1. Unit Tests (`test` build)
31+
32+
**What it does:** Runs all unit tests with coverage in CI mode
33+
34+
**Command:**
35+
36+
```bash
37+
yarn test-ci
38+
```
39+
40+
**Equivalent to:**
41+
42+
```bash
43+
lerna run test --concurrency 1 -- --ci -i
44+
```
45+
46+
**Common issues:**
47+
48+
- Coverage threshold failures: Check `jest.config.js` in the failing package
49+
- Pre-existing coverage issues may not be related to your changes
50+
- To verify if an issue is pre-existing, test on the base branch
51+
52+
### 2. License Extraction (`verify_dependency_licenses_extract` build)
53+
54+
**What it does:** Extracts dependency licenses and verifies no changes
55+
56+
**Command:**
57+
58+
```bash
59+
yarn verify-dependency-licenses-extract
60+
```
61+
62+
**Equivalent to:**
63+
64+
```bash
65+
yarn extract-dependency-licenses && ./scripts/verify-dependency-licenses.sh
66+
```
67+
68+
**Common issues:**
69+
70+
- License changes after dependency updates are expected
71+
- Always commit `dependency_licenses.txt` changes with dependency updates
72+
- The pre-commit hook runs this automatically
73+
74+
### 3. Local Registry Publish (`publish_to_local_registry` build)
75+
76+
**What it does:** Publishes packages to a local Verdaccio registry for e2e testing
77+
78+
**Command:**
79+
80+
```bash
81+
# Start Verdaccio (in separate terminal)
82+
npx verdaccio
83+
84+
# Publish packages
85+
yarn publish-to-verdaccio
86+
```
87+
88+
**Common issues:**
89+
90+
- Requires Verdaccio running locally
91+
- May fail if packages have version conflicts
92+
- Check `lerna.json` for version configuration
93+
94+
### 4. Windows Build (`build_windows` build)
95+
96+
**What it does:** Builds all packages on Windows with Node.js 24.12.0
97+
98+
**Command (on Windows):**
99+
100+
```powershell
101+
yarn production-build
102+
yarn build-tests
103+
```
104+
105+
**Command (on macOS/Linux):**
106+
Cannot be fully simulated on non-Windows systems. However, you can:
107+
108+
```bash
109+
yarn production-build
110+
yarn build-tests
111+
```
112+
113+
**Common issues:**
114+
115+
- Path separator differences (Windows uses `\`, Unix uses `/`)
116+
- Line ending differences (CRLF vs LF)
117+
- Case-sensitive filesystem differences
118+
- Windows-specific Node.js modules
119+
120+
## Debugging E2E Failures
121+
122+
### Step 1: Identify the Failing Build
123+
124+
```bash
125+
yarn e2e-failed <batch-id>
126+
```
127+
128+
This shows which specific builds failed.
129+
130+
### Step 2: Get Build Logs
131+
132+
```bash
133+
yarn e2e-logs <build-id>
134+
```
135+
136+
This downloads and displays the full build log.
137+
138+
### Step 3: Simulate Locally
139+
140+
Run the equivalent local command (see sections above) to reproduce the issue.
141+
142+
### Step 4: Check for Pre-existing Issues
143+
144+
Before fixing, verify the issue exists on the base branch:
145+
146+
```bash
147+
# Stash your changes
148+
git stash
149+
150+
# Checkout base branch
151+
git checkout main
152+
153+
# Run the failing command
154+
yarn <command>
155+
156+
# Restore your changes
157+
git checkout <your-branch>
158+
git stash pop
159+
```
160+
161+
## E2E Test Workflow
162+
163+
### Full E2E Test Suite
164+
165+
```bash
166+
# 1. Commit and push all changes
167+
git push
168+
169+
# 2. Trigger e2e suite
170+
yarn cloud-e2e
171+
172+
# 3. Monitor with auto-retry
173+
yarn e2e-monitor <batch-id>
174+
```
175+
176+
### Targeted E2E Tests
177+
178+
You can run specific e2e test files locally:
179+
180+
```bash
181+
# Run specific test file
182+
cd packages/amplify-e2e-tests
183+
yarn e2e src/__tests__/api_1.test.ts
184+
```
185+
186+
**Note:** Local e2e tests still require AWS credentials and will create real resources in your AWS account.
187+
188+
## Common Failure Patterns
189+
190+
### 1. Transient Infrastructure Failures
191+
192+
**Symptoms:**
193+
194+
- Timeout errors
195+
- Credential expiration
196+
- Quota/limit errors
197+
198+
**Solution:** Retry the build
199+
200+
```bash
201+
yarn e2e-retry <batch-id>
202+
```
203+
204+
### 2. Code-Related Failures
205+
206+
**Symptoms:**
207+
208+
- Test failures
209+
- Build errors
210+
- Linting errors
211+
- Coverage threshold failures
212+
213+
**Solution:** Fix the code and re-run locally, then push and re-trigger e2e tests
214+
215+
### 3. Dependency-Related Failures
216+
217+
**Symptoms:**
218+
219+
- Module not found errors
220+
- Version conflicts
221+
- Breaking API changes
222+
223+
**Solution:**
224+
225+
- Check if dependency upgrade is necessary
226+
- Look for major version changes that may have breaking changes
227+
- Consider pinning to a compatible version
228+
229+
## Build Job Types
230+
231+
The e2e workflow includes these build types:
232+
233+
- `build_linux` - Build on Linux (not retried by monitor)
234+
- `build_windows` - Build on Windows (not retried by monitor)
235+
- `test` - Run unit tests (not retried by monitor)
236+
- `lint` - Run linting (not retried by monitor)
237+
- `verify_dependency_licenses_extract` - Verify licenses
238+
- `verify_api_extract` - Verify API surface
239+
- `verify_yarn_lock` - Verify yarn.lock consistency
240+
- `publish_to_local_registry` - Publish to Verdaccio
241+
- `graphql_e2e_tests_*` - GraphQL e2e test suites (171 jobs)
242+
243+
**Note:** The monitor script skips auto-retrying `build_linux`, `build_windows`, `test`, and `lint` because failures in these are typically code-related and require fixes, not retries.
244+
245+
## Tips
246+
247+
1. **Always test locally first** before pushing to CI
248+
2. **Check pre-commit hooks** - they run tests automatically
249+
3. **Monitor resource usage** - e2e tests create real AWS resources
250+
4. **Clean up resources** - use `yarn cleanup-stale-resources` periodically
251+
5. **Check credentials** - most failures are due to expired credentials
252+
6. **Read the logs** - build logs contain detailed error information
253+
254+
## Troubleshooting
255+
256+
### "Command failed with exit code 1"
257+
258+
This is a generic error. Check the full output for the actual error message.
259+
260+
### "Cannot read properties of undefined"
261+
262+
Often indicates a dependency version mismatch or breaking API change.
263+
264+
### "Coverage threshold not met"
265+
266+
Check if this is a pre-existing issue by testing on the base branch. Coverage can change due to:
267+
268+
- Code changes
269+
- Dependency updates affecting how coverage is calculated
270+
- Test changes
271+
272+
### "License change detected"
273+
274+
Expected when updating dependencies. Run `yarn extract-dependency-licenses` and commit the changes.
275+
276+
## Related Documentation
277+
278+
- [DEPENDABOT.md](./DEPENDABOT.md) - Dependency update workflow
279+
- [AGENTS.md](../AGENTS.md) - General agent workflow
280+
- [shared-scripts.sh](../shared-scripts.sh) - Build step implementations

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ yarn-error.log
1010
coverage
1111
.nyc_output
1212
.env
13+
.github-token
1314
UNIFIED_CHANGELOG.md
1415
package-lock.json
1516
packages/amplify-cli/amplify/.config/

0 commit comments

Comments
 (0)