Skip to content

Commit 51f7a3e

Browse files
Copilothuangyiirene
andcommitted
Add admin-focused guide for enabling release workflow
Co-authored-by: huangyiirene <7665279+huangyiirene@users.noreply.github.com>
1 parent bf3321c commit 51f7a3e

1 file changed

Lines changed: 125 additions & 0 deletions

File tree

.github/FOR_ADMINS.md

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# For Organization Admins: Enable Release Workflow
2+
3+
**To**: Organization Owners of `objectstack-ai`
4+
**Subject**: Action Required - Enable GitHub Actions PR Creation
5+
**Priority**: Medium
6+
**Estimated Time**: 2 minutes
7+
8+
---
9+
10+
## What Happened?
11+
12+
The automated release workflow is currently failing because GitHub Actions doesn't have permission to create pull requests. This is controlled by a security setting that needs to be enabled.
13+
14+
**Error Message**:
15+
```
16+
GitHub Actions is not permitted to create or approve pull requests
17+
```
18+
19+
**Failed Workflow**: https://github.com/objectstack-ai/objectql/actions/runs/21075340633/job/60615659715
20+
21+
---
22+
23+
## What Needs to Be Done?
24+
25+
You need to enable a checkbox in two places (takes ~2 minutes total):
26+
27+
### Step 1: Enable at Organization Level (You must do this first)
28+
29+
1. **Go to**: https://github.com/organizations/objectstack-ai/settings/actions
30+
31+
2. **Scroll down** to the "Workflow permissions" section
32+
33+
3. **Check the box**:
34+
```
35+
☑ Allow GitHub Actions to create and approve pull requests
36+
```
37+
38+
4. **Click** the "Save" button
39+
40+
### Step 2: Enable at Repository Level
41+
42+
1. **Go to**: https://github.com/objectstack-ai/objectql/settings/actions
43+
44+
2. **Scroll down** to the "Workflow permissions" section
45+
46+
3. **Check the box**:
47+
```
48+
☑ Allow GitHub Actions to create and approve pull requests
49+
```
50+
51+
4. **Click** the "Save" button
52+
53+
---
54+
55+
## Why Is This Safe?
56+
57+
**Protected Branches**: Our `main` branch has protection rules that prevent unauthorized merges
58+
59+
**Required Reviews**: PRs still require manual approval before merge
60+
61+
**CI Checks Required**: All tests must pass before merge is allowed
62+
63+
**Limited Scope**: The GitHub Actions token only has the permissions explicitly granted in workflow files
64+
65+
**Audit Trail**: All PR creations by GitHub Actions are logged and visible
66+
67+
**Trusted Actions**: We only use official actions from:
68+
- `changesets/action` (official changesets maintainer)
69+
- `actions/*` (official GitHub actions)
70+
- `pnpm/*` (official pnpm maintainer)
71+
72+
---
73+
74+
## What Will This Enable?
75+
76+
Once enabled, the release workflow will:
77+
78+
1. **Automatically create** a "Version Packages" PR when changesets are detected
79+
2. **Update** version numbers in package.json files
80+
3. **Generate** CHANGELOG.md entries
81+
4. **Publish** packages to npm when you manually merge the PR
82+
83+
You still maintain full control - the workflow only **creates** the PR. You **manually review and merge** it.
84+
85+
---
86+
87+
## What If I Don't Enable This?
88+
89+
- ❌ Automated releases won't work
90+
- ⚠️ Maintainers will need to manually:
91+
- Run `pnpm changeset version`
92+
- Update all CHANGELOG.md files
93+
- Update all package.json versions
94+
- Publish to npm manually
95+
- Create GitHub releases manually
96+
97+
This increases maintenance burden and risk of human error.
98+
99+
---
100+
101+
## Verification
102+
103+
After enabling both settings, you can test by:
104+
105+
1. Merging a PR with a changeset to `main`
106+
2. The workflow should automatically create a "Version Packages" PR
107+
3. Check: https://github.com/objectstack-ai/objectql/pulls
108+
109+
---
110+
111+
## Questions?
112+
113+
**Documentation**:
114+
- Quick Setup: [.github/RELEASE_CHECKLIST.md](.github/RELEASE_CHECKLIST.md)
115+
- Detailed Guide: [.github/RELEASE_SETUP.md](.github/RELEASE_SETUP.md)
116+
117+
**GitHub Official Docs**:
118+
- https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository
119+
120+
**Security Info**:
121+
- https://github.blog/changelog/2022-05-03-github-actions-prevent-github-actions-from-creating-and-approving-pull-requests/
122+
123+
---
124+
125+
**Thank you for maintaining ObjectQL! 🚀**

0 commit comments

Comments
 (0)