Skip to content

Commit 645e907

Browse files
Copilothuangyiirene
Copilot
and
huangyiirene
committed
Add documentation and instructions for fixing release workflow permissions
Co-authored-by: huangyiirene <7665279+huangyiirene@users.noreply.github.com>
1 parent c692c2a commit 645e907

File tree

4 files changed

+194
-0
lines changed

4 files changed

+194
-0
lines changed

‎.github/RELEASE_SETUP.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# Release Workflow Setup Guide
2+
3+
This guide explains how to configure the repository and organization settings required for the automated release workflow to function correctly.
4+
5+
## Problem
6+
7+
If you encounter the following error in the Release workflow:
8+
9+
```
10+
GitHub Actions is not permitted to create or approve pull requests
11+
```
12+
13+
This means the required repository setting is not enabled.
14+
15+
## Solution
16+
17+
GitHub has a security setting that controls whether GitHub Actions workflows can create pull requests. This setting must be enabled for the `changesets/action` to create release PRs automatically.
18+
19+
### For Organization Repositories
20+
21+
If your repository belongs to an organization (like `objectstack-ai/objectql`), you must enable the setting at **both** the organization and repository levels:
22+
23+
#### Step 1: Enable at Organization Level
24+
25+
1. Navigate to your organization settings:
26+
```
27+
https://github.com/organizations/YOUR_ORG/settings/actions
28+
```
29+
Replace `YOUR_ORG` with your organization name (e.g., `objectstack-ai`)
30+
31+
2. Under **Actions > General > Workflow permissions**:
32+
- Scroll down to find the section "Workflow permissions"
33+
- Check the box: **☑ Allow GitHub Actions to create and approve pull requests**
34+
- Click **Save**
35+
36+
> **Note:** You must be an organization owner to change these settings.
37+
38+
#### Step 2: Enable at Repository Level
39+
40+
After enabling at the organization level, enable it for the specific repository:
41+
42+
1. Navigate to your repository settings:
43+
```
44+
https://github.com/YOUR_ORG/YOUR_REPO/settings/actions
45+
```
46+
For this repo: `https://github.com/objectstack-ai/objectql/settings/actions`
47+
48+
2. Under **Actions > General > Workflow permissions**:
49+
- Check the box: **☑ Allow GitHub Actions to create and approve pull requests**
50+
- Click **Save**
51+
52+
> **Note:** This option may be grayed out until you enable it at the organization level first.
53+
54+
### For Personal Repositories
55+
56+
If your repository is under a personal account (not an organization):
57+
58+
1. Navigate to your repository settings:
59+
```
60+
https://github.com/USERNAME/REPO/settings/actions
61+
```
62+
63+
2. Under **Actions > General > Workflow permissions**:
64+
- Check the box: **☑ Allow GitHub Actions to create and approve pull requests**
65+
- Click **Save**
66+
67+
## How the Release Workflow Works
68+
69+
Once the settings are enabled:
70+
71+
1. **On merge to `main`**: The workflow runs automatically
72+
2. **Changesets detected**: If there are `.changeset/*.md` files, the action:
73+
- Creates/updates a PR titled "Version Packages"
74+
- Updates CHANGELOG.md files
75+
- Bumps package.json versions
76+
3. **Manual merge**: When you merge the "Version Packages" PR:
77+
- The workflow publishes packages to npm
78+
- Creates GitHub releases with tags
79+
80+
## Troubleshooting
81+
82+
### Error: "GitHub Actions is not permitted to create or approve pull requests"
83+
84+
**Cause**: The repository/organization setting is not enabled.
85+
86+
**Solution**: Follow the steps above to enable the setting.
87+
88+
### Error: "Resource not accessible by integration"
89+
90+
**Cause**: The workflow doesn't have sufficient permissions.
91+
92+
**Solution**: The workflow already has the correct permissions defined:
93+
```yaml
94+
permissions:
95+
contents: write
96+
issues: write
97+
pull-requests: write
98+
```
99+
100+
If you still see this error, check that you haven't restricted the `GITHUB_TOKEN` permissions in your repository settings.
101+
102+
### The workflow runs but doesn't create a PR
103+
104+
**Cause**: There are no changesets to process.
105+
106+
**Solution**: Contributors should add changesets for their changes:
107+
```bash
108+
pnpm changeset
109+
```
110+
111+
This creates a markdown file in `.changeset/` describing the change and version bump type.
112+
113+
## Security Considerations
114+
115+
Enabling "Allow GitHub Actions to create and approve pull requests" is safe when:
116+
117+
- ✅ Your workflow files (`.github/workflows/`) are protected by branch protection rules
118+
- ✅ You review workflow changes in PRs before merging
119+
- ✅ You trust the actions used in your workflows (we use official actions from `changesets`, `actions`, and `pnpm`)
120+
121+
The default `GITHUB_TOKEN` has limited scope and cannot:
122+
- Push to protected branches without passing checks
123+
- Bypass branch protection rules
124+
- Access organization secrets beyond those explicitly granted
125+
126+
## Additional Resources
127+
128+
- [GitHub Docs: Managing GitHub Actions settings](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository)
129+
- [Changesets Documentation](https://github.com/changesets/changesets)
130+
- [GitHub Blog: Prevent Actions from creating PRs](https://github.blog/changelog/2022-05-03-github-actions-prevent-github-actions-from-creating-and-approving-pull-requests/)
131+
132+
## Quick Reference
133+
134+
| Level | URL Template | Required For |
135+
|-------|-------------|--------------|
136+
| **Organization** | `https://github.com/organizations/{ORG}/settings/actions` | Organization repos (enable first) |
137+
| **Repository** | `https://github.com/{ORG}/{REPO}/settings/actions` | All repos (enable after org) |
138+
| **Personal** | `https://github.com/{USER}/{REPO}/settings/actions` | Personal repos only |
139+
140+
---
141+
142+
**Last Updated**: January 2026
143+
**Maintainer**: ObjectStack AI Team

‎.github/WORKFLOWS.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,12 @@ This document describes all the GitHub Actions workflows configured for the Obje
4242
- Publishes packages to npm when merged
4343
- Requires NPM_TOKEN secret
4444

45+
**⚠️ Setup Required:** This workflow requires enabling a GitHub setting. See [RELEASE_SETUP.md](RELEASE_SETUP.md) for detailed setup instructions.
46+
47+
**Common Issues:**
48+
- Error: "GitHub Actions is not permitted to create or approve pull requests"
49+
- **Solution:** Enable the setting at organization/repository level (see setup guide)
50+
4551
### 📝 [changelog-preview.yml](workflows/changelog-preview.yml) ✨ NEW
4652
**Purpose:** Preview changelog before release
4753
**Triggers:** Pull Requests
@@ -182,6 +188,19 @@ The following secrets need to be configured in repository settings:
182188
- `NPM_TOKEN` - For publishing packages to npm (required by release.yml)
183189
- `CODECOV_TOKEN` - For uploading coverage reports (optional for coverage.yml)
184190

191+
## Required Repository Settings
192+
193+
### Release Workflow
194+
195+
For the release workflow to create pull requests automatically, you must enable:
196+
197+
**Repository Settings > Actions > General > Workflow permissions**
198+
- ☑ Allow GitHub Actions to create and approve pull requests
199+
200+
For organization repositories, this must also be enabled at the organization level first.
201+
202+
**📖 See [RELEASE_SETUP.md](RELEASE_SETUP.md) for complete setup instructions and troubleshooting.**
203+
185204
---
186205

187206
## Workflow Status Badges

‎.github/workflows/release.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,16 @@ on:
77

88
concurrency: ${{ github.workflow }}-${{ github.ref }}
99

10+
# IMPORTANT: For this workflow to work, you must enable the following setting:
11+
# Repository Settings > Actions > General > Workflow permissions
12+
# ☑ Allow GitHub Actions to create and approve pull requests
13+
#
14+
# For organizations: This must be enabled at the organization level first:
15+
# Organization Settings > Actions > General > Workflow permissions
16+
# ☑ Allow GitHub Actions to create and approve pull requests
17+
#
18+
# See: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#preventing-github-actions-from-creating-or-approving-pull-requests
19+
1020
permissions:
1121
contents: write
1222
issues: write

‎README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -295,6 +295,28 @@ If you fork or clone the repository to contribute or run examples from source:
295295
# Output: Plugin initialization, Employee creation logs, Audit trails
296296
```
297297

298+
### For Repository Maintainers
299+
300+
#### Release Process Setup
301+
302+
The repository uses automated releases via Changesets. To enable the release workflow:
303+
304+
1. Configure required GitHub settings (organization owners only):
305+
- See [.github/RELEASE_SETUP.md](.github/RELEASE_SETUP.md) for detailed instructions
306+
307+
2. Add required secrets:
308+
- `NPM_TOKEN`: Token for publishing to npm
309+
310+
#### Adding Changes
311+
312+
When making changes, add a changeset describing the change:
313+
314+
```bash
315+
pnpm changeset
316+
```
317+
318+
This creates a file in `.changeset/` that will be used to generate changelogs and version bumps.
319+
298320
---
299321

300322
## ⚖️ License

0 commit comments

Comments
 (0)