Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
3 changes: 3 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,6 @@ contact_links:
- name: Roadmap and status
url: https://github.com/cloudhal-dev/podbay/blob/main/docs/roadmap.md
about: What is planned and what is knowingly left open. Read these before asking for a feature.
- name: Ask a question
url: https://github.com/cloudhal-dev/podbay/discussions
about: Questions about running or building Podbay. An issue is for a defect or a planned piece of work.
17 changes: 16 additions & 1 deletion .github/rulesets/main.json
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,13 @@
"parameters": {
"allowed_merge_methods": ["merge"],
"dismiss_stale_reviews_on_push": true,
"dismissal_restriction": { "allowed_actors": [], "enabled": false },
"require_code_owner_review": true,
"require_extra_approval_for_unattributed_changes": true,
"require_last_push_approval": false,
"required_approving_review_count": 0,
"required_review_thread_resolution": true
"required_review_thread_resolution": true,
"required_reviewers": []
}
},
{
Expand All @@ -31,6 +34,18 @@
{ "context": "pnpm e2e (browser)", "integration_id": 15368 }
]
}
},
{
"type": "code_scanning",
"parameters": {
"code_scanning_tools": [
{
"tool": "CodeQL",
"security_alerts_threshold": "high_or_higher",
"alerts_threshold": "errors"
}
]
}
}
]
}
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ None of them needs an account or a secret. Which tier proves what is in the [`po
- [Sign-in and access](docs/auth-and-access.md): accounts, roles, mailbox memberships, credentials for programs.
- [Engineering rules](docs/engineering-rules.md): the version policy, the security rules and the developer rules, each with its automated check.
- [Decisions](docs/adr/README.md): one record for each decision that changes a contract, a stored format or the direction.
- [The repository and its settings](docs/repository.md): which protections are in force and what is done on the day it becomes public.
- [The repository and its settings](docs/repository.md): which protections are in force since the repository opened, and what is still open.
- [Cloudflare facts](docs/cloudflare/README.md): what the code relies on about the platform, each with its source and the date it was read.

## Contributing
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# ADR-0017: The repository opens before the name is reviewed

- Status: **Accepted**
- Date: 2026-11-18
- Decided by: Halil (@madraka), project lead
- Amends: [ADR-0001](0001-founding-decisions.md), decision 8, and the third consequence of [ADR-0003](0003-project-home-on-cloudhal-dev.md). Neither file is changed; this record is where the change is.

## Context

ADR-0001 (decision 8) made the repository public only after the name "Podbay" had passed a domain and trademark check, and ADR-0003 repeated it: the review "still happens before the repository becomes public". The review ([issue #4](https://github.com/cloudhal-dev/podbay/issues/4)) is not done.

Keeping the repository private had a cost. The organisation is on GitHub's free plan, and on that plan the protections the project depends on exist only for a public repository. On 2026-11-18 GitHub refused four of them for this repository, each with an answer: the rulesets for `main` and for release tags, and classic branch protection ("Upgrade to GitHub Pro or make this repository public"); secret scanning with push protection ("not available for this repository"); private vulnerability reporting (not found); and the approval for workflows from forks ("not allowed for private repositories"). Code scanning was not asked for while the repository was private; it was left for the day it opened. While it was private, `main` was guarded by review alone (rule S16 in the [status](../status.md), section 2).

## Decision

1. **The repository is public from 2026-11-18**, before the name review is done.
2. **The name review is done before version 0.1 is released.** No release, tag or package is published under the name until the review is closed with its outcome written on issue #4.
3. **If the review fails, the project is renamed** by a new decision, before any release.

## What is not decided here

- The outcome of the review, or a new name.
- Where the project is published or announced. Nothing is published yet, and the project's home is still the one in ADR-0003.

## Consequences

- The protections GitHub offers a public repository are on from the day it opened, and [repository](../repository.md) records them with the date they were checked.
- Anything pushed, and every issue, pull request and comment, is public from that day. The rules that already held for that are unchanged: no other mail product is named, and no real mail, address or token goes into the repository or its tracker.
- The name is used in public before it is cleared. If it has to change, the repository, the package name, the project's home and the documents change with it, and links to the old name may break. That cost is accepted, and it is smallest before a release.
- The release gate gains one condition. Issue #4 is closed before version 0.1, alongside the full security audit ([security records](../security/README.md)).

## Triggers

Look at this again if:
- the review finds a conflict;
- a release is planned before the review is closed;
- someone outside the project raises the name.
1 change: 1 addition & 0 deletions docs/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,3 +20,4 @@ Decisions are immutable once accepted. A later ADR supersedes an earlier one; th
| [0014](0014-acting-on-many-conversations.md) | One request acts on many conversations, and a list has an order a person chooses | Accepted, 2026-11-17 |
| [0015](0015-the-original-message-is-kept.md) | The original message is kept | Accepted, 2026-11-17 |
| [0016](0016-outgoing-mail-waits-before-it-leaves.md) | Outgoing mail waits before it leaves | Accepted, 2026-11-17 |
| [0017](0017-the-repository-opens-before-the-name-is-reviewed.md) | The repository opens before the name is reviewed (amends 0001, decision 8, and 0003) | Accepted, 2026-11-18 |
60 changes: 28 additions & 32 deletions docs/repository.md
Original file line number Diff line number Diff line change
@@ -1,60 +1,56 @@
# Podbay: the repository and its settings

- Companion to [`GOVERNANCE.md`](../GOVERNANCE.md), [`CONTRIBUTING.md`](../CONTRIBUTING.md) and the [status](status.md).
- Question answered here: where the repository lives, which settings guard it, which are in force today, and what is done on the day it becomes public.
- Question answered here: where the repository lives, which settings guard it and which are in force today.

The repository is `github.com/cloudhal-dev/podbay`. Settings live on GitHub, not in the tree, so this page is their record: change the setting and this page in the same sitting. Last checked against GitHub: 2026-11-18.
The repository is `github.com/cloudhal-dev/podbay`. Settings live on GitHub, not in the tree, so this page is their record: change the setting and this page in the same sitting. Last checked against GitHub's API: 2026-11-18.

## 1. Private until the name is reviewed
## 1. Public since 2026-11-18

The repository is **private**. [ADR-0001](adr/0001-founding-decisions.md) (decision 8) and [ADR-0003](adr/0003-project-home-on-cloudhal-dev.md) hold the public launch until the name "Podbay" has had a trademark review. Opening the repository is the project lead's step and nobody else's.
The repository is **public**. It opened before the name "Podbay" had its trademark review: [ADR-0017](adr/0017-the-repository-opens-before-the-name-is-reviewed.md) amends ADR-0001 (decision 8) and ADR-0003 so that the review ([issue #4](https://github.com/cloudhal-dev/podbay/issues/4)) is done before version 0.1 is released. If the review fails, the project is renamed by a new decision before any release.

The organisation is on GitHub's free plan. On that plan several protections exist only for public repositories. Each one in section 3 was asked for on 2026-11-18 and refused by GitHub for this repository while it is private; they are written down here and applied when it opens.
Everything pushed, every issue, pull request and comment is public. No other mail product is named, and no real mail, address or token goes into the repository or its tracker.

## 2. In force today

| Setting | Value | Why |
|---|---|---|
| Merging | Merge commits only; squash and rebase are off | A change keeps its commits and their messages |
| Ruleset `main` | `main` cannot be deleted or force-pushed. A change arrives by pull request, merged with a merge commit, with a review from an owner of the code for the paths in [`.github/CODEOWNERS`](../.github/CODEOWNERS) and every conversation resolved. Three checks must be green: `pnpm check (Node 24)`, `pnpm check (Node 26)` and `pnpm e2e (browser)`. Code scanning must find no new security alert of level high or above and no new error. A repository administrator may merge their own pull request without the review; nobody can push past the pull request | Rule S16; [`.github/rulesets/main.json`](../.github/rulesets/main.json) |
| Ruleset `release tags` | A tag cannot be moved or deleted, by anyone | [`.github/rulesets/release-tags.json`](../.github/rulesets/release-tags.json) |
| Merging | Merge commits only; squash and rebase are off. Auto-merge is on: a pull request merges by itself once its requirements are met | A change keeps its commits and their messages |
| Branches | Deleted when their pull request merges; "Update branch" offered | |
| Sign-off | Required for commits made on the web | Every commit carries `Signed-off-by` ([`CONTRIBUTING.md`](../CONTRIBUTING.md)) |
| Wiki and projects | Off | Documents live in `docs/`, where the checks read them |
| Secret scanning | On, with push protection: a push that carries a known kind of credential is refused | Rule S6 |
| Private vulnerability reporting | On: the form [`SECURITY.md`](../SECURITY.md) links to | |
| Code scanning | Default setup, query suite `extended`, for the workflows and for JavaScript and TypeScript, on `main` and on every pull request | Rule S16 |
| Workflows from forks | Wait for a maintainer's approval for every outside contributor (`all_external_contributors`), not only the first time | Rule S16 |
| Actions that may run | GitHub's own and `pnpm/action-setup`, each pinned by full commit id; GitHub refuses a workflow that is not | Rule S16 |
| The workflow token | Read-only by default; workflows cannot approve pull requests | Rule S16 |
| Runners | GitHub's hosted standard runners only. The repository has no self-hosted runner and must never get one while it is public: a pull request from anyone could run code on it | Rule S16 |
| Artifacts and logs | Kept 90 days, the most GitHub allows | |
| Releases | Immutable releases are on. The environment `release` needs a review from the project lead and deploys only from tags `v*`; nothing uses it yet: it is for the release workflow ([issue #21](https://github.com/cloudhal-dev/podbay/issues/21)) | Rule S16 |
| Dependabot | Alerts and security updates on; weekly version updates by [`.github/dependabot.yml`](../.github/dependabot.yml) | Rules V2 and S15 |
| Issues | On, through two forms; blank issues are off, and a vulnerability is sent to the private report | [`SECURITY.md`](../SECURITY.md) |
| Issues and discussions | Issues through two forms; blank issues are off, and a vulnerability is sent to the private report. Questions go to [Discussions](https://github.com/cloudhal-dev/podbay/discussions) | [`SECURITY.md`](../SECURITY.md) |
| Wiki and projects | Off | Documents live in `docs/`, where the checks read them |

The checks of [`.github/workflows/checks.yml`](../.github/workflows/checks.yml) run on every pull request and every push to `main`: `pnpm check` and `pnpm test:workerd` on two versions of Node, and `pnpm e2e`. They use no secret and no account.
The checks of [`.github/workflows/checks.yml`](../.github/workflows/checks.yml) run on every pull request and every push to `main`: `pnpm check` and `pnpm test:workerd` on two versions of Node, and `pnpm e2e`. They use no secret and no account. On 2026-11-18 the Actions cache of the repository held about 1.1 GB.

## 3. Applied when the repository is public
## 3. Asked for and not given

| Protection | What it does | Where it is written |
|---|---|---|
| Ruleset `main` | `main` cannot be deleted or force-pushed. A change arrives by pull request, with a review from an owner of the code for the paths in [`.github/CODEOWNERS`](../.github/CODEOWNERS), every conversation resolved, and the three checks green. A repository administrator may merge their own pull request without the review, never push past one | [`.github/rulesets/main.json`](../.github/rulesets/main.json) |
| Ruleset `release tags` | A tag cannot be moved or deleted, by anyone | [`.github/rulesets/release-tags.json`](../.github/rulesets/release-tags.json) |
| Secret scanning with push protection | A push that carries a known kind of credential is refused | A repository setting |
| Private vulnerability reporting | The form `SECURITY.md` links to | A repository setting |
| Code scanning | Static analysis of `main` and of every pull request | A repository setting (default setup) |
| Approval for workflows from forks | A first pull request from outside does not run a workflow until a maintainer allows it | A repository setting |
| Auto-merge | A pull request merges by itself once its requirements are met | A repository setting |
Asked for on 2026-11-18 and still off afterwards, because GitHub does not give them to this repository:

## 4. The day it opens
- secret scanning for patterns that belong to no provider (generic passwords and keys);
- validity checks of the credentials secret scanning finds.

In order, by the project lead or with their word:
## 4. How it opened, and what is still open

1. The name review is closed, with its outcome written on its issue.
2. Read the tracked files and the history once more: `pnpm static secrets`, `pnpm static names`, and `git log --format='%ae %ce' | sort -u` shows no private address.
3. Make the repository public.
4. Create the two rulesets from their files:
On 2026-11-18 the repository was made public. The two rulesets were created from their files, and the settings of section 2 were turned on. Right after the visibility changed, GitHub refused the rulesets for some seconds ("Repository has been locked") and took them on the second try. The first code scanning run found twenty alerts, none of them a vulnerability: eleven in tests and tooling were dismissed with their reason on the alert, and nine are corrected by [pull request #60](https://github.com/cloudhal-dev/podbay/pull/60).

```bash
gh api -X POST repos/cloudhal-dev/podbay/rulesets --input .github/rulesets/main.json
gh api -X POST repos/cloudhal-dev/podbay/rulesets --input .github/rulesets/release-tags.json
```
Still open:

5. Turn on secret scanning with push protection, private vulnerability reporting, code scanning, the approval for workflows from forks, and auto-merge.
6. Open `SECURITY.md`'s report link while signed out of the organisation and see the form.
7. Change sections 1 to 3 of this page to what is now true, with the date, in a pull request: the first one the ruleset checks.
- **Two-factor sign-in is not required by the organisation.** It is the project lead's setting, for the whole organisation.
- **The name review** ([issue #4](https://github.com/cloudhal-dev/podbay/issues/4)), before version 0.1 ([ADR-0017](adr/0017-the-repository-opens-before-the-name-is-reviewed.md)).
- **The files of the rulesets are a record, not the source.** Nothing compares them with what GitHub holds; they are compared by hand against `gh api repos/cloudhal-dev/podbay/rulesets/<id>` when either changes.

## 5. Labels and milestones

Expand Down
3 changes: 2 additions & 1 deletion docs/status.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@
| The auth tables equal what Better Auth generates | D3 (part) | `node scripts/auth-ddl.ts --check` (in `pnpm static`) |
| Envelope routing, file names, feature switches, sender check, list options | S2, S3, S8, D2, D7 | `test/unit/`, `test/workerd/` |
| Actions pinned by commit, read-only token | S16 | `.github/workflows/checks.yml` (by review until the workflow lint lands) |
| `main` changes only by pull request with the three checks green and no new code scanning alert of level high; tags cannot move; secret scanning with push protection, private vulnerability reporting and code scanning are on; workflows from forks wait for approval (since 2026-11-18, when the repository opened) | S16, S6 | GitHub's rulesets and settings, recorded in [repository](repository.md) and `.github/rulesets/`; compared by hand, no check reads them yet |
| The app's words are messages, in English and Turkish: every message the code names has a Turkish translation with the same values, the catalog holds nothing the code dropped, and no words stand bare in the markup of a screen; a person chooses the language in the settings or takes the device's, it takes effect at once, is kept with the person's account ([ADR-0012](adr/0012-a-persons-choices-and-known-addresses.md)) and in the browser's copy for the first paint, and dates follow it | D8 | `pnpm static messages`, `test/unit/messages.test.ts`; `pnpm e2e`: `language.spec.ts` |
| The formatting bar sizes, colours, highlights, aligns and indents what is written and takes it off again; what goes into a message is literal markup with nothing of the app's theme, a choice from one of its menus leaves the cursor in the text, and its menus open above the compose window | D9 | `pnpm e2e`: `writing.spec.ts` (the formatting bar) |
| A mailbox sends at most 20 messages in an hour and 100 in a day, counted in time: until 2026-11-17 the hour was compared as text against dates written another way, so it counted the whole day and a mailbox could send twenty messages a day. Since ADR-0016 the caps count what left, in a record of the mailbox's own (`send_log`), and no longer the rows of Sent | S8 | `test/workerd/sending-limit.test.ts`, `test/workerd/leaving.test.ts` |
Expand Down Expand Up @@ -94,7 +95,7 @@ These rules are accepted but their checks land with the code they guard. Until t
| S8 (the cap for the whole instance; the one send path is enforced since ADR-0016), S12 (constrained outbound requests); keys for the HTTP API and management keys; OAuth 2.1 with a consent screen for MCP clients ([ADR-0004](adr/0004-mcp-keys-first.md)) | Milestone 3 |
| S18 (audit records and the release gate; the skill and the hash check exist) | Before v0.1 |
| D2, D3, D9, D10, D13 (schemas at every entry point, migration tests, design lint, drift check, budgets) | Milestones 1 to 3 |
| S16 on the repository itself: the rulesets for `main` and for release tags, secret scanning with push protection, private vulnerability reporting, code scanning. GitHub offers them to this organisation only for a public repository, and the repository is private until the name is reviewed ([ADR-0001](adr/0001-founding-decisions.md), decision 8) | The day the repository is public ([repository](repository.md)) |
| S16, the rest: the workflow lint, the repository's settings compared with their record by a check, and the release workflow | Milestone 3 and the release ([issue #56](https://github.com/cloudhal-dev/podbay/issues/56), [issue #21](https://github.com/cloudhal-dev/podbay/issues/21)) |

## 3. Known debt and known gaps

Expand Down
Loading