## Summary System hooks are instance-wide webhooks. An instance admin sets them up at `/admin/hooks`, and they fire for events anywhere on the instance, like project created, user added to a group, push or merge request. For Cells, each organization needs its own system hooks. The database and model already know about organizations. Delivery, the REST API, hook logs and the org admin UI don't yet. A few things to know first: - Nobody tracks this yet. &22859 says system hooks are "tracked separately", but there's no issue or epic for them. - System hooks are hidden on GitLab.com on purpose (gitlab#460989, 17.2), because one hook could get data from every project. Giving org owners system hooks on GitLab.com is a product and security call, not just code. - The scoping fixes are safe to do now. Nothing changes on a single-org instance, and they close a cross-org leak on any cell with more than one. Proposal: open a new epic next to &22859. Start the database and backend scoping work now, and hold the permission and UI work until the product decision lands. ## Already done - `web_hooks.organization_id` column, index and check constraint (gitlab#524812) - `SystemHook` belongs to an organization, and create sets it in the UI and API (gitlab!206728) - `/admin/hooks` only shows the current org's hooks (gitlab!237441) - Webhook workers carry the org in their job context (gitlab!236598) - Hook logs get the org through a database trigger (gitlab#524820) - The org admin area exists at `/o/:organization_path/admin` (gitlab#587370) - No data migration needed, GitLab.com has zero system hooks today - Delivery, `Project#has_active_hooks?`, the REST API, the admin hook logs and test payloads, and `SystemHookPushWorker` are scoped or removed (gitlab#632589, #632590, #632591, #632592, #632595) ## What's broken - The instance admin area falls back to the first org. Decided to stay for now, see Decisions below. - No hooks pages, menu item or permissions for org owners. - Local network requests are allowed by default, and there's no rate limit or auto-disable. Fine for admins, risky for org owners. - User and key events are not yet filtered by whether the organization owns the user. - Audit events land on the user, not the org. - The org foreign key on `web_hooks` is still `NOT VALID`. - Data isolation skips `web_hooks` (it has 3 sharding keys), so every scope must be explicit and tested. ## Decisions Answered: - **Product:** organization admins get hooks in the org admin area ([Drew Blessing](https://gitlab.com/groups/gitlab-org/-/work_items/23936#note_4012739503)). SSH public keys are fine to share. Emails are not, for users the organization does not own. - **Events:** one hook type for every deployment, no split between isolated and non-isolated organizations. Events about a user are delivered to an organization's hooks only if the organization owns the user: `user_create`, `user_destroy`, `user_rename`, `user_failed_login`, `key_create` and `key_destroy` are held back otherwise, or sent without the email. This was agreed in Slack between Drew Blessing and Jennifer Black and replaces Jennifer's earlier proposal in the thread on this epic. Tracked in gitlab#632599. - **Multi-org self-managed:** behaves the same as GitLab.com. Hooks are per organization, and default org hooks do not fire for other orgs (Drew Blessing). - **Instance admin area fallback:** `Organization.first` stays for now. The instance admin area should not have a current organization at all, which is resolved under gitlab-org#19424 before migrating to a cell. Pages that depend on one move to the org admin area. Still open: - **Security:** local requests, rate limits and auto-disable for org owner hooks. (AppSec, gitlab#632599) - **Naming:** Drew Blessing leans toward "Organization hooks" as its own named feature, with some or all system hooks becoming organization hooks. Needs a final call before UI copy and docs are written (gitlab#632598, gitlab#632602). Note gitlab#589210 is the general org admin area design and does not cover hooks. - **Permission names:** legacy `read_web_hook` and `admin_web_hook`, or the granular `*_webhook` names (gitlab#632597). - **Home:** new epic or part of &22859? (Thiago Figueiro) ## Things to watch - Shares files with &22859 (org admin routes, settings menu, role YAMLs, release config). gitlab#631291 and gitlab#631295 are closed, so rebase on their changes. - No automatic data isolation, so cross-org specs are our safety net. - Organizations have no plan limits, so rate limits need a design. - Granular tokens don't have an org boundary yet. - The product term is now "Org Admin", not "Owner". The role in code is still `organization_owner`. ## Out of scope - `/organizations/:id/hooks` REST endpoints - Project and group webhooks (already scoped) - File hooks - Renaming `SystemHook` to `OrganizationHook` - Adding `organization_id` to hook payloads ## Links - Integrations epic: &22859 - Org admin area epic: &19424 - System hooks sharding epic: &17008 - Spike: gitlab#598315 - Ownership: gitlab#599597 - [Cells Admin Area design doc](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/cells/impacted_features/admin-area/) - Docs: [System hooks](https://docs.gitlab.com/administration/system_hooks/), [API](https://docs.gitlab.com/api/system_hooks/)