From 0820c02230ce9a298d8fabecf70187abeb6b25cb Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Sat, 11 Jul 2026 13:38:33 +0200 Subject: [PATCH] docs(references): trim gh-CLI basics and dependency-config boilerplate Cut generic gh CLI command listings (repo info, PR list/view/merge, branch protection gets, Actions run listing, release/tag commands, file contents API, repo settings) from gh-cli-reference.md, keeping the GHCR permission gotcha and all Common Troubleshooting Patterns content untouched. Cut generic Dependabot/Renovate config boilerplate (basic/extended config, ecosystem table, commit-message prefixes, ignore rules, reviewers, grouping/security/PHP/Go presets), the Dependabot-vs- Renovate feature comparison, and the best-practices listicle from dependency-management.md. Kept ecosystem-hygiene and target-branch gotchas, the auto-merge mechanics, branch-protection requirements, and every troubleshooting pattern. Signed-off-by: Sebastian Mendel --- .../references/dependency-management.md | 278 ------------------ .../references/gh-cli-reference.md | 163 +--------- 2 files changed, 1 insertion(+), 440 deletions(-) diff --git a/skills/github-project/references/dependency-management.md b/skills/github-project/references/dependency-management.md index af7e7b4..1793b2f 100644 --- a/skills/github-project/references/dependency-management.md +++ b/skills/github-project/references/dependency-management.md @@ -4,37 +4,6 @@ Dependabot and Renovate configuration patterns, auto-merge workflows, and troubl ## Dependabot -### Basic Configuration -```yaml -# .github/dependabot.yml -version: 2 -updates: - - package-ecosystem: "gomod" - directory: "/" - schedule: - interval: "weekly" - day: "monday" - time: "06:00" - timezone: "Europe/Berlin" -``` - -### Package Ecosystems - -| Ecosystem | Languages/Tools | -|-----------|-----------------| -| gomod | Go modules | -| npm | JavaScript/Node.js | -| composer | PHP | -| pip | Python | -| cargo | Rust | -| maven | Java | -| gradle | Java/Kotlin | -| nuget | .NET | -| bundler | Ruby | -| docker | Dockerfiles | -| github-actions | GitHub Actions | -| terraform | Terraform | - ### Ecosystem Hygiene — Only Declare What the Repo Actually Has Dependabot's update job runs on the ecosystems configured, whether or not the manifest files exist. Some ecosystems **hard-fail** when their manifest is missing; others silently no-op. Declaring ecosystems that don't apply turns main red on every scheduled Dependabot run, for no benefit: @@ -122,121 +91,8 @@ updates: dependency-type: "development" ``` -### Commit Message Prefixes -```yaml -updates: - - package-ecosystem: "gomod" - directory: "/" - schedule: - interval: "weekly" - commit-message: - prefix: "deps" - prefix-development: "deps(dev)" - include: "scope" - labels: - - "dependencies" -``` - -### Multiple Ecosystems -```yaml -version: 2 -updates: - - package-ecosystem: "gomod" - directory: "/" - schedule: - interval: "weekly" - groups: - dependencies: - patterns: - - "*" - commit-message: - prefix: "deps" - labels: - - "dependencies" - - - package-ecosystem: "github-actions" - directory: "/" - schedule: - interval: "weekly" - groups: - github-actions: - patterns: - - "*" - commit-message: - prefix: "ci" - labels: - - "dependencies" - - "github-actions" - - - package-ecosystem: "docker" - directory: "/" - schedule: - interval: "weekly" - commit-message: - prefix: "docker" - labels: - - "dependencies" - - "docker" -``` - -### Ignoring Dependencies -```yaml -updates: - - package-ecosystem: "npm" - directory: "/" - schedule: - interval: "weekly" - ignore: - - dependency-name: "lodash" - versions: [">=5.0.0"] - - dependency-name: "react" - update-types: ["version-update:semver-major"] -``` - -### Reviewers and Assignees -```yaml -updates: - - package-ecosystem: "gomod" - directory: "/" - schedule: - interval: "weekly" - reviewers: - - "username" - - "org/team-name" - assignees: - - "username" -``` - ## Renovate -### Basic Configuration -```json -{ - "$schema": "https://docs.renovatebot.com/renovate-schema.json", - "extends": [ - "config:recommended" - ] -} -``` - -### Extended Configuration -```json -{ - "$schema": "https://docs.renovatebot.com/renovate-schema.json", - "extends": [ - "config:recommended", - ":semanticCommits", - ":semanticCommitTypeAll(chore)", - "group:allNonMajor" - ], - "labels": ["dependencies"], - "prHourlyLimit": 2, - "prConcurrentLimit": 5, - "timezone": "Europe/Berlin", - "schedule": ["before 7am on monday"] -} -``` - ### Auto-merge Configuration (Recommended) **IMPORTANT:** Use `platformAutomerge: true` to leverage Renovate's bypass permissions: @@ -262,93 +118,6 @@ updates: | `platformAutomerge` | `true` | Use GitHub's auto-merge (Renovate enables it) | | `automerge` | `true` | Enable auto-merge for matching packages | -### Lock File Maintenance - -Use Renovate for lock file updates instead of CI workflows that push directly to main: - -```json -{ - "lockFileMaintenance": { - "enabled": true, - "schedule": ["before 6am on monday"] - } -} -``` - -**Why:** CI workflows cannot push to protected branches. Renovate creates PRs that go through normal review/merge process. - -### Grouping Rules -```json -{ - "extends": ["config:recommended"], - "packageRules": [ - { - "matchPackagePatterns": ["^@types/"], - "groupName": "TypeScript types" - }, - { - "matchPackagePatterns": ["eslint"], - "groupName": "ESLint" - }, - { - "matchPackagePatterns": ["^react"], - "groupName": "React" - } - ] -} -``` - -### Security Updates -```json -{ - "extends": [ - "config:recommended", - ":enableVulnerabilityAlerts" - ], - "vulnerabilityAlerts": { - "labels": ["security"], - "automerge": true - } -} -``` - -### PHP/Composer Configuration -```json -{ - "extends": ["config:recommended"], - "composer": { - "enabled": true - }, - "packageRules": [ - { - "matchPackagePatterns": ["^typo3/"], - "groupName": "TYPO3" - }, - { - "matchPackagePatterns": ["^phpstan/", "^phpunit/"], - "groupName": "PHP dev tools" - } - ] -} -``` - -### Go Configuration -```json -{ - "extends": ["config:recommended"], - "gomod": { - "enabled": true - }, - "packageRules": [ - { - "matchManagers": ["gomod"], - "matchUpdateTypes": ["minor", "patch"], - "automerge": true - } - ] -} -``` - ## Auto-merge Workflow ### Auto-merge Decision Matrix @@ -740,50 +509,3 @@ PRs modifying workflow files require manual merge by a repository admin. ``` The lockfile `name` then stays stable regardless of which worktree folder you run `npm install` in. This bites specifically in git worktree workflows; a plain clone (dir == repo name) masks it. - -## Comparison: Dependabot vs Renovate - -| Feature | Dependabot | Renovate | -|---------|------------|----------| -| Hosting | GitHub native | Self-hosted or app | -| Configuration | YAML | JSON/JSON5 | -| Grouping | Basic | Advanced | -| Auto-merge | Via workflow | Native `platformAutomerge` | -| Bypass permissions | Via `GITHUB_TOKEN` | Direct (when in bypass list) | -| Lock file maintenance | Manual | Built-in | -| Custom managers | Limited | Regex support | -| Dashboard | Basic | Dependency Dashboard | -| Presets | Limited | Extensive | -| Update types | All | Granular control | -| Rebase on demand | `@dependabot rebase` | `@renovate rebase` | - -### When to Use Dependabot -- GitHub-only projects -- Simple dependency management -- Native GitHub integration preferred -- Limited configuration needs - -### When to Use Renovate -- Complex grouping requirements -- Multiple repositories -- Advanced auto-merge rules (use `platformAutomerge`) -- Custom package managers -- Dependency Dashboard needed -- Cross-platform support -- Need bypass permissions for auto-merge - -## Best Practices - -1. **Use Renovate's `platformAutomerge`**: For bypass permissions to work correctly -2. **Avoid `require_code_owner_reviews`**: With dependency auto-merge -3. **Match check names exactly**: In branch protection rules -4. **Use lock file maintenance**: Instead of CI pushing to main -5. **Group related updates**: Reduce PR noise -6. **Use semantic commit prefixes**: Better changelogs -7. **Enable auto-merge for safe updates**: minor/patch/pin/digest -8. **Require CI checks**: Before auto-merge -9. **Review major updates manually**: Breaking changes -10. **Schedule updates**: Off-peak hours -11. **Label PRs**: Easy filtering -12. **Limit concurrent PRs**: Avoid CI overload -13. **Add `workflow_dispatch`**: For manual workflow triggers diff --git a/skills/github-project/references/gh-cli-reference.md b/skills/github-project/references/gh-cli-reference.md index cb59cd9..6d7bf22 100644 --- a/skills/github-project/references/gh-cli-reference.md +++ b/skills/github-project/references/gh-cli-reference.md @@ -1,141 +1,6 @@ # gh CLI Commands Reference -Essential `gh` CLI commands for GitHub repository management. - -## Repository Information - -```bash -# Get repo info -gh repo view OWNER/REPO --json name,defaultBranchRef,description - -# List branches -gh api repos/OWNER/REPO/branches --jq '.[].name' - -# Get branch protection rules -gh api repos/OWNER/REPO/branches/main/protection -``` - -## Pull Requests - -```bash -# List PRs -gh pr list --repo OWNER/REPO --state open - -# View PR details -gh pr view NUMBER --repo OWNER/REPO --json state,mergeStateStatus,reviewDecision,autoMergeRequest - -# Check PR merge status (GraphQL - more detailed) -gh api graphql -f query='query($owner:String!,$repo:String!,$pr:Int!){ - repository(owner:$owner,name:$repo){pullRequest(number:$pr){ - state mergeStateStatus reviewDecision mergeable - autoMergeRequest{enabledBy{login}mergeMethod} - commits(last:1){nodes{commit{statusCheckRollup{state}}}} - }} -}' -f owner=OWNER -f repo=REPO -F pr=NUMBER - -# Approve PR -gh pr review NUMBER --repo OWNER/REPO --approve - -# Enable auto-merge -gh pr merge NUMBER --repo OWNER/REPO --auto --merge - -# Merge PR directly -gh pr merge NUMBER --repo OWNER/REPO --merge # or --squash, --rebase - -# Wait for PR CI to finish — use the native watcher, NOT a hand-rolled poll loop -gh pr checks NUMBER --repo OWNER/REPO --watch --fail-fast - -# Comment on PR -gh pr comment NUMBER --repo OWNER/REPO --body "message" - -# Trigger bot rebase -gh pr comment NUMBER --repo OWNER/REPO --body "@dependabot rebase" -gh pr comment NUMBER --repo OWNER/REPO --body "@renovate rebase" -``` - -## Branch Protection - -```bash -# Get full branch protection -gh api repos/OWNER/REPO/branches/main/protection - -# Get required status checks -gh api repos/OWNER/REPO/branches/main/protection/required_status_checks - -# Update required status checks -gh api repos/OWNER/REPO/branches/main/protection/required_status_checks -X PATCH \ - --input - << 'EOF' -{ - "strict": true, - "checks": [ - {"context": "lint"}, - {"context": "build"}, - {"context": "test"} - ] -} -EOF - -# Get/update PR review requirements -gh api repos/OWNER/REPO/branches/main/protection/required_pull_request_reviews - -# Disable code owner reviews, add bypass apps -gh api repos/OWNER/REPO/branches/main/protection/required_pull_request_reviews -X PATCH \ - --input - << 'EOF' -{ - "require_code_owner_reviews": false, - "required_approving_review_count": 1, - "bypass_pull_request_allowances": { - "apps": ["dependabot", "renovate"] - } -} -EOF -``` - -## GitHub Actions - -```bash -# List workflow runs -gh run list --repo OWNER/REPO --limit 10 - -# List runs for specific workflow -gh run list --repo OWNER/REPO --workflow=build.yml - -# View run details -gh run view RUN_ID --repo OWNER/REPO - -# View failed logs -gh run view RUN_ID --repo OWNER/REPO --log-failed - -# Re-run failed jobs (genuine flakes only — see caveat below) -gh run rerun RUN_ID --repo OWNER/REPO --failed - -# Wait for a workflow run to finish (native watcher, prefer over hand-rolled loops) -gh run watch RUN_ID --repo OWNER/REPO - -# Manually trigger workflow -gh workflow run WORKFLOW.yml --repo OWNER/REPO --ref main - -# List workflows -gh workflow list --repo OWNER/REPO -``` - -## Releases and Tags - -```bash -# List releases -gh release list --repo OWNER/REPO - -# Create release (after pushing signed tag) -git tag -s vX.Y.Z -m "vX.Y.Z" -git push origin vX.Y.Z -gh release create vX.Y.Z --repo OWNER/REPO --title "vX.Y.Z" --notes "Release notes" - -# Get latest release -gh release view --repo OWNER/REPO - -# Download release assets -gh release download TAG --repo OWNER/REPO -``` +Non-obvious `gh` CLI gotchas and troubleshooting patterns for GitHub repository management. For basic `gh pr`/`gh run`/`gh api` usage, `gh help` and `gh --help` cover it. ## Packages (GHCR) @@ -158,32 +23,6 @@ Verify the token's effective scopes from GitHub's response header, not `gh auth gh api "" --include 2>&1 | grep -i '^X-Oauth-Scopes:' ``` -## Files and Content - -```bash -# Get file contents (base64 encoded) -gh api repos/OWNER/REPO/contents/PATH --jq '.content' | base64 -d - -# Update file via API -gh api repos/OWNER/REPO/contents/PATH -X PUT \ - -f message="commit message" \ - -f content="$(base64 -w0 < file)" \ - -f sha="$(gh api repos/OWNER/REPO/contents/PATH --jq '.sha')" -``` - -## Repository Settings - -```bash -# Update repo settings -gh repo edit OWNER/REPO --enable-projects --enable-wiki=false - -# Set topics -gh api repos/OWNER/REPO/topics -X PUT -f names='["topic1","topic2"]' - -# Update description -gh repo edit OWNER/REPO --description "New description" -``` - ## Common Troubleshooting Patterns ### Wait for CI with the native watcher, not a hand-rolled loop