Skip to content

docs: add CONTRIBUTING.md note on dev-signing permission resets #276

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MufeezQadri wants to merge 1 commit into
base: main
Choose a base branch
from
+23 −0
Open

docs: add CONTRIBUTING.md note on dev-signing permission resets #276

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Contributing to FreeFlow

## Building and running locally

```bash
make run
```

This compiles the app and code-signs it with the identity named in `CODESIGN_IDENTITY` (`FreeFlow Dev` by default).

### Accessibility (or Microphone/Screen Recording) permission keeps disappearing after every rebuild

If you build from source without a matching signing identity in your keychain, `make` falls back to an ad-hoc signature. Ad-hoc signatures have no stable subject, so macOS treats every rebuild as a new, different app — any Accessibility/Microphone/Screen Recording grant you gave the previous build silently stops applying, even though System Settings may still show an old, now-stale entry.

@coderabbitai coderabbitai Bot Jul 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -eu
rg -n 'CODESIGN_IDENTITY|codesign|--sign' Makefile

Repository: zachlatta/freeflow

Length of output: 481

🏁 Script executed:

#!/bin/bash
set -eu
cat -n CONTRIBUTING.md | sed -n '1,40p'
echo
rg -n 'ad-hoc|CODESIGN_IDENTITY\s*=\s*-|fallback.*ad-hoc|codesign.*sign' .

Repository: zachlatta/freeflow

Length of output: 3014

Clarify the signing behavior here. Makefile passes CODESIGN_IDENTITY straight to codesign; it does not automatically switch to ad-hoc signing when the identity is missing. If ad-hoc is intended, document the explicit CODESIGN_IDENTITY=- path or add that fallback in Makefile.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@CONTRIBUTING.md` at line 13, Update the signing guidance in CONTRIBUTING.md
to accurately state that Makefile passes CODESIGN_IDENTITY directly to codesign
and does not automatically fall back to ad-hoc signing. Document the explicit
CODESIGN_IDENTITY=- invocation if ad-hoc signing is intended, or implement the
missing fallback in the Makefile.

Source: MCP tools


**Fix: create a local self-signed code-signing certificate named `FreeFlow Dev`** so every rebuild shares the same signing identity, and macOS remembers your permission grants across rebuilds:

1. Open **Keychain Access** → menu bar **Keychain Access → Certificate Assistant → Create a Certificate…**
2. Name: `FreeFlow Dev`. Identity Type: **Self Signed Root**. Certificate Type: **Code Signing**.
3. Leave the rest at their defaults and click **Create**.
4. Run `make clean && make` — the build log should now say `build/FreeFlow Dev.app: replacing existing signature` and `codesign -dv "build/FreeFlow Dev.app"` should show `Authority=FreeFlow Dev` instead of an `adhoc` flag.
5. Launch the app and grant Accessibility/Microphone/Screen Recording once more. Future rebuilds will keep this same identity, so you should not need to re-grant them again.

If you ever see a stale, disabled entry for FreeFlow (or FreeFlow Dev) in System Settings → Privacy & Security, remove it with the **−** button rather than just toggling it — a leftover ad-hoc entry can conflict with the newly-signed build.