Skip to content

Commit 7f1ae7f

Browse files
claudeclaude
committed
docs: add GitHub repository configuration steps to setup guide
Add comprehensive repository settings configuration to both README.md and branch-protection.md: - Always suggest updating pull request branches - Allow auto-merge for automated workflows - Automatically delete head branches after merge - Allow GitHub Actions to create and approve pull requests (repo and org level) - Require actions to be pinned to full-length commit SHA These settings are essential for: - Auto-PR workflow (claude/** branches) - Release-please automation - Renovate auto-merge - Enhanced supply chain security (SLSA) Includes detailed explanations, benefits, security notes, and verification checklist.
1 parent ffe008d commit 7f1ae7f

2 files changed

Lines changed: 152 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -105,10 +105,21 @@
105105
- Add `NPM_TOKEN` in repository Settings → Secrets and variables → Actions
106106
- Required for automated NPM publishing
107107

108-
4. **Configure branch protection** (recommended):
108+
4. **Configure repository settings** (recommended):
109+
- Go to Settings → General → Pull Requests:
110+
- ✅ Always suggest updating pull request branches
111+
- ✅ Allow auto-merge
112+
- ✅ Automatically delete head branches
113+
- Go to Settings → Actions → General → Workflow permissions:
114+
- ✅ Allow GitHub Actions to create and approve pull requests
115+
- Go to Settings → Code security and analysis → Pinned actions:
116+
- ✅ Require actions to be pinned to a full-length commit SHA
117+
- See [docs/deployment/branch-protection.md](docs/deployment/branch-protection.md) for complete setup guide
118+
119+
5. **Configure branch protection** (recommended):
109120
- Follow [docs/deployment/branch-protection.md](docs/deployment/branch-protection.md)
110121

111-
5. **Start coding!**:
122+
6. **Start coding!**:
112123
- Write tests first (TDD methodology)
113124
- Replace sample code in `src/index.ts`
114125
- Update tests in `tests/index.test.ts`

‎docs/deployment/branch-protection.md‎

Lines changed: 139 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
# Branch Protection Setup Guide
22

3-
This guide explains how to configure branch protection rules for the `main` branch to ensure code quality and security.
3+
This guide explains how to configure branch protection rules and repository settings for the `main` branch to ensure code quality and security.
44

55
## Table of Contents
66

7+
- [Repository Settings (Required First)](#repository-settings-required-first)
78
- [Why Branch Protection?](#why-branch-protection)
89
- [Recommended Settings](#recommended-settings)
910
- [Step-by-Step Setup](#step-by-step-setup)
@@ -12,6 +13,143 @@ This guide explains how to configure branch protection rules for the `main` bran
1213

1314
---
1415

16+
## Repository Settings (Required First)
17+
18+
**Before configuring branch protection**, set up these essential repository settings:
19+
20+
### Pull Request Settings
21+
22+
Navigate to: **Settings → General → Pull Requests**
23+
24+
#### Always suggest updating pull request branches
25+
26+
- ✅ **Enable this setting**
27+
28+
**What it does:**
29+
- Shows a button to update PR branches when they're behind the base branch
30+
- Helps prevent merge conflicts
31+
- Ensures PRs are tested against latest code
32+
33+
**Benefits:**
34+
- Reduces "works on my branch but fails on main" issues
35+
- Makes it easier to keep PRs up to date
36+
- Improves CI/CD reliability
37+
38+
#### Allow auto-merge
39+
40+
- ✅ **Enable this setting**
41+
42+
**What it does:**
43+
- Allows PRs to be marked for automatic merge when all checks pass
44+
- Used by Renovate and auto-pr.yml workflow
45+
- Merges automatically when all requirements are met
46+
47+
**Benefits:**
48+
- Enables automated dependency updates
49+
- Reduces manual PR management
50+
- Works with claude/** branch auto-PR workflow
51+
52+
**Note:** Auto-merge respects branch protection rules - PRs won't merge unless all required checks pass.
53+
54+
#### Automatically delete head branches
55+
56+
- ✅ **Enable this setting**
57+
58+
**What it does:**
59+
- Automatically deletes feature branches after PR merge
60+
- Keeps repository clean
61+
- Reduces clutter from old branches
62+
63+
**Benefits:**
64+
- No manual branch cleanup needed
65+
- Prevents confusion from stale branches
66+
- Maintains clean branch list
67+
68+
**Note:** Only deletes head branches, never the base branch (main).
69+
70+
### GitHub Actions Permissions
71+
72+
Navigate to: **Settings → Actions → General → Workflow permissions**
73+
74+
#### Allow GitHub Actions to create and approve pull requests
75+
76+
- ✅ **Enable this setting**
77+
78+
**What it does:**
79+
- Allows workflows to create PRs programmatically
80+
- Used by auto-pr.yml workflow for claude/** branches
81+
- Enables release-please to create release PRs
82+
83+
**Benefits:**
84+
- Enables auto-pr.yml workflow
85+
- Allows release-please to function
86+
- Supports automated workflows
87+
88+
**Required for:**
89+
- `auto-pr.yml` - Creates PRs from claude/** branches
90+
- `release-please.yml` - Creates release PRs
91+
- Any custom automation that creates PRs
92+
93+
**Security note:** This permission is safe because:
94+
- Workflows still run from your repository
95+
- Branch protection rules still apply
96+
- Status checks must still pass
97+
98+
**Organization-level setting:**
99+
100+
If this is an organization repository, you may also need to enable this at the organization level:
101+
102+
1. Go to: **Organization Settings → Actions → General**
103+
2. Under "Workflow permissions", enable:
104+
- ✅ Allow GitHub Actions to create and approve pull requests
105+
106+
### Code Security Settings
107+
108+
Navigate to: **Settings → Code security and analysis**
109+
110+
#### Require actions to be pinned to a full-length commit SHA
111+
112+
- ✅ **Enable this setting** (if available)
113+
114+
**What it does:**
115+
- Requires GitHub Actions to use full commit SHAs instead of tags
116+
- Example: `actions/checkout@a1b2c3d...` instead of `actions/checkout@v4`
117+
- Prevents supply chain attacks via tag manipulation
118+
119+
**Benefits:**
120+
- Enhanced security (SLSA requirement)
121+
- Prevents tag hijacking attacks
122+
- Immutable action versions
123+
124+
**Example change:**
125+
```yaml
126+
# Before (tag-based)
127+
- uses: actions/checkout@v4
128+
129+
# After (SHA-pinned)
130+
- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
131+
```
132+
133+
**How to implement:**
134+
- Use tools like `pin-github-action` or Dependabot
135+
- Add comments with version tags for readability
136+
- Update SHAs when updating action versions
137+
138+
**Note:** This may not be available on all GitHub plans. If unavailable, consider using Dependabot to monitor action versions.
139+
140+
### Verification Checklist
141+
142+
After configuring repository settings, verify:
143+
144+
- [ ] "Update branch" button appears on PRs when behind base
145+
- [ ] "Enable auto-merge" button appears on PRs
146+
- [ ] Merged PRs automatically delete their branches
147+
- [ ] auto-pr.yml workflow can create PRs from claude/** branches
148+
- [ ] release-please.yml workflow can create release PRs
149+
- [ ] GitHub Actions are pinned to commit SHAs (if enabled)
150+
151+
---
152+
15153
## Why Branch Protection?
16154

17155
Branch protection prevents:

0 commit comments

Comments
 (0)