141 lines
3.8 KiB
Markdown
141 lines
3.8 KiB
Markdown
# Contributing to Jarvis
|
|
|
|
## Branch workflow
|
|
|
|
```
|
|
feature/* ──→ develop ──→ main
|
|
```
|
|
|
|
- **`main`** — protected. No direct pushes. Every change arrives via PR from `develop`.
|
|
- **`develop`** — integration branch. All feature work merges here first. CI runs on every push.
|
|
- **`feature/*`** — short-lived branches cut from `develop`.
|
|
|
|
## Starting work
|
|
|
|
```bash
|
|
git checkout develop
|
|
git pull origin develop
|
|
git checkout -b feature/your-description
|
|
```
|
|
|
|
## Opening a PR
|
|
|
|
1. Push your feature branch and open a PR targeting **`develop`**.
|
|
2. CI must pass (Debug + Release builds succeed).
|
|
3. At least 1 approval required before merge.
|
|
|
|
## Releasing to TestFlight
|
|
|
|
A maintainer opens a PR from `develop → main`. Merging triggers the release workflow:
|
|
archive → export IPA → upload to TestFlight.
|
|
|
|
---
|
|
|
|
## Runner setup (one-time, on your Mac)
|
|
|
|
Gitea Actions requires a self-hosted runner. The CI workflows target `[self-hosted, macos]`.
|
|
|
|
### 1. Enable Gitea Actions (admin, once per instance)
|
|
|
|
In `app.ini` on the Gitea server, add:
|
|
|
|
```ini
|
|
[actions]
|
|
ENABLED = true
|
|
```
|
|
|
|
Then restart Gitea.
|
|
|
|
### 2. Install act_runner on the Mac
|
|
|
|
There is no Homebrew formula — download the official binary:
|
|
|
|
```bash
|
|
curl -sL -o /usr/local/bin/act_runner \
|
|
https://dl.gitea.com/act_runner/0.6.1/act_runner-0.6.1-darwin-arm64
|
|
chmod +x /usr/local/bin/act_runner
|
|
```
|
|
|
|
### 3. Register the runner
|
|
|
|
Get a registration token from:
|
|
**Repository Settings → Actions → Runners → Create Runner**
|
|
(or via API: `GET /api/v1/repos/kutesir/jarvis/actions/runners/registration-token`)
|
|
|
|
The `:host` label suffix is required — it makes jobs run directly on the Mac
|
|
instead of in Docker (which xcodebuild needs, and the Mac has no Docker):
|
|
|
|
```bash
|
|
mkdir -p ~/.act_runner && cd ~/.act_runner
|
|
act_runner register --no-interactive \
|
|
--instance http://10.10.1.21:3002 \
|
|
--token <RUNNER_TOKEN> \
|
|
--name "mac-mini" \
|
|
--labels "self-hosted:host,macos:host"
|
|
```
|
|
|
|
### 4. Configure and start the runner
|
|
|
|
Generate the config, then fix two defaults that break Docker-less Macs
|
|
(the generated config ships Docker-based ubuntu labels that make the daemon
|
|
refuse to start without a Docker socket):
|
|
|
|
```bash
|
|
cd ~/.act_runner
|
|
act_runner generate-config > config.yaml
|
|
# 1. labels: [] — empty falls back to the :host labels in .runner
|
|
# 2. docker_host: "-" — never look for a Docker daemon
|
|
```
|
|
|
|
In `config.yaml`, set:
|
|
- `labels: []` (replace the default ubuntu docker labels)
|
|
- `docker_host: "-"` (under `container:`)
|
|
|
|
Then start it:
|
|
|
|
```bash
|
|
act_runner daemon --config ~/.act_runner/config.yaml
|
|
```
|
|
|
|
To keep it running across reboots, load it as a LaunchAgent
|
|
(`~/Library/LaunchAgents/com.gitea.act-runner.plist`, see repo scripts).
|
|
|
|
The runner must have **Xcode 16+** installed and accepted the license:
|
|
|
|
```bash
|
|
sudo xcodebuild -license accept
|
|
```
|
|
|
|
---
|
|
|
|
## Signing and TestFlight secrets
|
|
|
|
For the release workflow to archive and upload, the runner Mac needs:
|
|
|
|
1. The **iOS Distribution certificate** installed in its keychain (set up once in Xcode → Settings → Accounts → Manage Certificates).
|
|
2. Three **Gitea secrets** set under:
|
|
**Repository Settings → Actions → Secrets**
|
|
|
|
| Secret | Where to get it |
|
|
|---|---|
|
|
| `ASC_KEY_ID` | App Store Connect → Users & Access → API Keys |
|
|
| `ASC_ISSUER_ID` | Same page, above the key list |
|
|
| `ASC_PRIVATE_KEY` | The `.p8` file downloaded when you created the key (only downloadable once) |
|
|
|
|
---
|
|
|
|
## Branch protection (manual setup in Gitea UI)
|
|
|
|
Go to **Repository Settings → Branches → Add Branch Rule**:
|
|
|
|
| Setting | Value |
|
|
|---|---|
|
|
| Branch name pattern | `main` |
|
|
| Require pull request before merging | ✅ |
|
|
| Required approvals | 1 |
|
|
| Require status checks to pass | ✅ — select `Build · Debug` and `Build · Release` |
|
|
| Block force push | ✅ |
|
|
| Block deletion | ✅ |
|
|
|
|
Repeat with `develop` but set required approvals to 0 (CI gate only).
|