# Crow HR documentation > Install, set up and run Crow HR, the free, MIT-licensed, self-hosted HR and payroll platform for Singapore SMEs. Source: https://hr.crow.sg/docs/ :::caution[Version 1.1: check every result] Check every payroll result before you pay or file it, and read [what is built](https://hr.crow.sg/docs/status/) and the [limitations](https://hr.crow.sg/docs/payroll/limitations/). Nothing here is legal or tax advice. ::: ## What it does People records, leave, attendance and overtime, expense claims, shift rosters, documents and HR letters, approvals and reports. Monthly payroll with CPF (OW and AW ceilings, SPR graduated rates), SHG funds, SDL and an FWL estimate, itemised payslips, and the CPF EZPay file, a bank file and an IR8A export that you upload yourself. Each CPF figure shows its working, the rate table it used and a link to CPF's source. Staff sign in with email and password and two-step verification, Google Workspace, Microsoft Entra ID, any OpenID Connect provider, or Singpass once your company has onboarded with Singpass. ## Install You need Docker with the Compose plugin. Get the files, set `PUBLIC_URL` in `.env`, and start: ```sh git clone https://github.com/Crow-Tech-Pte-Ltd/CrowHR.git && cd CrowHR cp .env.example .env # edit .env: set PUBLIC_URL, e.g. https://hr.example.sg docker compose up -d ``` The first start prints a one-time setup code (`docker compose logs app | grep -A3 'SETUP CODE'`); open `PUBLIC_URL` and enter it to create your company and its owner. Crow HR runs as one app container and PostgreSQL 17, with no Redis, no queue and no cloud account. The [quick start](https://hr.crow.sg/docs/quick-start/) has the details. ## Guides - **Run the server:** [Install](https://hr.crow.sg/docs/self-hosting/install/) · [Configuration](https://hr.crow.sg/docs/self-hosting/configuration/) · [Reverse proxy](https://hr.crow.sg/docs/self-hosting/reverse-proxy/) · [Backups](https://hr.crow.sg/docs/self-hosting/backups/) · [Upgrades](https://hr.crow.sg/docs/self-hosting/upgrades/) - **Set up and run HR:** [Setup wizard](https://hr.crow.sg/docs/admin/setup-wizard/) · [Members and roles](https://hr.crow.sg/docs/admin/members-and-roles/) · [Running payroll](https://hr.crow.sg/docs/payroll/running-payroll/) · [Leave](https://hr.crow.sg/docs/leave/leave/) · [Attendance](https://hr.crow.sg/docs/attendance/attendance/) · [Claims](https://hr.crow.sg/docs/claims/claims/) · [Scheduling](https://hr.crow.sg/docs/scheduling/scheduling/) - **Build on it:** [API reference](https://hr.crow.sg/docs/api/) · [Architecture](https://hr.crow.sg/docs/developers/architecture/) · [Contributing](https://hr.crow.sg/docs/developers/contributing/) --- # Introduction > What Crow HR is, who it is for, how it is licensed and what it means that you host it and own the data. Source: https://hr.crow.sg/docs/introduction/ Crow HR is an HR and payroll platform for small and medium companies in Singapore. It is made by Crow Tech Pte. Ltd., released under the MIT licence, and designed to run on a server you control. ## Who it is for A Singapore company with a handful to a few hundred employees and one person who is comfortable running a Docker container. That person does not need to be a DevOps engineer: the install is four short steps with one required setting, backups and database upgrades run on their own, and every startup error says which setting to fix. Typical users inside the company: | Who | What they do in Crow HR | | --- | --- | | Owner | Sets up the company and sign-in, grants roles, approves payroll runs. | | HR admin | Keeps employee records, imports staff, handles lifecycle events and change requests, sets leave, attendance and claim policies, issues letters and documents. | | Payroll admin | Runs payroll, reviews the CPF working, releases payslips, pays claims and downloads the statutory files. | | Manager | Sees their team, builds rosters, corrects timesheets, approves leave, overtime, claims and swaps routed to them. | | Employee | Signs in to see their own profile, payslips and documents, applies for leave, clocks in, files claims, sees their shifts and asks for changes to their details. | The exact rights of each role are on the [roles and permissions](https://hr.crow.sg/docs/roles-and-permissions/) page. ## Free and open source The code is MIT-licensed: you may use, change and redistribute it, including commercially, without paying anyone. There is no paid tier hidden behind the open version and no feature flag that phones home. Contributions are welcome; see [contributing](https://hr.crow.sg/docs/developers/contributing/). ### Licence Crow HR is © Crow Tech Pte. Ltd. and contributors, under the [MIT licence](https://github.com/Crow-Tech-Pte-Ltd/CrowHR/blob/main/LICENSE). It ships with open-source packages under their own permissive licences (MIT, Apache-2.0, ISC, BSD and similar; no GPL-family licences) and with the Azeret Mono, Ubuntu and Noto fonts (SIL Open Font License 1.1 and Ubuntu Font Licence 1.0). Every package, version and licence is listed in [THIRD-PARTY-NOTICES.md](https://github.com/Crow-Tech-Pte-Ltd/CrowHR/blob/main/THIRD-PARTY-NOTICES.md), which is also in the Docker image at `/app/THIRD-PARTY-NOTICES.md` next to `/app/LICENSE`. ## Self-hosted: you own the data Crow HR runs as one app container and a PostgreSQL 17 database on your machine, in your office or with the cloud provider you choose. Crow Tech does not run a hosted service for it and receives nothing from your install: - no analytics, telemetry or usage reporting; - no calls to third-party services unless you configure them (your SMTP server, your identity provider, optionally your own error-monitoring service); - fonts, icons and the web app are served from your server, not from a CDN. Sensitive identifiers (NRIC/FIN, passport and work pass numbers, bank account numbers) and secrets (two-step verification, SSO) are encrypted in the database with a key that stays in your data volume and your backups. Your company remains the organisation responsible for the personal data under the PDPA; see [privacy and PDPA](https://hr.crow.sg/docs/help/privacy-pdpa/). ## What it covers Employee records and self-service, leave, attendance and overtime, shift scheduling, expense claims, approvals, documents and HR letters, reports, and monthly payroll with CPF, SHG, SDL and the files you upload to CPF, your bank and IRAS. Staff use it in the browser or in the [mobile apps](https://hr.crow.sg/docs/mobile-apps/) for Android, iPhone and iPad. The [project status](https://hr.crow.sg/docs/status/) page lists what is built, what is partly done and what is not. To look around first, open the [in-browser demo](https://hr.crow.sg/docs/demo/) at [hr.crow.sg](https://hr.crow.sg/). ## Not legal advice Crow HR implements Singapore's statutory rules from cited official sources and records how they were checked (see [how we verify statutory calculations](https://hr.crow.sg/docs/payroll/verification/)). It is not endorsed or approved by CPF Board, IRAS or MOM, and it does not replace your own judgement or professional advice. The [limitations](https://hr.crow.sg/docs/payroll/limitations/) page lists what you need to check yourself. --- # Quick start > Install Crow HR with Docker Compose, then finish setup in the browser. Source: https://hr.crow.sg/docs/quick-start/ You need a machine with Docker Engine 24+ and the Compose plugin, 2 GB of RAM and a few GB of disk. Using an AI coding agent such as Claude Code or Codex? **Copy for my AI** under the title copies a prompt that lets it do this install with you; see [set up with an AI agent](https://hr.crow.sg/docs/self-hosting/ai-agent/). ## 1. Get the files ```sh git clone https://github.com/Crow-Tech-Pte-Ltd/CrowHR.git && cd CrowHR ``` Only `docker-compose.yml` and `.env.example` are needed from the checkout. ## 2. Copy the example settings ```sh cp .env.example .env ``` ## 3. Set the address people will open Edit `.env` and set `PUBLIC_URL`: ```sh PUBLIC_URL=https://hr.example.sg # behind a reverse proxy with HTTPS # PUBLIC_URL=http://192.168.1.20:8080 # or on your office network, no proxy ``` ## 4. Start it ```sh docker compose up -d ``` That is all that is required. Compose pulls the published image (`ghcr.io/crow-tech-pte-ltd/crowhr:1`, amd64 or arm64), and the database password, the encryption key and a one-time setup code are generated on first start. ## Then finish in the browser 1. Print the setup code: `docker compose logs app | grep -A3 'SETUP CODE'`. 2. Open `PUBLIC_URL`. You land on `/setup`. 3. Enter the code, the company's registered name and the owner's name, email and password. You are signed in as the owner. 4. Run `docker compose exec app crowhr backup` and copy the archive somewhere safe. Before you store real data, set `BACKUP_PASSPHRASE` in `.env` (backups contain the encryption key) and, behind a proxy, `TRUSTED_PROXIES`. The full walkthrough is [install with Docker Compose](https://hr.crow.sg/docs/self-hosting/install/). ## What next - Put it behind HTTPS: [reverse proxy](https://hr.crow.sg/docs/self-hosting/reverse-proxy/). - Fill in the company profile and structure: [company and structure](https://hr.crow.sg/docs/admin/company-and-structure/). - Add or import employees: [adding employees](https://hr.crow.sg/docs/people/adding-employees/), [importing from CSV](https://hr.crow.sg/docs/people/importing/). - Turn on single sign-on: [sign-in methods](https://hr.crow.sg/docs/admin/sign-in-methods/). --- # Project status > Which Crow HR modules are built and tested, which are partly done or only reachable through the API, and what is not built. Source: https://hr.crow.sg/docs/status/ This page describes Crow HR 1.1.1. A module is listed as built when it works end to end and is tested. Check every result before you pay or file it. ## Built | Area | What works | Guide | | --- | --- | --- | | Self-hosting | Docker Compose install with the published multi-arch image (amd64 and arm64), setup wizard, automatic migrations with a lock, scheduled and manual backups (encrypted when `BACKUP_PASSPHRASE` is set, which is strongly recommended), restore, `crowhr` CLI, **Settings → System** | [Install](https://hr.crow.sg/docs/self-hosting/install/) | | Sign-in and security | Email and password, TOTP two-step verification and recovery codes, MFA policy for privileged roles, sessions and device list, security notices, Google Workspace, Microsoft Entra ID and generic OpenID Connect SSO, an append-only audit log with hash chaining | [Sign-in methods](https://hr.crow.sg/docs/admin/sign-in-methods/) | | Members and roles | Invitations, owner / HR admin / payroll admin roles, derived manager and employee roles, permission matrix enforced on the server | [Roles and permissions](https://hr.crow.sg/docs/roles-and-permissions/) | | Company and people | Company profile, structure, work schedules, employee records with history, CSV import, export, lifecycle events, work passes, checklists, self-service change requests | [Adding employees](https://hr.crow.sg/docs/people/adding-employees/) | | Approvals and notifications | Approval policies, delegation, escalation, Home work-to-do list, inbox, in-app and email notifications, reminders | [Approvals](https://hr.crow.sg/docs/approvals/approvals/) | | Leave | Statutory and Government-paid leave types, policies with the statutory floor, accrual and carry-forward, applications with half days and documents, approval and cancellation, team calendar, public holidays in lieu, part-timers in hours, encashment, Government-paid leave report, year-end close | [Leave](https://hr.crow.sg/docs/leave/leave/) | | Attendance and overtime | Clock in and out with an offline queue, optional location and office-network checks, timesheets and corrections, optional timesheet approval that locks approved periods, lateness rules, overtime claims with the Part 4 test and the 72-hour warning | [Attendance](https://hr.crow.sg/docs/attendance/attendance/) | | Claims | Claim types with caps and eligibility, multi-line claims with receipts, foreign currency at manual rates, approvals, reimbursement through payroll or recorded as paid outside it | [Claims](https://hr.crow.sg/docs/claims/claims/) | | Scheduling | Shift templates, weekly rosters with a keyboard-driven grid, conflicts and hour warnings, publishing with notifications, swaps and open shifts | [Scheduling](https://hr.crow.sg/docs/scheduling/scheduling/) | | Payroll | Monthly, off-cycle and adjustment runs; CPF, SHG, SDL and FWL estimate; no-pay leave, overtime, scheduled days, holiday pay, leave encashment and claims fed from the other modules; review with CPF working; approval; payslips (web and PDF) with a notification on release; CPF EZPay file; ISO 20022 bank file; IR8A export with Appendix 8A (benefits-in-kind) and 8B (share gains) | [Running payroll](https://hr.crow.sg/docs/payroll/running-payroll/) | | Documents | Per-employee documents in categories with access rules, versions, expiry reminders, soft delete; HR letters and KETs from templates; acknowledgements; employment letter requests; retention review flags | [Employee documents](https://hr.crow.sg/docs/documents/documents/) | | Reports | Headcount, headcount over time, turnover, work pass expiry, leave taken and balances with liability, attendance exceptions, scheduled hours, claims, payroll cost; CSV and XLSX export | [Reports](https://hr.crow.sg/docs/reports/running-reports/) | | Mobile apps | Native Android and iPhone/iPad apps for payslips, leave, clocking in, claims, schedules and approvals, connecting only to your own server. The Android app is on Google Play and the iPhone and iPad app on the App Store. | [Mobile apps](https://hr.crow.sg/docs/mobile-apps/) | | In-browser demo | The real app and API running in the visitor's browser with a fictional company, personas and a resettable local database, at [hr.crow.sg](https://hr.crow.sg/) | [Demo](https://hr.crow.sg/docs/demo/) | ## Partly done | Item | State | | --- | --- | | Singpass login | Implemented to Singpass's FAPI 2.0 login profile and tested against **Singpass staging**; not yet against Singpass production. The official Singpass logo for the button has to be added by whoever runs the server, because it can't ship in the repository. See the [Singpass guide](https://hr.crow.sg/docs/admin/sso/singpass/). | | Virus scanning | Receipts, documents and medical certificates are scanned by your own ClamAV when you set `CLAMAV_HOST` ([configuration](https://hr.crow.sg/docs/self-hosting/configuration/#optional-virus-scanning)). No scanner ships with Crow HR, so without one uploads are stored unscanned. | | Payroll inputs from other modules | Rest-day and public-holiday work premiums are entered by hand, and overtime fed from attendance for staff outside Part 4 or paid by the hour needs its contractual amount entered on the run. See [payroll limitations](https://hr.crow.sg/docs/payroll/limitations/#payroll-inputs). | | Features without a screen | These work through the [API](https://hr.crow.sg/docs/api/) but have no control in the web app yet: adding allowance types and recurring allowances, per-schedule start times for lateness, leave balance adjustments, editing a child's record, and filing overtime for another employee. | ## Not built - Direct submission to CPF, IRAS or banks: Crow HR produces the CPF EZPay file, the ISO 20022 bank file and the IR8A export for you to upload. - API keys or service accounts for server-to-server integrations. - The other integrations listed under [not available](https://hr.crow.sg/docs/integrations/#not-available). The [limitations](https://hr.crow.sg/docs/payroll/limitations/) page lists the known gaps inside the built modules, and each module's guide ends with its own. --- # In-browser demo > How Crow HR's in-browser demo works - the real app and API running in your browser against fictional data - what differs from a self-hosted install, and where to try it (hr.crow.sg). Source: https://hr.crow.sg/docs/demo/ Crow HR has an in-browser demo: the same web app and the same API code that a self-hosted install runs, started inside the visitor's browser instead of on a server. Try it at **[hr.crow.sg](https://hr.crow.sg/)**, next to these docs. You can also build and open it on your own machine (see [running it locally](#running-it-locally)) or [install Crow HR](https://hr.crow.sg/docs/quick-start/). ![The demo's sign-in page: a banner saying it runs entirely in your browser, and five personas to sign in as with one click (fictional company)](../../assets/screens/demo-personas.webp) ## How it works - **No backend.** The site is static files. The Crow HR API runs in a Web Worker in your tab, against PostgreSQL compiled to WebAssembly (PGlite), saved in your browser's IndexedDB. Nothing you type reaches a server, and there are no analytics or third-party requests. - **The real code.** Payroll is calculated by the real engine with the cited Singapore rules, approvals go through the real workflow engine, and permissions are enforced by the same server code as a self-hosted install. - **Your own copy.** Each browser gets its own database, restored from a pre-built database snapshot on the first visit; if that download is missing or corrupt, the same seed runs in your browser. **Reset** in the demo banner wipes your copy, restores the snapshot and re-anchors the clock; clearing the site's data in your browser does the same. When a new version of the demo changes its data, your next visit starts from a fresh copy automatically. - **One tab at a time.** Two tabs writing the same local database would corrupt it, so a second tab offers to take over instead. ## The demo company Kopi Kaki Pte. Ltd. is a fictional café group with an office, a central kitchen and three outlets. 25 people work there (one starts in November) and two left this year. They include citizens, permanent residents in their first, second and later years, Employment Pass, S Pass and Work Permit holders, every self-help group fund, part-timers and employees on each CPF age boundary. Every name, NRIC/FIN, bank account and email address is invented. Payroll for July to September 2026 is approved and paid. October is a draft run with warnings, and it already includes the overtime that managers approved from October's clock-ins. Rosters are published for October and the following week at the three outlets. Sign in with one click as one of five personas, or type any seeded account's email with the shared password `kopi-kaki-demo`: | Persona | Name | What they do in the demo | | --- | --- | --- | | Owner | Lim Kah Hui | Managing director. Approves payroll and her direct reports' claims. | | HR admin | Nur Aisyah binte Rahman | People records, change requests and the second claims step. | | Payroll admin | Chloe de Souza | Prepares the monthly run, bank file and CPF file. | | Manager | Siti Nurhaliza binte Osman | Jurong Point outlet supervisor. Approves her team's claims, leave and a pending shift swap. | | Employee | Goh Jun Jie | Barista at Tanjong Pagar. Payslips, claims, schedule and a document to acknowledge. | Three things to try: - As **Payroll admin**, open the October run and pick an employee to see how their CPF was worked out, step by step, with links to CPF's rate tables. - As **Manager**, approve the shift swap waiting in the Inbox. The two shifts then move on the Jurong Point roster in **Schedules**. - As **Employee**, acknowledge the updated terms waiting on Home, then open a payslip. ## What differs from a self-hosted install | Area | In the demo | Self-hosted | | --- | --- | --- | | Signing in | One click on a persona, or the shared password. Two-step verification is not required. | Email and password, two-step verification (required for admin roles by default), SSO. | | Google, Microsoft, Singpass | Buttons are shown but disabled; no request is made to any identity provider. (A demo can be built with a real Singpass login that keeps nothing about the visitor, see [Singpass login](https://hr.crow.sg/docs/admin/sso/singpass/#public-demo); hr.crow.sg does not offer it.) | Work once an owner configures them. | | Email | Nothing is sent. Messages appear in the **Demo outbox** (from the banner), so invitation and reset links still work. | Sent over SMTP if configured. | | Passwords | PBKDF2 in a demo-only format that a real server refuses. | argon2id. | | Encryption at rest | NRIC/FIN and bank numbers are encrypted with a throwaway key included with the fictional snapshot and stored next to the database. The fallback seed creates a fresh key. Fine for invented data, never a pattern for real data. | Encrypted with the server's `CROWHR_SECRET_KEY`. | | Date | The company lives on Saturday 31 Oct 2026: every visit starts there at 11:30 Singapore time, after the outlets' morning crews have clocked in, and the clock then runs normally. Reset re-anchors it. | The real date. | | Uploaded files | Stored in the browser database. | Stored on the server's disk volume. | | Background jobs | Reminders, escalations and the outbox run every 30 seconds while a demo tab is open, and catch up on the next visit. | Every 60 seconds in the server process. | | Backups and system status | Not applicable. | Daily `pg_dump` to the backups volume. | ## Known differences - Kopi Kaki moved to Crow HR in July 2026: its January–June opening balances were imported with **Year-to-date balances**, so July to September show no issues and October only its real one (a leaver's final pay). - Receipt previews and PDF or CSV downloads go through a service worker. Where service workers are unavailable (some private-browsing modes), those previews and downloads fail; everything else works. - A tab closed in the middle of a request can lose that one request. - Nothing is filed with CPF Board, IRAS or a bank, here or in the product: Crow HR produces the files for you to upload. The demo's own **About this demo** page (`/about-demo`) lists the same differences for visitors. ## Running it locally From a checkout, with [Bun](https://bun.sh) installed: ```sh bun install # build the demo and these docs into apps/demo/dist-site bun run demo:site # serve them at http://127.0.0.1:5181 node apps/demo/scripts/serve.ts apps/demo/dist-site ``` The preview server applies the same headers and redirects as the static host would. Keep it on your own machine: the demo has a shared password and no real security, by design. --- # Install with Docker Compose > Install Crow HR on your own server with Docker Compose, finish setup in the browser and take your first backup. Source: https://hr.crow.sg/docs/self-hosting/install/ The short version is on the [quick start](https://hr.crow.sg/docs/quick-start/) page, and an AI coding agent can do these steps with you: see [set up with an AI agent](https://hr.crow.sg/docs/self-hosting/ai-agent/). An automated test runs these steps as written on every change to Crow HR. You need a machine with Docker Engine 24+ and the Compose plugin (`docker compose version`), 2 GB of RAM and a few GB of disk. Crow HR runs as two containers, the app and PostgreSQL 17. There is no Redis and no queue. ## 1. Get the files You need two files from the repository, `docker-compose.yml` and `.env.example`. The simplest way to get them is to clone it: ```sh git clone https://github.com/Crow-Tech-Pte-Ltd/CrowHR.git cd CrowHR ``` Compose pulls the published image, `ghcr.io/crow-tech-pte-ltd/crowhr:1`, built for both amd64 and arm64 (Intel/AMD and 64-bit ARM servers). `:1` follows the newest 1.x release. To run an image you build yourself, see [build the image yourself](#build-the-image-yourself). ## 2. Configure ```sh cp .env.example .env ``` Open `.env` and set one line, the address people will type in the browser: ```sh PUBLIC_URL=https://hr.example.sg # behind a reverse proxy with HTTPS # or PUBLIC_URL=http://192.168.1.20:8080 # on your office network, no proxy ``` Everything else has a working default. Recommended before you store real data: - `BACKUP_PASSPHRASE` encrypts backups. Without it, a backup file includes your encryption key in the clear. See [backups and restore](https://hr.crow.sg/docs/self-hosting/backups/). - `TRUSTED_PROXIES` is needed when you use a reverse proxy. See [reverse proxy](https://hr.crow.sg/docs/self-hosting/reverse-proxy/). Every variable is listed in the [configuration reference](https://hr.crow.sg/docs/self-hosting/configuration/). ## 3. Start ```sh docker compose up -d docker compose ps # app and db should become "healthy" within a minute or two ``` On first start Crow HR: - creates a random database password in the `secrets` volume (the one-shot `init` service); - applies the database migrations; - generates the encryption key into the data volume (`/data/secrets/crowhr.key`, mode 600) and logs where it is; - prints a one-time setup code. ## 4. Finish setup in the browser ```sh docker compose logs app | grep -A3 'SETUP CODE' ``` Open `PUBLIC_URL`. Every page redirects to `/setup` until setup is done. Enter the code, your company's registered name, and the owner's name, email and password. You are then signed in as the owner and offered two-step verification. Afterwards `/setup` no longer exists. The [setup wizard](https://hr.crow.sg/docs/admin/setup-wizard/) page explains each field. The code changes on every restart; `docker compose exec app crowhr setup-code` prints a fresh one. Five wrong codes from one address block it for 15 minutes. ## 5. Check it ```sh docker compose exec app crowhr doctor ``` `doctor` checks the configuration, database, migrations, encryption key, disk space, clock and the proxy headers the app sees, and says what to fix. Owners see the same facts in **Settings → System**. Then make your first backup and copy it somewhere else: ```sh docker compose exec app crowhr backup ``` ## What is where | Volume | Holds | Back up? | | --- | --- | --- | | `data` (`/data`) | uploaded files, `secrets/crowhr.key` | yes (backups include it) | | `db` | PostgreSQL data | yes (backups include a `pg_dump`) | | `backups` (`/backups`) | backup archives | copy them off this machine | | `secrets` (`/run/crowhr-secrets`) | generated database password | no: a restore works with a fresh one | Only the app's port is published (`HTTP_PORT`, default 8080, on `BIND_ADDRESS`, default all interfaces). PostgreSQL has no host port. The app runs as uid 10001 on a read-only root filesystem. ## Build the image yourself To run your own build of the checkout instead of the published image: ```sh docker build -t crowhr:local . echo 'CROWHR_IMAGE=crowhr:local' >> .env docker compose up -d ``` The build takes a few minutes. To upgrade, `git pull`, build again and run `docker compose up -d`; `docker compose pull` only updates published images. ## Next - [Configuration reference](https://hr.crow.sg/docs/self-hosting/configuration/) - [Reverse proxy](https://hr.crow.sg/docs/self-hosting/reverse-proxy/) - [Backups and restore](https://hr.crow.sg/docs/self-hosting/backups/) - [Upgrades](https://hr.crow.sg/docs/self-hosting/upgrades/) - [Troubleshooting](https://hr.crow.sg/docs/self-hosting/troubleshooting/) --- # Set up with an AI agent > Copy a ready-made prompt that lets an AI coding agent such as Claude Code or Codex install Crow HR on your server with you, from Docker Compose and HTTPS to backups and your people's first sign-in. Source: https://hr.crow.sg/docs/self-hosting/ai-agent/ If you use a coding agent that can run commands on your server (Claude Code, Codex, Gemini CLI or another), it can install Crow HR with you. **Copy for my AI**, under the title of every docs page, copies the prompt below. Paste it into the agent on the server, or on a computer that reaches the server over SSH. ## What the agent does - Asks you first: where Crow HR will run, the address people will type, how HTTPS should work, whether to send email, and where backups go. - Installs Crow HR with Docker Compose the way the [install guide](https://hr.crow.sg/docs/self-hosting/install/) describes, sets up [HTTPS](https://hr.crow.sg/docs/self-hosting/reverse-proxy/), and checks the result with `crowhr doctor`. - Leaves the secrets to you: you type the backup passphrase, the SMTP password and the tunnel token into `.env`, read the one-time setup code yourself, and create the owner account in your own browser. - Takes the first [backup](https://hr.crow.sg/docs/self-hosting/backups/) and sets up a copy off the server. - Tells you how to add your people and connect the phone app. :::caution[You stay in charge] The agent runs commands on your server. Read what it proposes before it runs it, keep passwords and codes out of the chat, and make DNS and Cloudflare changes in your own browser. ::: ## The prompt ````markdown You are helping me set up Crow HR for my company: the free, open-source (MIT) HR and payroll software for Singapore SMEs, https://github.com/Crow-Tech-Pte-Ltd/CrowHR. Goal: Crow HR running on my server with Docker Compose at an address my staff can reach (over HTTPS, unless it stays on our office network), my owner account created with two-step verification, encrypted backups running and copied off the machine, and my people able to sign in on the web and in the Crow HR phone app. Work one step at a time. Before you run a command, tell me what it does and why, and show me the output when something fails. Follow the Crow HR docs at https://hr.crow.sg/docs/. If what you see doesn't match these instructions, read the matching page before you improvise: every page is also available as Markdown (add `.md` to its address, for example https://hr.crow.sg/docs/self-hosting/install.md), and https://hr.crow.sg/docs/llms-full.txt has all of them in one file. Don't invent settings: every variable is in https://hr.crow.sg/docs/self-hosting/configuration.md. ## Before you start, ask me 1. Where will it run: a VPS or cloud server with a public IP, a machine on our office network only, or a server that already runs Docker or a web server? Are you on that machine, or do you reach it over SSH (which host and user)? 2. The address people will type: a domain or subdomain such as `hr.example.sg` (and who manages its DNS), or an office-network address such as `http://192.168.1.20:8080`. 3. How HTTPS should work: Caddy in Docker (needs ports 80 and 443 open and a DNS record pointing at the server), an nginx or Traefik that already runs there, a Cloudflare Tunnel (no open ports; the domain's DNS must be on Cloudflare), or none (office network only). 4. Whether Crow HR should send email (invitations, password resets, notifications) through an SMTP server, and which one. Without email everything still works: invitations show a link to copy. 5. Where backups should be copied to: another computer, or a remote that rclone supports (S3, B2, Google Drive and others). ## Prerequisites - A Linux server (amd64 or arm64) with Docker Engine 24 or later and the Compose plugin (`docker compose version`), 2 GB of RAM and a few GB of disk. - Crow HR runs as two containers, the app and PostgreSQL 17. There is no Redis and no queue. ## Steps 1. **Get the files.** `git clone https://github.com/Crow-Tech-Pte-Ltd/CrowHR.git`, then `cd CrowHR`. Compose pulls the published image `ghcr.io/crow-tech-pte-ltd/crowhr:1`, which follows the newest 1.x release. 2. **Configure.** `cp .env.example .env`, then set: - `PUBLIC_URL`: exactly the address people will type, with scheme, host and port. An `https` address sets secure cookies, which browsers drop over plain `http`. - `BACKUP_PASSPHRASE`: at least 12 characters. Ask me to type it into `.env` myself rather than into this chat, and remind me to keep a copy outside this server. Scheduled backups don't run without it, and an encrypted backup can't be restored without it. - With a proxy or tunnel on this machine: `TRUSTED_PROXIES=private` and `BIND_ADDRESS=127.0.0.1`. On the office network with no proxy: leave `TRUSTED_PROXIES` empty. - Email, only if I want it: `SMTP_URL` (`smtps://user:password@smtp.example.sg:465`, or `smtp://user:password@smtp.example.sg:587`; URL-encode special characters, `@` becomes `%40`) and `MAIL_FROM` (for example `"Crow HR "`, an address my mail provider lets me send from). I type the SMTP password myself. - Leave everything else at its default unless the configuration reference says my setup needs it. 3. **HTTPS**, following https://hr.crow.sg/docs/self-hosting/reverse-proxy.md for my choice: - Caddy: `cp deploy/caddy/docker-compose.override.example.yml docker-compose.override.yml` and `cp deploy/caddy/Caddyfile.example Caddyfile`, then set my domain in `Caddyfile`. DNS: an `A` record for the domain pointing at the server (DNS only, not proxied, if it's on Cloudflare), and ports 80 and 443 open in the server's and the provider's firewall. - nginx or Traefik: use that page's example as written. For nginx keep the `upstream` block with its `resolver`, `client_max_body_size 25m`, and `proxy_set_header X-Forwarded-For $remote_addr` (replace the header, don't append to it). - Cloudflare Tunnel: add the `cloudflared` service from that page to `docker-compose.override.yml`. I create the tunnel in the Cloudflare Zero Trust dashboard, route the hostname to `http://app:8080` and put `CLOUDFLARE_TUNNEL_TOKEN` into `.env` myself. If we'll use Singpass login, I must not turn on Bot Fight Mode for that hostname. 4. **Start.** `docker compose up -d` (always all services, never `docker compose up app`), then `docker compose ps` until `app` and `db` are healthy, usually within a minute or two. 5. **Owner account.** I run `docker compose logs app | grep -A3 'SETUP CODE'` myself, so the code stays out of this chat (a fresh one: `docker compose exec app crowhr setup-code`; the code changes on every restart). Then stop and wait: I open `PUBLIC_URL`, enter the code, the company's registered name and the owner's name, email and password, and turn on two-step verification. 6. **Check it.** Run `docker compose exec app crowhr doctor` and fix whatever it reports. Then I open **Settings → System → This request**: it should show my own IP address, `https` behind TLS, and "Trusted proxy" when there is a proxy. 7. **Backups.** Take the first one with `docker compose exec app crowhr backup`. Then set up a nightly copy off the machine, for example `docker compose cp app:/backups/ ./` to another computer, or the rclone line on https://hr.crow.sg/docs/self-hosting/backups.md in the host's crontab (the volume is `_backups`; check with `docker volume ls`). Scheduled backups run daily at 02:00 Singapore time (`BACKUP_TIME`) once `BACKUP_PASSPHRASE` is set. If I want, help me test a restore on another machine with the steps on that page. 8. **My people.** Tell me what comes next in Crow HR: the company profile and payroll settings, then adding employees in **People**, one by one or by importing a CSV. Hiring someone sends their invitation; without email, I copy the invitation link from the app. Each person finds the code that connects the Crow HR phone app (App Store and Google Play) in **My profile → Mobile app**. The app needs HTTPS; on the office network it connects over plain HTTP only to a private address, after a warning. ## Verify at the end - `docker compose ps` shows `app` and `db` healthy, and `PUBLIC_URL` opens the sign-in page over HTTPS with a valid certificate (or over HTTP on the office network). - `/api/health` answers with the Crow HR version. - `crowhr doctor` reports nothing to fix, and **Settings → System** shows the last backup. - I'm signed in as the owner with two-step verification on, and a backup archive exists outside the server. ## Upgrading later `docker compose pull`, `docker compose up -d`, then `docker compose logs -f app` until it says "Crow HR is ready". A backup is taken before every database upgrade. To decide when to upgrade, pin a release with `CROWHR_IMAGE=ghcr.io/crow-tech-pte-ltd/crowhr:` in `.env`. Read the release notes (https://github.com/Crow-Tech-Pte-Ltd/CrowHR/releases) before a major upgrade. ## Common pitfalls - `Crow HR cannot start: … PUBLIC_URL …` or another named setting: fix `.env` as the message says, then `docker compose up -d`. - Everyone gets the same IP address and sign-in limits hit the whole office: `TRUSTED_PROXIES` doesn't match the proxy. The log says `Ignoring X-Forwarded-* headers from `, and `crowhr doctor` suggests a value. - Signed out right after signing in: `PUBLIC_URL` doesn't match the address in the browser exactly. - `Port 8080 is already in use`: change `HTTP_PORT` in `.env`. - Caddy can't get a certificate: the DNS record is proxied (orange cloud), or ports 80 and 443 aren't reachable from the internet. - `CROWHR_SECRET_KEY does not match this database`: the data volume or the key was lost. Restore the key from a backup with `crowhr restore --secrets-only`; never delete the database to "fix" it. ## Rules for you - Never run `docker compose down -v`, delete Docker volumes, or remove `/data/secrets/crowhr.key`. That destroys the database, or the key that decrypts NRIC, bank and single sign-on data. - Keep secrets out of this chat: setup codes, passwords, `BACKUP_PASSPHRASE`, SMTP passwords and tunnel tokens. Ask me to type them where they belong. - Don't put Crow HR on the internet without HTTPS, don't publish the database port, and don't switch off two-step verification or other security settings to make something work. - I make DNS, Cloudflare and other dashboard changes in my own browser. Tell me exactly what to set. - Don't enter real employee data while testing. To try things first, the in-browser demo at https://hr.crow.sg uses a fictional company. - When we're done, give me a short summary: the address, where `.env` and the backups are, and the commands to back up, restore and upgrade. ```` ## Reading the docs as Markdown The agent can read every page of these docs as Markdown: add `.md` to a page's address (for example [install.md](https://hr.crow.sg/docs/self-hosting/install.md)), or fetch [llms-full.txt](https://hr.crow.sg/docs/llms-full.txt) for all pages in one file. [llms.txt](https://hr.crow.sg/docs/llms.txt) lists the pages. **Copy page**, under each page's title, copies that page as Markdown, to ask an assistant about it. --- # Configuration reference > Every environment variable Crow HR reads, with defaults, valid values and what each one does. Source: https://hr.crow.sg/docs/self-hosting/configuration/ Set variables in `.env` next to `docker-compose.yml`, then run `docker compose up -d` to apply them (it recreates only what changed). Empty values count as unset. At startup every variable is checked. A wrong value stops the app with a message naming the variable, what is wrong, a valid example and where to set it (exit code 78). All problems are reported in one run, so you fix them once. :::note[Kept in sync with the code] This page is checked by a test (`apps/docs/tests/env-vars.test.ts`) that reads every environment variable the server, the CLI, the Dockerfile and `docker-compose.yml` use. The test fails when a variable is missing here, or when this page lists one the code no longer reads. ::: ## Required | Variable | Example | Meaning | | --- | --- | --- | | `PUBLIC_URL` | `https://hr.example.sg` | The address people open: scheme and host (and port), no path. Cookies are `Secure` (and use the `__Host-` prefix) when this is `https`, even if a proxy talks plain HTTP to the app. Links in emails, the CSRF origin check and SSO redirect URIs use it. Crow HR must live at the root of its own (sub)domain. Required in production; in development it defaults to `http://localhost:8080`. | ## Network | Variable | Default | Meaning | | --- | --- | --- | | `HTTP_PORT` | `8080` | Host port published by compose. Inside the container the app always listens on 8080. | | `BIND_ADDRESS` | `0.0.0.0` | Host address the port binds to. Use `127.0.0.1` when a proxy on the same machine is the only way in. | | `TRUSTED_PROXIES` | empty | Comma-separated IPs/CIDRs (IPv4 or IPv6) whose `X-Forwarded-For`, `X-Forwarded-Proto` and `X-Forwarded-Host` are believed. Shorthands: `private` (10/8, 172.16/12, 192.168/16, fc00::/7, loopback) and `loopback`. Empty: the TCP peer is the client and forwarded headers are ignored (the app logs a hint when it sees them). The client IP is the right-most `X-Forwarded-For` address that is not itself a trusted proxy, so clients cannot spoof it. | ## Backups | Variable | Default | Meaning | | --- | --- | --- | | `BACKUP_PASSPHRASE` | empty | Encrypts every backup archive with [age](https://age-encryption.org) (scrypt). At least 12 characters. Required for scheduled backups: they refuse to run without it because archives contain the encryption key. Keep it outside the server; restores need it. | | `BACKUP_TIME` | `02:00` | Daily scheduled backup time (24 h) in `BACKUP_TIMEZONE`, or `off`. If the server was down at that time it catches up later the same day. Not run until setup has created an organisation. | | `BACKUP_TIMEZONE` | `Asia/Singapore` | IANA time zone for `BACKUP_TIME`. | | `BACKUP_KEEP` | `14` | Newest archives kept in the backups directory after each scheduled backup (manual and pre-upgrade ones count). 1 to 3650. | | `BACKUP_BEFORE_MIGRATE` | `true` | Before applying database upgrades to a database that has data, write a backup (`…-pre-migrate.tar.gz`). If that backup fails, the upgrade does not start. | | `BACKUP_DIR` | `/backups` in the image | Where archives are written (the `backups` volume). In development: `/backups`. | ## Secrets and data | Variable | Default | Meaning | | --- | --- | --- | | `CROWHR_SECRET_KEY` | generated | 32 random bytes, base64 (44 characters) or hex (64 characters), for example from `openssl rand -base64 32`. Encrypts NRIC/FIN, bank account numbers, MFA and SSO secrets. When unset, one is generated on first start into `SECRET_KEY_FILE` (mode 600). When set, it wins over the file. The app refuses a key that does not match the database, and never generates a new key for a database that already has one. | | `SECRET_KEY_FILE` | `/secrets/crowhr.key` | Generated key location (`/data/secrets/crowhr.key` in the image). | | `DATA_DIR` | `/data` in the image, `./data` otherwise | The data volume. | | `FILE_STORAGE_DIR` | `/files` | Uploaded files. | ## Database Compose sets these for the bundled PostgreSQL; you normally leave them alone. | Variable | Default | Meaning | | --- | --- | --- | | `DATABASE_URL` | built from the parts below | Use an external PostgreSQL 17: `postgres://user:password@host:5432/db` (add `?sslmode=require` if needed). Takes precedence over the parts. In development without it, the server uses in-process PGlite in `./data/pglite` (`pglite:memory` for a throwaway database); PGlite is for development and tests only. | | `DATABASE_HOST` | `db` (compose) | Host of the bundled database. | | `DATABASE_PORT` | `5432` | | | `DATABASE_NAME` | `crowhr` | | | `DATABASE_USER` | `crowhr` | | | `DATABASE_PASSWORD` | unset | Database password, if you do not use a password file. | | `DATABASE_PASSWORD_FILE` | `/run/crowhr-secrets/db_password` (compose) | File holding the password, written by the compose `init` service (`crowhr init-secrets`). | | `DB_WAIT_SECONDS` | `60` | How long to wait for the database at startup ("waiting for database" is logged every 5 s), then exit with a `docker compose ps` hint. 0 to 3600. | | `MIGRATE_ON_START` | `true` | Apply migrations at startup under a Postgres advisory lock. With `false`, run `crowhr migrate` yourself. | | `MIGRATE_LOCK_TIMEOUT_SECONDS` | `300` | How long a second instance waits for another one's migrations. | ## Email Optional. Without it Crow HR works fully: notifications appear in the app (the bell, top right) and invitations and password resets show a link to copy. Owners see "Email is not configured" in **Settings → Notifications**. | Variable | Default | Meaning | | --- | --- | --- | | `SMTP_URL` | unset (email off) | `smtps://user:password@smtp.example.sg:465` (TLS from the start) or `smtp://user:password@smtp.example.sg:587` (STARTTLS required by default). URL-encode special characters in the user and password (`@` → `%40`). | | `SMTP_REQUIRE_TLS` | `true` on SMTP port 587; otherwise `false` | Require STARTTLS on an SMTP connection. Set `true` for a relay on another port, or explicitly `false` for a relay without STARTTLS. `smtps://` always uses implicit TLS. Only `true` and `false` are accepted. | | `MAIL_FROM` | required with `SMTP_URL` | Sender, for example `"Crow HR "`. Use an address your mail provider lets you send from (SPF/DKIM). Setting it without `SMTP_URL` is an error. | Notification emails go through an outbox: a failed send is retried after 1, 5, 30, 120 and 720 minutes, then marked failed; owners see failures in **Settings → Notifications**. Emails never contain salary or other amounts, NRIC/FIN, bank or medical details, only a short summary and a link. A wrong `SMTP_URL` or a missing `MAIL_FROM` stops startup with a message saying which one to fix. Invitations and password-reset emails are currently sent directly by the sign-in code, without the outbox's retries (see [limitations](https://hr.crow.sg/docs/payroll/limitations/#platform-and-sign-in)). ## Other | Variable | Default | Meaning | | --- | --- | --- | | `SETUP_CODE` | random per start | Fixed first-run setup code (16 characters from `34679ACDEFGHJKMNPQRTUVWXY`, for example `ACDE-FGHJ-KMNP-QRTU`) for scripted installs. Normally leave unset. | | `LOG_LEVEL` | `info` | `debug`, `info`, `warn` or `error`. Logs are JSON lines on stdout (compose keeps 3 × 10 MB per container). | | `HOST` | `0.0.0.0` in the image, `127.0.0.1` otherwise | Listen address inside the container. | | `PORT` | `8080` | Listen port inside the container (compose pins it to 8080). | | `WEB_DIST_DIR` | `/app/apps/web/dist` in the image | Built web app. | | `SETUP_GATE` | `true` | Redirect every page to `/setup` until setup is done. Tests only. | | `NODE_ENV` | `production` in the image | Outside the image (development) `PUBLIC_URL` defaults to `http://localhost:8080` and the database to `pglite:./data/pglite`. | | `DEMO_SINGPASS_PROVIDER_ID` | unset | Only for hosting the public demo's Singpass login: the id of this server's Singpass method (as in its redirect URI). Set together with `DEMO_SINGPASS_RETURN_URL`. Nobody is signed in on this server and nothing about the person is kept. See [Singpass login](https://hr.crow.sg/docs/admin/sso/singpass/#public-demo). | | `DEMO_SINGPASS_RETURN_URL` | unset | The demo sign-in page (full `https://` address, for example `https://hr.crow.sg/sign-in/kopi-kaki`) that demo visitors return to after Singpass. Set together with `DEMO_SINGPASS_PROVIDER_ID`. | ## Set by the image or compose file You do not set these in `.env`; they are listed so nothing the app reads is undocumented. | Variable | Set by | Meaning | | --- | --- | --- | | `CROWHR_IMAGE` | `docker-compose.yml` | Image to run, default `ghcr.io/crow-tech-pte-ltd/crowhr:1` (the newest 1.x release). The one exception to this table: set it in `.env` to stay on one release (`…:1.0.0`) or to run your own build (`crowhr:local`, see [build the image yourself](https://hr.crow.sg/docs/self-hosting/install/#build-the-image-yourself)). | | `CROWHR_CONTAINER` | Dockerfile (`1`) | Tells `crowhr restore` it runs inside the container, so it can restart the app afterwards by signalling PID 1. Outside Docker it prints "restart the app" instead. | | `NODE_OPTIONS` | Dockerfile | Silences Node's experimental-feature warnings in the logs. | | `CROWHR_GIT_SHA` | build argument (Dockerfile) | Commit the image was built from, added to the error-monitoring release (`crowhr@+`). Set in the published images; empty in your own build unless you run `docker build --build-arg CROWHR_GIT_SHA=$(git rev-parse HEAD) -t crowhr:local .`. | ## Optional virus scanning | Variable | Default | Meaning | | --- | --- | --- | | `CLAMAV_HOST` | unset (scanning off) | Private hostname/IP of your own clamd server. Enables the shared upload scan pipeline; no third-party service is contacted. | | `CLAMAV_PORT` | `3310` | clamd TCP port, 1–65535. Uses INSTREAM, a 15-second deadline and 64 KB chunks. | Configure these on the **app container** (for example an `environment` entry in a local compose override), then recreate it. Keep clamd on a private network: this protocol has no authentication or TLS. Crow HR does not install or operate clamd. Keep its signatures current with your own FreshClam service. No scanner is required to run Crow HR. Receipt, document and medical certificate uploads are initially `pending_scan`; the existing background sweep scans them and records `clean` or `infected`. Infected bytes are removed, the uploader is notified, and an audit event is written. Transport errors never mark a file clean: three failed attempts produce `scan_failed`. Medical certificates are unavailable until a configured scanner returns clean. Without configuration, files remain explicitly `unscanned` and the scanning-off notice remains visible. Requests default to a 1 MB body limit. Dedicated receipt/document uploads, CSV import previews, company logos and leave attachment requests have explicit larger limits, with each file's own size validation still enforced. ## Demo companies Only for a public demo server, such as the one Crow Tech runs for people who want to try the apps. Never turn this on for a company's own install. With `DEMO_COMPANIES=1`, anyone can open `/try` on the server, get a private copy of the fictional sample company Kopi Kaki in one tap, and sign in by picking a person (owner, HR admin, payroll admin, manager, employee), on the web and in the Crow HR mobile apps. Each copy is deleted with everything in it after `DEMO_COMPANY_TTL_HOURS`. The server stays a normal server for its other organisations. | Variable | Default | Meaning | | --- | --- | --- | | `DEMO_COMPANIES` | off | `1` (or `true`) offers demo companies at `/try`. Off: every demo-company route answers 404 and no organisation can become one. The `DEMO_COMPANY_*` settings are refused without it. | | `DEMO_COMPANY_TTL_HOURS` | `72` | Hours a demo company lives, counted from the moment a visitor starts it (1–720). | | `DEMO_COMPANY_POOL_SIZE` | `3` | Copies kept ready so a start is instant (0–20). The scheduler seeds one per minute while the pool is short; a copy nobody takes within a day is replaced. `0` seeds each copy while the visitor waits. | | `DEMO_COMPANY_MAX_LIVE` | `300` | Demo companies handed out at once, at most (1–10000). The pool stops growing at this number too. | | `DEMO_COMPANY_HOURLY_LIMIT` | `5` | Starts per network (client IP after `TRUSTED_PROXIES`; an IPv6 /48 counts as one network) per hour. | | `DEMO_COMPANY_DAILY_LIMIT` | `20` | Starts per network per day. Must be at least the hourly limit. | | `DEMO_COMPANY_SERVER_HOURLY_LIMIT` | `30` | Starts on the whole server per hour, every network together (1–10000), so many networks at once can't take every demo company. Must be at least `DEMO_COMPANY_HOURLY_LIMIT`. | | `DEMO_COMPANY_UPLOAD_QUOTA_MB` | `25` | Receipts, documents and letters one demo company may hold (1–1024). Uploads past it are refused with a message naming the limit. | In a demo company the server refuses changes to sign-in methods and security settings, single sign-on, invitations, passwords and two-step verification, and sends no email. Device sessions record the platform ("Android phone", "iPhone") instead of the device's own name. Demo companies are never listed by the API: the short name (`demo-` and 12 random characters) is the key to a visitor's copy. Each copy is seeded in its own in-memory database, one at a time (measured in November 2026: about 18 seconds and 22 CPU-seconds per copy; the app's memory went from about 320 MB to a peak of 1.1 GB during a seed and stayed near 950 MB), then copied into PostgreSQL (about 5 MB of database and 200 KB of files per copy before visitors add to it). Expired copies, with every row, file, session and person in them, are deleted by the scheduler on every server, even after the mode is turned off; `crowhr demo-companies purge` deletes them all at once (see [CLI](https://hr.crow.sg/docs/self-hosting/cli/)). The start limits keep only counts (per network, keyed by a hash of the address under the server's key, and one for the whole server) and delete each count when its hour or day ends. Set `TRUSTED_PROXIES` so the limits see each visitor's own address rather than the proxy's. Keep scheduled backups off on a demo server (`BACKUP_TIME=off`): a backup holds the demo companies live at that moment. ## Optional error monitoring Off by default: without a DSN no monitoring code is loaded and nothing is sent anywhere. Set a DSN to report errors and slow requests to **your own** [GlitchTip](https://glitchtip.com) or Sentry project (any Sentry-compatible service). Crow Tech receives nothing. | Variable | Default | Meaning | | --- | --- | --- | | `SENTRY_DSN` | empty (off) | The server project's DSN (GlitchTip: project settings, *Client keys (DSN)*). Reports unhandled errors and every `error` log entry (for example a failed scheduled backup) as issues, traces API requests, and forwards the app's log entries. | | `SENTRY_BROWSER_DSN` | empty (off) | DSN for the web app; may be the same project or a separate browser project. Browsers can read it (that is how browser reporting works), so use a DSN whose only right is sending events. The server puts it in the page at runtime (no rebuild) and allows its origin in the page's Content-Security-Policy. | | `SENTRY_ENVIRONMENT` | `production` in the image | Environment name shown in the monitoring service, for example `staging`. At most 64 characters, no spaces or slashes. | | `SENTRY_RELEASE` | `crowhr@` (`+` with `CROWHR_GIT_SHA`) | Release name for both server and browser events. | | `SENTRY_TRACES_SAMPLE_RATE` | `0.2` | Share of API requests and page loads traced, `0` to `1`. `0` turns tracing off. Health checks and static files are never traced. | | `SENTRY_ENABLE_LOGS` | `true` | Forward the app's log entries (at `LOG_LEVEL` and above) as logs. The console output does not change. | Crow HR holds NRIC/FIN, salaries, bank and medical details, so events carry no request or response bodies, cookies, query strings, IP addresses, user details, database query values or local variables, and no session replay. Request headers are limited to `User-Agent`, `Accept`, `Content-Type`, `Content-Length` and `X-Request-Id` (the ID shown to users with an error, also in the app's logs). Before anything is sent, error messages, log entries and breadcrumbs lose the values of a failed database query, and NRIC/FIN numbers and email addresses in them are masked; invitation and password-reset tokens are removed from page addresses, and element labels from click records. Console output is not attached. Expected failures (validation, permission, not found) are not reported; 4xx answers in the browser are not either. Error messages and log entries can still name records (IDs, file names, names of categories or shifts), so keep the monitoring service as private as the app. Set the variables in `.env` and run `docker compose up -d`: a restart applies them, no rebuild is needed. A wrong value stops the app with a message, like every other setting. --- # Reverse proxy (or none) > Run Crow HR behind Caddy, nginx, Traefik or Cloudflare Tunnel, or on a LAN without a proxy, and set TRUSTED_PROXIES correctly. Source: https://hr.crow.sg/docs/self-hosting/reverse-proxy/ Crow HR serves plain HTTP on one port and works behind any reverse proxy, or with none on a trusted LAN. No proxy is bundled. The app's scripts and styles are sent compressed (Brotli or gzip, prepared when the image is built), so compression in the proxy is optional; proxies leave those responses as they are. Two settings matter: - `PUBLIC_URL` is what people type, e.g. `https://hr.example.sg`. HTTPS cookies follow from it, so TLS can end at the proxy. - `TRUSTED_PROXIES` lists the proxy's address so the app believes its `X-Forwarded-For/-Proto/-Host`. If it is wrong, the app logs `Ignoring X-Forwarded-* headers from 172.18.0.5 … set TRUSTED_PROXIES=172.18.0.5`. **Settings → System → This request** and `crowhr doctor` show what the app sees. ## How each example was tested | Setup | How it was tested | | --- | --- | | No proxy (LAN) | Automated: the default compose install. | | Caddy | Automated: the shipped `Caddyfile.example` (below) in a `caddy:2-alpine` container on the compose network. Caddy installed on the host was not tested. | | nginx | Automated: the config below in `nginx:1.30-alpine` on the compose network, and the host variant below (with host networking standing in for nginx installed on the host). Only nginx 1.30. | | Traefik | Automated: the labels below with `traefik:v3.7` on the compose network (Docker provider, `exposedByDefault=false`, entrypoint `websecure` on port 443). Also by hand behind Cloudflare Tunnel, with a file-provider route. | | Cloudflare Tunnel | By hand: a remote-managed tunnel (token) in front of Traefik. Routing the hostname straight to `http://app:8080`, as below, was not tested. | The automated test runs on every change to Crow HR. For each proxy it sets `.env` as below (`PUBLIC_URL=https://hr.example.sg`), sends requests in which the client adds its own `X-Forwarded-For`, `X-Forwarded-Host` and `X-Forwarded-Proto`, and checks: - With `TRUSTED_PROXIES=private`, the app sees the client's real address (in Settings → System and in the sign-in audit entry), scheme `https` and host `hr.example.sg`. The client's own headers are ignored. - The session cookie is `__Host-` and `Secure`, and plain `http://` redirects to `https://` (Caddy and nginx; the Traefik labels add no port 80 route). - With `TRUSTED_PROXIES` empty, the app ignores the proxy's headers, records the proxy's own address, and logs the hint above. - Each proxy still reaches the app after the app container is recreated with a new address, which can happen on an upgrade. Not tested: getting or renewing a Let's Encrypt certificate, because the test machine has no public name. Instead, Caddy used its internal CA, nginx a self-signed certificate at the paths below, and Traefik (which has no `letsencrypt` resolver there) its default self-signed certificate. Also not tested: HTTP/3, IPv6, and clients on another machine (the test client is the Docker host). If you run a setup this page does not cover, please [open an issue](https://github.com/Crow-Tech-Pte-Ltd/CrowHR/issues) saying what worked or did not. ## No proxy (LAN) ```sh PUBLIC_URL=http://192.168.1.20:8080 TRUSTED_PROXIES= ``` Fine on an office network you trust. Passwords travel unencrypted over the LAN, and Settings → Security shows a "Not using HTTPS" warning. Do not expose this to the internet. ## Caddy (automatic HTTPS) Easiest when the machine has a public DNS name. The repository ships an optional override: ```sh cp deploy/caddy/docker-compose.override.example.yml docker-compose.override.yml cp deploy/caddy/Caddyfile.example Caddyfile # set your domain ``` `.env`: ```sh PUBLIC_URL=https://hr.example.sg TRUSTED_PROXIES=private BIND_ADDRESS=127.0.0.1 ``` `Caddyfile`: ```txt hr.example.sg { encode zstd gzip reverse_proxy app:8080 } ``` `docker compose up -d` starts Caddy too. Caddy replaces any client-supplied `X-Forwarded-For` with the real client address. Caddy installed on the host instead of in Docker: `reverse_proxy 127.0.0.1:8080` and still `TRUSTED_PROXIES=private`. Docker's port forwarding hands the app connections from the host via the Docker network's gateway address (e.g. `172.19.0.1`), not `127.0.0.1`, so `loopback` does not match (seen in the test with nginx on the host). ## nginx nginx 1.27.3 or later in a container on the compose network, for example `nginx:1.30-alpine` with this file as `/etc/nginx/conf.d/default.conf` and the certificates mounted read-only (`/etc/letsencrypt:/etc/letsencrypt:ro` from certbot on the host): ```nginx upstream crowhr { zone crowhr 64k; server app:8080 resolve; # looked up again, so nginx follows a recreated app container resolver 127.0.0.11 valid=10s; # Docker's DNS } server { listen 443 ssl; http2 on; server_name hr.example.sg; ssl_certificate /etc/letsencrypt/live/hr.example.sg/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/hr.example.sg/privkey.pem; client_max_body_size 25m; # uploads (receipts, documents) location / { proxy_pass http://crowhr; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $remote_addr; # replace, don't append a client's value proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Host $host; proxy_read_timeout 120s; } } server { listen 80; server_name hr.example.sg; return 301 https://$host$request_uri; } ``` `.env`: `PUBLIC_URL=https://hr.example.sg`, `TRUSTED_PROXIES=private`, `BIND_ADDRESS=127.0.0.1`. Avoid a plain `proxy_pass http://app:8080;`. nginx then looks `app` up only once, at start. When an upgrade recreates the app container with a new address, nginx answers 502 until it is restarted. The `upstream` above looks the name up again within 10 seconds. nginx installed on the host: in the `upstream`, replace the `server` and `resolver` lines with `server 127.0.0.1:8080;`. Keep `TRUSTED_PROXIES=private`, because the app sees connections from the host as coming from the Docker network's gateway, not `127.0.0.1`. nginx before 1.25.1 (check with `nginx -v`) does not know `http2 on;`; write `listen 443 ssl http2;` instead. ## Traefik Add labels to the `app` service in `docker-compose.override.yml`, with Traefik on the same Docker network: ```yaml services: app: labels: - traefik.enable=true - traefik.http.routers.crowhr.rule=Host(`hr.example.sg`) - traefik.http.routers.crowhr.entrypoints=websecure - traefik.http.routers.crowhr.tls.certresolver=letsencrypt - traefik.http.services.crowhr.loadbalancer.server.port=8080 ``` The labels assume Traefik v3 with its Docker provider (`exposedByDefault=false`), an entrypoint named `websecure` on port 443 and a certificate resolver named `letsencrypt`. Rename them to match your Traefik. If Traefik logs `Router uses a nonexistent certificate resolver`, the name does not match, and Traefik serves its own self-signed certificate instead. `.env`: `PUBLIC_URL=https://hr.example.sg`, `TRUSTED_PROXIES=private`, and stop publishing the app port to the world with `BIND_ADDRESS=127.0.0.1`. Traefik sets `X-Forwarded-*` itself; configure its entrypoint `forwardedHeaders.trustedIPs` only for proxies in front of Traefik. ## Cloudflare Tunnel No open ports needed. Add `cloudflared` to `docker-compose.override.yml`: ```yaml services: cloudflared: image: cloudflare/cloudflared:latest command: tunnel --no-autoupdate run environment: TUNNEL_TOKEN: ${CLOUDFLARE_TUNNEL_TOKEN} restart: unless-stopped ``` In the Cloudflare Zero Trust dashboard, route the public hostname `hr.example.sg` to `http://app:8080`. `.env`: ```sh PUBLIC_URL=https://hr.example.sg TRUSTED_PROXIES=private BIND_ADDRESS=127.0.0.1 CLOUDFLARE_TUNNEL_TOKEN=… ``` cloudflared sends `X-Forwarded-For` with the visitor's address (Cloudflare also sends `CF-Connecting-IP`, which Crow HR does not read) and `X-Forwarded-Proto: https`. Using Singpass login? Cloudflare's **Bot Fight Mode** challenges Singpass's servers when they fetch your JWKS URL, and Singpass then refuses the sign-in. See [Singpass login](https://hr.crow.sg/docs/admin/sso/singpass/), step 2. ## Checking it 1. Open `PUBLIC_URL`, sign in as an owner, go to **Settings → System → This request**: "Your IP as seen" should be your own public or LAN address, scheme `https` behind TLS, and the badge "Trusted proxy". 2. `docker compose exec app crowhr doctor` shows the last request as the app saw it and suggests a `TRUSTED_PROXIES` value when a proxy's headers were ignored. --- # Backups and restore > What a Crow HR backup contains, how scheduled and manual backups work, how to copy them off the server and how to restore. Source: https://hr.crow.sg/docs/self-hosting/backups/ An automated test runs the whole cycle on every change: backup, delete everything (`docker compose down -v`), fresh install, restore, then check that the organisation, uploaded files, encryption key and owner sign-in are back. ## What a backup contains One file in the `backups` volume, `crowhr-backup-[-scheduled|-pre-migrate].tar.gz` (`.tar.gz.age` when encrypted): - `manifest.json`: app version, database schema version, time, SHA-256 of every part; - `db.dump`: `pg_dump --format=custom` of the whole database; - `files/…`: every uploaded file; - `secrets/crowhr.key`: the encryption key. **The key is included by default**, because a backup without it cannot restore NRIC, bank or SSO data, and losing the key is far more common than losing a backup to theft. That means an unencrypted backup file is as sensitive as the live system. Set `BACKUP_PASSPHRASE` in `.env` (at least 12 characters, kept outside the server). Then every archive is encrypted with [age](https://age-encryption.org); you can also decrypt it with the standard tool: `age -d backup.tar.gz.age > backup.tar.gz`. Scheduled backups refuse to run until a passphrase is set. A manual backup without a passphrase still works, with a warning. ## Automatic backups **Scheduled backups need `BACKUP_PASSPHRASE`.** Set it in `.env` (at least 12 characters), keep a copy outside this server and run `docker compose up -d`. Without it, each scheduled backup is recorded as failed and nothing is written. Daily at `BACKUP_TIME` (default 02:00 Singapore time), keeping the newest `BACKUP_KEEP` (default 14). A backup is also taken before any database upgrade (`BACKUP_BEFORE_MIGRATE`). Results, sizes and failures appear in Settings → System; owners see a warning on Home when the last successful backup is more than 48 hours old, and when scheduled backups are disabled because `BACKUP_PASSPHRASE` is not set (both, if both apply). ## Manual backup ```sh docker compose exec app crowhr backup docker compose exec app crowhr backup --passphrase-file /run/secrets/pp # or --passphrase '…' (visible in `ps`) docker compose exec app crowhr backup --without-key # key not included: keep it separately! ``` ## Copy backups off the machine The backups volume sits on the same disk as the data. Copy archives elsewhere regularly: ```sh docker compose cp app:/backups/crowhr-backup-20261031T020000Z-scheduled.tar.gz.age ./ ``` Nightly copy with rclone (any S3/B2/Drive remote, configured with `rclone config`), from the host's crontab: ```sh 30 3 * * * docker run --rm -v crowhr_backups:/backups:ro -v $HOME/.config/rclone:/config/rclone rclone/rclone copy /backups remote:crowhr-backups ``` (`crowhr_backups` is `_backups`; check with `docker volume ls`. The rclone line is an example and is not tested.) ## Restore Restore replaces the database, uploaded files and key with the backup. It first extracts and verifies every checksum, and refuses archives made by a newer Crow HR, before changing anything. The database is restored in a single transaction: if it fails, nothing changed. During the restore the site answers "Restoring backup" (503) and background jobs pause; afterwards the app restarts itself. Onto a new machine (or after `docker compose down -v`): ```sh cp .env.example .env # set PUBLIC_URL (and BACKUP_PASSPHRASE if the backup is encrypted) docker compose up -d docker compose exec -T app sh -c 'cat > /backups/restore.tar.gz' < crowhr-backup-….tar.gz docker compose exec app crowhr restore /backups/restore.tar.gz docker compose ps # app restarts and becomes healthy ``` (Copy the file in with `exec … cat`, not `docker compose cp`: `cp` creates it owned by root, which the app user cannot read.) Over an install that already has data, add `--force`; without it the restore stops and explains. Encrypted archives need `BACKUP_PASSPHRASE` in `.env` or `--passphrase-file `. ## Lost the data volume (key gone, database intact) The app refuses to start rather than generate a new key over existing encrypted data: ``` CROWHR_SECRET_KEY does not match this database. Restore the key from your backup (crowhr restore --secrets-only ) ``` Recover just the key from any backup of this install: ```sh docker compose run --rm app crowhr restore --secrets-only /backups/ docker compose up -d ``` Uploaded files that were only in the lost volume come back with a full restore of the latest backup. --- # Upgrades > Upgrade Crow HR with docker compose pull, what happens during database migrations, image tags and downgrades. Source: https://hr.crow.sg/docs/self-hosting/upgrades/ ## Upgrading ```sh docker compose pull docker compose up -d docker compose logs -f app # watch the migrations, Ctrl-C when "Crow HR is ready" ``` While the database is being upgraded the site shows "Crow HR is starting" and `/api/health` answers 503 `starting`. A few seconds of downtime is normal. What happens on start: 1. The app waits for the database (up to `DB_WAIT_SECONDS`). 2. It takes a Postgres advisory lock, so two app containers never migrate at once (a second one waits up to `MIGRATE_LOCK_TIMEOUT_SECONDS`). 3. If migrations are pending and the database has data, it writes a backup first (`…-pre-migrate.tar.gz`). 4. Each migration runs in its own transaction. If one fails, the app stops with the migration's name, the database error and the path of that backup; earlier migrations stay applied and nothing of the failed one does. Go back to the previous image tag and report the error. Skipping versions is fine within a major version: an install on 1.1.0 can pull 1.6.2 directly, and every migration from 1.2 to 1.6 is applied in order on the first start. ## Image tags Images are published to `ghcr.io/crow-tech-pte-ltd/crowhr` for amd64 and arm64, tagged `:`, `:.`, `:..` and `latest`. `docker-compose.yml` references `:1`, so `pull` brings the newest 1.x. A major upgrade (1 → 2) means editing the tag in `docker-compose.yml` and reading the [release notes](https://github.com/Crow-Tech-Pte-Ltd/CrowHR/releases), which mark any manual step. To stay on one release, set `CROWHR_IMAGE=ghcr.io/crow-tech-pte-ltd/crowhr:1.1.0` (for example) in `.env`. If you run your own build (`CROWHR_IMAGE=crowhr:local`, see [build the image yourself](https://hr.crow.sg/docs/self-hosting/install/#build-the-image-yourself)), upgrade with `git pull`, `docker build -t crowhr:local .` and `docker compose up -d`. Each published image carries a software bill of materials (SBOM) and a signed build provenance attestation. To check that an image was built from this repository by its release workflow: ```sh gh attestation verify oci://ghcr.io/crow-tech-pte-ltd/crowhr:1 --owner Crow-Tech-Pte-Ltd ``` ## Downgrades Starting an older image against a database upgraded by a newer one is refused: ``` This database was upgraded by Crow HR 1.5. Run 1.5 or newer ``` To really go back, restore a backup taken before the upgrade (the pre-migrate backup is made for this): see [backups and restore](https://hr.crow.sg/docs/self-hosting/backups/). ## Multi-arch builds (amd64 and arm64) Published images are built natively for amd64 and arm64, and each is started against PostgreSQL 17 before it is published. The Dockerfile builds on both architectures; a local multi-arch build uses QEMU: ```sh docker buildx build --platform linux/amd64,linux/arm64 -t crowhr:local . ``` Building arm64 under QEMU is slow (several minutes). --- # crowhr CLI reference > Every command of the crowhr server administration CLI, run inside the app container with docker compose exec. Source: https://hr.crow.sg/docs/self-hosting/cli/ The image ships a `crowhr` command for server administration. Run it inside the app container: ```sh docker compose exec app crowhr docker compose exec app crowhr help # the same list, from the installed version docker compose exec app crowhr --version ``` Commands that change data are recorded in the audit log as CLI actions. Use `docker compose run --rm app crowhr …` when the app container is not running (for example to restore the key before first start). :::note[Kept in sync with the code] `apps/docs/tests/cli.test.ts` fails when the CLI gains a command that is not documented on this page. ::: ## Backups ### backup ```sh crowhr backup [--passphrase-file | --passphrase ] [--without-key] ``` Writes a backup archive (database dump, uploaded files and the encryption key) to the backups directory (`/backups`). It is encrypted when `BACKUP_PASSPHRASE` is set or a passphrase option is given; otherwise it prints a warning. `--passphrase` is visible in `ps`, so prefer `--passphrase-file`. `--without-key` leaves the encryption key out: keep the key somewhere else, or the backup cannot restore NRIC, bank and SSO data. See [backups and restore](https://hr.crow.sg/docs/self-hosting/backups/). ### restore ```sh crowhr restore [--force] [--secrets-only] [--passphrase-file ] [--no-restart] ``` Restores a backup archive. It verifies every checksum and refuses archives made by a newer Crow HR before changing anything, then restores the database in one transaction. - `--force` is required when the database already has data. - `--secrets-only` restores just the encryption key, after losing the data volume while the database survived. - `--passphrase-file` reads the passphrase for an encrypted archive (otherwise `BACKUP_PASSPHRASE` is used). - `--no-restart` skips restarting the app afterwards. Inside the container the app restarts itself; elsewhere the command tells you to restart it. ## Database ### migrate ```sh crowhr migrate ``` Applies pending database migrations under the same advisory lock the app uses on start. You only need it with `MIGRATE_ON_START=false`. ### init-secrets ```sh crowhr init-secrets ``` Creates the random database password in the shared secrets volume (`DATABASE_PASSWORD_FILE`). The compose `init` service runs it on every `up`; it does nothing when the password already exists. ## Setup and health ### setup-code ```sh crowhr setup-code ``` Prints a new first-run setup code; the previous one stops working. After setup is complete it says so and prints the sign-in address. ### doctor ```sh crowhr doctor ``` Checks the configuration, database connection, migrations, encryption key, disk space, backups, clock skew and the proxy headers of the last request the app saw, and says what to fix. It suggests a `TRUSTED_PROXIES` value when a proxy's headers were ignored. ## Owner recovery (break-glass) ### create-reset-link ```sh crowhr create-reset-link --email [--org ] ``` Prints a one-time password reset link for an owner, valid for 60 minutes. Add `--org` when the install has several organisations. ### reset-owner-mfa ```sh crowhr reset-owner-mfa --email [--org ] ``` Clears the owner's two-step verification and prints a reset link. The owner sets a new password and enrols again. ### admin ```sh crowhr admin verify-audit [--org ] crowhr admin reset-owner-password --org --email [--reset-mfa] ``` `verify-audit` checks that the audit log's SHA-256 hash chain is intact and reports the first broken link: an altered event or a gap in the sequence. It does not detect events removed from the end of the log. `reset-owner-password` is the same as `create-reset-link` (with `--reset-mfa`, the same as `reset-owner-mfa`). ## Demo companies ### demo-companies purge ```sh crowhr demo-companies purge [--expired] ``` Only on a public demo server ([`DEMO_COMPANIES`](https://hr.crow.sg/docs/self-hosting/configuration/#demo-companies)). Deletes every demo company with everything in it, including the ones visitors are still using; with `--expired`, only those past their expiry (the scheduler does this every minute anyway). Use it after turning `DEMO_COMPANIES` off. Real organisations are never touched: the database refuses to delete their audit events, and an organisation can't be made a demo company after it is created. ### help and version ```sh crowhr help # also --help, -h crowhr version # also --version ``` --- # Troubleshooting the server > Fixes for Crow HR startup errors, lost setup codes, locked-out owners, proxy problems, backups and disk space. Source: https://hr.crow.sg/docs/self-hosting/troubleshooting/ For problems inside the app (sign-in, SSO, payroll), see [troubleshooting](https://hr.crow.sg/docs/help/troubleshooting/). For the server, start with: ```sh docker compose ps # is everything up and healthy? docker compose logs --tail=100 app # the app says what is wrong and what to run docker compose exec app crowhr doctor # configuration, database, key, disk, clock, proxy headers ``` ## The app exits right after starting | Log says | Fix | | --- | --- | | `Crow HR cannot start: 1 setting needs fixing. - PUBLIC_URL …` | Edit `.env` as the message says (every message names the variable and gives an example), then `docker compose up -d`. Exit code 78. | | `PUBLIC_URL is not set` | `cp .env.example .env` and set `PUBLIC_URL`. | | `Cannot reach the database after 60 s` | `docker compose ps` and `docker compose logs db`. With an external database, check `DATABASE_URL`. | | `DATABASE_PASSWORD_FILE points to … cannot be read` | The `init` service did not run: use `docker compose up -d` (all services), not `docker compose up app`. | | `CROWHR_SECRET_KEY does not match this database` | The data volume (key file) was lost or `CROWHR_SECRET_KEY` changed. Put the original value back, or `docker compose run --rm app crowhr restore --secrets-only /backups/`. Never delete the database to "fix" this. | | `This database was upgraded by Crow HR X. Run X or newer` | You started an older image. Set the newer tag again in `docker-compose.yml`. | | `Database migration 0042_… failed` | Your data is intact. Go back to the previous image tag; a pre-migration backup path is in the message. Report the error. | | `Could not take the backup that runs before database migrations` | Usually disk space (`docker compose exec app df -h /backups`). Free space, or set `BACKUP_BEFORE_MIGRATE=false` once. | | `Another Crow HR instance has held the migration lock` | Two app containers on one database. `docker compose down`, then `docker compose up -d`. | | `Port 8080 is already in use` | Change `HTTP_PORT` in `.env` (the host side). | ## I lost the setup code `docker compose logs app | grep -A3 'SETUP CODE'`, or print a new one: `docker compose exec app crowhr setup-code`. The code changes on every restart. After five wrong codes your address is blocked for 15 minutes. ## The owner is locked out Break-glass, from the server (audited as a CLI action): ```sh docker compose exec app crowhr create-reset-link --email owner@example.sg # one-time password reset link, 60 minutes docker compose exec app crowhr reset-owner-mfa --email owner@example.sg # also clears two-step verification ``` Add `--org ` when the install has several organisations. ## Behind a proxy, everyone has the same IP / sign-in limits hit the whole office The app does not trust your proxy. Logs show `Ignoring X-Forwarded-* headers from `. Set `TRUSTED_PROXIES=` (or `private`) in `.env`, `docker compose up -d`, and check Settings → System → This request. See [reverse proxy](https://hr.crow.sg/docs/self-hosting/reverse-proxy/). ## Signed out immediately / cookies not kept `PUBLIC_URL` must match the address in the browser exactly (scheme, host, port). An `https` `PUBLIC_URL` sets `Secure` cookies, which browsers drop over plain `http`. ## "Restoring backup" or "A backup was restored" does not go away A restore was interrupted. `docker compose restart app` clears the flag; the database restore itself is all-or-nothing. ## Backups fail Settings → System shows the last error. Common causes: disk full (`docker compose exec app df -h /backups`), an external PostgreSQL newer than 17 (the bundled `pg_dump` is 17), or a wrong `BACKUP_PASSPHRASE` length (at least 12 characters). ## Disk is filling up Container logs are capped at 3 × 10 MB per container. Backups are capped by `BACKUP_KEEP`. Old images: `docker image prune`. --- # Setup wizard > Create your organisation and its owner on a fresh Crow HR server with the one-time setup code. Source: https://hr.crow.sg/docs/admin/setup-wizard/ A new server has no organisation and nobody who can sign in. The setup wizard creates both. Until it is done, every page redirects to `/setup`, and the API answers `409 setup_required`. ## Before you start You need the one-time setup code from the server log: ```sh docker compose logs app | grep -A3 'SETUP CODE' ``` The code is 16 characters from an alphabet without look-alikes (no `0`/`O`, `1`/`I`), shown in four groups such as `ACDE-FGHJ-KMNP-QRTU`. It changes on every restart. `docker compose exec app crowhr setup-code` prints a fresh one and invalidates the old. Only a hash of the code is stored. ## The three steps 1. **Setup code.** Paste the code from the log. Five wrong codes from one IP address block that address for 15 minutes. 2. **Company's registered name**, as on ACRA BizFile (for example `Kampong Kopi Pte. Ltd.`). The UEN, CPF submission number and address come later in [company and structure](https://hr.crow.sg/docs/admin/company-and-structure/). 3. **The owner account**: your name, work email and a password. Passwords are 12 to 128 characters, must not be on the common-password list and must not equal the email. There are no character-class rules: a few random words work well. The organisation and the owner are created in one transaction, the code stops working, `setup.completed` is written to the audit log and you are signed in. `/setup` then answers 404. ## Protect the owner account The last screen offers two-step verification. Owners, HR admins and payroll admins must enrol by default ([MFA policy](https://hr.crow.sg/docs/admin/mfa/)), with a 7-day grace period, so it is easiest to do it now with an authenticator app. You can also choose **Later, go to Home**. ## After setup Home shows **Finish setting up** until the company profile, at least one department, the default work schedule and at least one employee exist. Each step links to the screen that completes it, and its tick comes from the data, not from a checkbox. Recommended order: 1. [Company profile](https://hr.crow.sg/docs/admin/company-and-structure/#company-profile): UEN, CSN and address (payroll is blocked without them). 2. [Structure and work schedules](https://hr.crow.sg/docs/admin/company-and-structure/#structure). 3. [Invite your HR and payroll admins](https://hr.crow.sg/docs/admin/members-and-roles/). 4. [Add](https://hr.crow.sg/docs/people/adding-employees/) or [import](https://hr.crow.sg/docs/people/importing/) employees. 5. [Payroll settings](https://hr.crow.sg/docs/payroll/settings/). For a scripted install, set `SETUP_CODE` in `.env` to a fixed code (see the [configuration reference](https://hr.crow.sg/docs/self-hosting/configuration/#other)). --- # Company and structure > Set the company profile (UEN, CSN, address), departments, teams, locations, cost centres and work schedules in Crow HR. Source: https://hr.crow.sg/docs/admin/company-and-structure/ Owners and HR admins maintain these in **Settings → Company** and **Settings → Structure**. Everyone else can read them. ## Company profile One Crow HR organisation is one legal entity, with one UEN and one CSN. A group of companies is set up as separate organisations; one person can belong to several and switch between them. | Field | Rules | | --- | --- | | Legal name | Required. Printed on payslips as the employer's full name, so payslips cannot be released without it. | | Trading name | Optional. | | UEN | Required. Must match one of ACRA's three formats: 8 digits and a letter (businesses), a 4-digit year, 5 digits and a letter (local companies), or `T`/`S`, 2 digits, a 2-character entity type, 4 digits and a letter (other entities). | | CPF submission number (CSN) | Your UEN, a 3-letter payment type and a 2-digit serial, for example `201912345KPTE01`. Payment types are `PTE` (staff), `AMS`, `VCT` and `MSE`. It must start with the UEN above. | | Registered address | Block or house number, street, unit, building and a 6-digit postal code. | | Logo | **Upload logo** under the address. PNG only (type detected from content), at most 1 MB; export SVG artwork as PNG first. Printed on letters generated from templates. | Payroll cannot be submitted until the profile has a UEN, a CSN and an address. Time zone (Asia/Singapore) and currency (SGD) are fixed. ## Structure **Settings → Structure** holds four flat lists: - **Departments** - **Teams**, each optionally inside one department - **Locations**, with an address and postal code - **Cost centres**, with a unique code and a name Names are unique among active entries of the same list. Entries are archived, never deleted, so history stays readable. An entry that a current employee uses cannot be archived: the error (`409 in_use`) says how many employees use it and links to that filtered list. ## Work schedules Payroll pro-rates salary from the employee's working days, and leave and attendance count days and measure lateness and overtime from it, so create the default schedule early. - A **fixed** schedule sets each weekday to *working* (with contracted hours), *half* (working, fewer hours), *off* or *rest*. It must have exactly one rest day. Weekly contracted hours are the sum of the days. - A **shift** schedule takes its days from published [rosters](https://hr.crow.sg/docs/scheduling/scheduling/). For an incomplete month, payroll needs these employees' scheduled days and days worked: they come from published rosters and attendance when available, otherwise HR enters them on the run. Crow HR does not guess a week. One schedule is the default for new employees. Editing a schedule creates a new effective-dated version, so earlier months keep the schedule that applied then. --- # Members and roles > Invite people to Crow HR, grant owner, HR admin and payroll admin roles, suspend members and handle former employees. Source: https://hr.crow.sg/docs/admin/members-and-roles/ A **member** is a person who can sign in to your organisation. Most members are linked to an employee record; some (an external accountant, for example) are not. Manage them in **Settings → Members**. ## Roles Roles combine: one person can be both HR admin and payroll admin. | Role | How you get it | In short | | --- | --- | --- | | Owner | Granted by an owner | Everything, including security settings, SSO and approving payroll runs. At least one active owner must always exist. | | HR admin | Granted by an owner | Employee records, structure, lifecycle, approval policies. No compensation, bank details or payroll. | | Payroll admin | Granted by an owner | Payroll runs, compensation, bank details, payslips and statutory files. | | Manager | Automatic, while the member's employee record has at least one active direct report | Their team (direct and indirect reports), and requests routed to them. | | Employee | Automatic, when the member is linked to an employee record | Their own records and payslips. | The full permission matrix, generated from the code, is on [roles and permissions](https://hr.crow.sg/docs/roles-and-permissions/). Rules worth knowing: - Only owners grant or revoke owner, HR admin and payroll admin. HR admins may invite members with no assigned roles only. - Revoking the last owner role, or suspending the last owner, fails with `409 last_owner`. - Nobody changes their own compensation or bank details directly, even an owner or payroll admin: those go through a change request decided by someone else. When nobody else is eligible, an owner may approve their own request and the decision is marked self-approved. - Granting or revoking roles needs a recent sign-in (within 10 minutes). If yours is older, Crow HR asks for your password (and code) again. ## Inviting people Hiring an employee in People sends their invitation automatically (see [adding employees](https://hr.crow.sg/docs/people/adding-employees/)). To invite someone without an employee record, use **Invite** in Settings → Members. - An invitation link is valid for 7 days. Resending replaces the link; revoking makes it unusable. - The invitee sets a password or uses any enabled SSO method. An invitation link also binds a first SSO sign-in to that member, which is how Singpass identities are linked. - **Without email configured**, the inviter gets the link to copy and send themselves. Invitations from a CSV import are sent after you confirm the import; without SMTP their links are not shown there, so resend them from Settings → Members. - Inviting an email that already has an active membership, or linking a second live account to the same employee, fails with `409 conflict`. Former memberships do not prevent rehiring. Only owners may link an invitation to an employee who holds roles or manages people. Existing accounts with two-step verification must enter their code to accept. ## Member status | Status | Meaning | | --- | --- | | Invited | Invitation sent, not accepted yet. | | Active | Can sign in. | | Suspended | Cannot sign in; their sessions are revoked. | | Former | The employee's last working day has passed. The membership becomes former the day after, automatically, and keeps read-only access to their own released payslips. | Suspending a member, or their membership becoming former, also ends any out-of-office cover to or from them and passes their open approval tasks to other eligible approvers ([approvals](https://hr.crow.sg/docs/approvals/approvals/#when-a-step-has-nobody)). Owners can clear lockouts, reset two-step verification and sign members out everywhere (also removing their SSO links in this organisation). Only an owner, after re-authentication within 10 minutes, may create a password reset link. The target must have no assigned roles and no memberships in other organisations, because passwords are shared across organisations. With SMTP the affected member receives the link by email; otherwise the owner gets a copyable link, valid 60 minutes. The action is audited. ## Audit log Every sign-in, role change, configuration change and change to employee or payroll data is recorded in **Settings → Audit log**, with actor, time, IP address and a field diff (sensitive fields record only that they changed). The log is append-only, with each event linked to the previous one by a SHA-256 hash chain that `crowhr admin verify-audit` checks; it is filterable and exportable to CSV. - Owners see all events. - HR admins see everything except security settings, SSO configuration and payroll events. - Payroll admins see payroll, compensation and bank events. --- # Sign-in methods > Choose how people sign in to Crow HR - email and password, Google Workspace, Microsoft Entra ID, generic OpenID Connect or Singpass - and how SSO accounts are linked. Source: https://hr.crow.sg/docs/admin/sign-in-methods/ Owners choose the sign-in methods in **Settings → Security**. Each organisation has its own sign-in page (`/sign-in/`; plain `/sign-in` goes straight there when the server has only one organisation), and that page shows only the methods that are switched on **and** fully configured. It never reveals whether an email address belongs to a member. ![Settings → Security with password, Microsoft, Google, Singpass and Okta methods, the two-step verification policy and session timeouts (fictional company)](../../../assets/screens/settings-security.webp) ## The methods | Method | Notes | Guide | | --- | --- | --- | | Email and password | Always available out of the box. Optional two-step verification (TOTP), required for privileged roles by default. | [Two-step verification](https://hr.crow.sg/docs/admin/mfa/) | | Google Workspace | OpenID Connect with Google; can be restricted to your Workspace domains. | [Google Workspace](https://hr.crow.sg/docs/admin/sso/google-workspace/) | | Microsoft Entra ID | OpenID Connect restricted to one tenant. | [Microsoft Entra ID](https://hr.crow.sg/docs/admin/sso/microsoft-entra-id/) | | OpenID Connect | Any provider with discovery: Okta, Keycloak, Authentik and others. | [Generic OIDC](https://hr.crow.sg/docs/admin/sso/generic-oidc/) | | Singpass | Needs your company to be onboarded as a Singpass relying party. Tested against Singpass staging; not against production yet. | [Singpass](https://hr.crow.sg/docs/admin/sso/singpass/) | All SSO methods use one OpenID Connect implementation (authorisation code flow with PKCE, `state` and `nonce`), with provider presets. Client secrets and private keys are encrypted at rest and never shown again after saving; the API only says whether one is set. ## Adding an SSO provider 1. In Settings → Security choose **Add a method** and the provider. The dialog lists where to find each value at the provider. 2. Fill in the client ID and secret (and tenant, domains or issuer, depending on the provider) and **Save**. Crow HR fetches the provider's discovery document and refuses to save with a readable error if it cannot. Saving needs a recent sign-in. 3. Copy the **redirect URI** shown after saving into the provider's app registration. It has the form `/api/v1/auth/oidc//callback`, so `PUBLIC_URL` must already be the final address. 4. Use **Test sign-in**. A provider is saved switched off; turn it on after a successful test. If a sign-in fails, the person sees a generic "Sign-in with … failed" message and the exact reason is recorded as `auth.sso_failed` in the audit log. ## How SSO accounts are linked Crow HR has no open self-signup. An SSO sign-in works only for an identity linked to an active member of the organisation. On the first sign-in an identity is linked when: - the provider asserts a **verified email** (`email_verified: true`, or `xms_edov: true` from your configured Entra tenant) that equals the email of an existing active or invited member; or - the sign-in started from that member's **invitation link**. After that the identity is matched by its issuer and subject, not by email. Singpass identities are never linked by email or NRIC: only through an invitation or by a signed-in member linking it in **My sessions → Linked sign-in methods**, where members can also link other providers and unlink an identity unless it is their only way to sign in. Linking and unlinking are audit-logged and send the member a [security notice](https://hr.crow.sg/docs/approvals/notifications/#security-notices). Linking a method and testing a provider need a sign-in within the last 10 minutes. Someone without a membership sees "Your account has not been set up in (organisation). Ask your HR team for an invitation". ### Creating accounts on first sign-in (JIT) Off by default and not available for Singpass. When you switch on **Create accounts on first sign-in** for a provider, anyone with a verified email in that provider's allowed domains who has no membership gets one as a plain member with no role and no employee record. Emails outside the allowed domains are refused as if JIT were off. HR admins (or owners, when there are none) get a security notice for each one, and the `member.jit_provisioned` audit event records it; link such members to an employee record or remove them in Settings → Members. ## Turning off password sign-in Once at least one SSO provider is switched on and has had a successful test sign-in, you can switch off email and password for staff. Members other than owners then get `password_sign_in_disabled` with the names of the SSO methods to use. **Owners can always sign in with their password** (break-glass, still with two-step verification), and that sign-in is audited as `auth.break_glass_sign_in`. ## Sessions Settings → Security also sets how long people stay signed in: | Setting | Default | Range | | --- | --- | --- | | Sign out after inactivity | 30 minutes | 15 to 240 minutes | | Always sign out after | 12 hours | 1 to 24 hours | | Mobile app: sign out after unused | 30 days | 1 to 90 days ([mobile apps](https://hr.crow.sg/docs/mobile-apps/)) | People see and revoke their own sessions in **My sessions**. **Sign out everywhere** removes all linked SSO identities in that organisation, including the current method; the current session stays signed in. A password reset removes identities across all organisations. Verified-email providers can link again at the next SSO sign-in; other identities need a new invitation or a fresh profile link. Changing or resetting a password and suspending a member revoke sessions too. Sensitive actions (changing the password, two-step verification or security settings, SSO configuration, role grants, revealing an NRIC/FIN or bank number, exports with sensitive fields) need a sign-in within the last 10 minutes. ## Changing your sign-in email Everyone changes their own sign-in email in the user menu under **Sign-in and devices → Sign-in email** (it needs a sign-in within the last 10 minutes). Crow HR emails a link to the new address, valid for 24 hours; the change happens when it is opened and confirmed, and both the old and the new address are told. Until then the old address keeps working, and a newer request or **Cancel the change** ends the old link. One person has one sign-in email for every organisation they belong to; the work email on the employee record doesn't change. A server without email (no SMTP) can't verify the new address, so it doesn't offer the change: an unverified address could claim someone else's, and invitations, SSO linking and password resets all trust it. Set up SMTP ([email configuration](https://hr.crow.sg/docs/self-hosting/configuration/#email)) to allow it. When `PUBLIC_URL` is plain `http`, Settings → Security warns "Not using HTTPS": session cookies are not protected in transit. Put Crow HR behind HTTPS ([reverse proxy](https://hr.crow.sg/docs/self-hosting/reverse-proxy/)) before using it over the internet. --- # Two-step verification (MFA) > How TOTP two-step verification, recovery codes and the MFA policy for privileged roles work in Crow HR. Source: https://hr.crow.sg/docs/admin/mfa/ Crow HR supports two-step verification with an authenticator app (TOTP) for password and SSO sign-in. ## Enrolling Each person enrols from **My sessions** (the banner's **Set up now** goes there). Scan the QR code with an authenticator app (any app that supports standard TOTP: 6 digits, 30-second codes) and enter a code to finish. The QR code is drawn in your browser; nothing is sent to a third party. Enrolment shows **10 recovery codes** once. Each works once, in place of an authenticator code. Store them somewhere safe. Regenerating codes invalidates the old set. After enrolment, password sign-in and accepting an invitation to another organisation require a code. SSO sign-in also requires it unless the identity provider explicitly asserts MFA (`amr` contains `mfa`). A code that was already used is refused. Five wrong codes (authenticator or recovery) within 15 minutes pause code entry for the account for 15 minutes, counted across sign-in, re-authentication and invitation acceptance, so starting a new sign-in does not reset the count. ## MFA policy for privileged roles In **Settings → Security → Two-step verification policy**, owners choose which roles must use two-step verification for password and SSO sign-in. By default: **owner, HR admin and payroll admin**. - A member who gets such a role has **7 days** from the role grant to enrol. During that time every page shows a banner with the deadline. - After 7 days without enrolment, they can only enrol or sign out until they do (`403 mfa_enrolment_required` for everything else). - The policy also covers **SSO and mobile app sessions**. An SSO session satisfies it when the identity provider's ID token explicitly asserts MFA (`amr` contains `mfa`; [RFC 8176](https://www.rfc-editor.org/rfc/rfc8176.html)); a single method such as `otp` is not enough. Google does not send this claim, so Google sign-ins never satisfy it. Without the assertion, the member enrols a Crow HR authenticator. While someone is blocked, the mobile app can't sign them in; they enrol in the browser first. ## When someone loses their device - They can sign in with a recovery code and enrol again. - An owner can reset another member's two-step verification in **Settings → Members**. The reset is audited. - If the only owner is locked out, the server operator runs `crowhr reset-owner-mfa --email ` (see the [CLI reference](https://hr.crow.sg/docs/self-hosting/cli/#reset-owner-mfa)). ## Security notices Turning two-step verification on or off, an owner resetting it, a recovery code being used and a pause after wrong codes each send you a [security notice](https://hr.crow.sg/docs/approvals/notifications/#security-notices) in the app, and by email when SMTP is set. They are also in the audit log. ## Not available Only TOTP is supported. There are no passkeys, WebAuthn security keys or SMS codes. --- # Google Workspace sign-in > Step-by-step setup of Google Workspace single sign-on (OpenID Connect) for Crow HR, with domain restriction. Source: https://hr.crow.sg/docs/admin/sso/google-workspace/ Lets staff sign in with their Google Workspace account. You need an owner account in Crow HR, admin access to a Google Cloud project for your Workspace, and `PUBLIC_URL` set to its final address (the redirect URI is built from it). ## What Crow HR does - OpenID Connect against `https://accounts.google.com` with scopes `openid email profile`, authorisation code flow with PKCE. - With **allowed Workspace domains** set, only accounts whose Google `hd` (hosted domain) claim is in the list can sign in; personal Gmail accounts have no `hd` and are refused. With exactly one domain, Google's account chooser is also limited to it. - A first sign-in links to the member with the same verified email, or to the member whose invitation link was used. ## Set it up 1. **Google Cloud Console**: choose or create a project for your Workspace. If Google asks you to configure the OAuth consent screen first, choose the **Internal** user type so only your Workspace's users can use it. 2. Open **APIs & Services → Credentials → Create credentials → OAuth client ID**, application type **Web application**. Leave the redirect URIs empty for now. Copy the **client ID** and **client secret**. 3. **Crow HR**: in **Settings → Security** choose **Add a method → Google Workspace**. Paste the client ID and secret, and enter your Workspace domain(s) in **Allowed Workspace domains**, for example `kampongkopi.sg`. Leave **Create accounts on first sign-in** off unless you want [JIT accounts](https://hr.crow.sg/docs/admin/sign-in-methods/#creating-accounts-on-first-sign-in-jit). Save (you may be asked for your password again). 4. Copy the **Redirect URI** shown after saving. It looks like `https://hr.example.sg/api/v1/auth/oidc//callback`. 5. **Google Cloud Console**: edit the OAuth client and add that exact URI under **Authorised redirect URIs**. Save. Google can take a few minutes to apply it. 6. **Crow HR**: use **Test sign-in** on the Google row. When it succeeds, switch the method on. The sign-in page now shows the Google button. ## Check - Invite or hire someone with their Workspace email, then have them sign in with Google: they land on Home without setting a password. - Someone from another domain is refused; the audit log shows `auth.sso_failed` with reason `hd_mismatch`. - Enforce 2-Step Verification in the Workspace admin console. Google's ID tokens don't tell Crow HR whether it was used, so members in roles covered by Crow HR's [MFA policy](https://hr.crow.sg/docs/admin/mfa/) (owners, HR and payroll admins by default) also enrol a Crow HR authenticator and enter its code after signing in with Google. An owner can take roles out of the policy. ## Common errors | Symptom | Cause | | --- | --- | | Google says `redirect_uri_mismatch` | The URI in Google Cloud does not match the one Crow HR showed exactly (scheme, host, path). Check `PUBLIC_URL`. | | "Your account has not been set up" | No member with that email exists. Invite them first, or have them use their invitation link. | | Audit reason `hd_mismatch` | The account's domain is not in Allowed Workspace domains (or it is a personal Google account). | | Audit reason `email_not_verified` | Google did not assert a verified email; use the invitation link instead. | Crow HR's automated tests run this flow against a mock identity provider, not a live Google Workspace; the preset uses Google's published OpenID Connect discovery document. --- # Microsoft Entra ID sign-in > Step-by-step setup of Microsoft Entra ID (Azure AD) single sign-on for Crow HR, restricted to your tenant. Source: https://hr.crow.sg/docs/admin/sso/microsoft-entra-id/ Lets staff sign in with their Microsoft 365 / Entra ID work account. You need an owner account in Crow HR, rights to register applications in your Entra tenant, and `PUBLIC_URL` set to its final address. ## What Crow HR does - OpenID Connect against `https://login.microsoftonline.com//v2.0` with scopes `openid email profile`, authorisation code flow with PKCE. - **Single tenant only.** The tenant ID is required, multi-tenant values (`common`, `organizations`, `consumers`) are refused, and any token whose `tid` differs from your tenant is rejected (`tid_mismatch`). - A matching tenant does **not** verify the `email` claim. Automatic email linking requires `xms_edov: true`, the optional domain-verification claim ([Microsoft reference](https://docs.azure.cn/en-us/entra/identity-platform/optional-claims-reference)). Without it, use the invitation link for the first sign-in; later sign-ins match the already-linked issuer and subject. Configure the optional `email` and `xms_edov` ID-token claims if you want automatic linking. ## Set it up 1. **Microsoft Entra admin centre**: open **App registrations → New registration**. Name it (for example "Crow HR") and choose **Accounts in this organizational directory only (single tenant)**. Leave the redirect URI empty for now and register. 2. On the app's **Overview** page copy the **Directory (tenant) ID** and the **Application (client) ID**. 3. Under **Certificates & secrets → Client secrets**, create a secret and copy its **Value** (not the Secret ID). Note its expiry date: sign-in stops working when it expires, and you then paste a new secret into Crow HR. 4. **Crow HR**: in **Settings → Security** choose **Add a method → Microsoft Entra ID**. Paste the tenant ID, client ID and secret. Optionally add allowed email domains (used only to limit [JIT accounts](https://hr.crow.sg/docs/admin/sign-in-methods/#creating-accounts-on-first-sign-in-jit)). Save. 5. Copy the **Redirect URI** shown after saving (`https://hr.example.sg/api/v1/auth/oidc//callback`). 6. **Entra**: in the app registration open **Authentication → Add a platform → Web** and paste the redirect URI. Save. 7. **Crow HR**: use **Test sign-in**, then switch the method on. ## Check - A member whose email matches and whose token has `xms_edov: true` can link automatically; otherwise start from their invitation. - A personal Microsoft account or another tenant's account is refused (`tid_mismatch` in the audit log). - Enforce MFA with Entra (security defaults or Conditional Access). Crow HR also enforces its [MFA policy](https://hr.crow.sg/docs/admin/mfa/) unless the validated ID token explicitly asserts MFA. ## Common errors | Symptom | Cause | | --- | --- | | Microsoft error AADSTS50011 (redirect URI mismatch) | The Web platform redirect URI does not exactly match the one Crow HR showed. | | Sign-in worked, then stopped months later | The client secret expired. Create a new one and paste it in **Edit**. | | "Your account has not been set up" | No member with that email, or the token lacks a verified email (`xms_edov: true`). Use the invitation link. | Crow HR's automated tests run this flow against a mock identity provider, not a live Entra tenant. --- # OpenID Connect (Okta, Keycloak, Authentik) > Connect any OpenID Connect identity provider with discovery - Okta, Keycloak, Authentik and others - to Crow HR. Source: https://hr.crow.sg/docs/admin/sso/generic-oidc/ Any identity provider that publishes an OpenID Connect discovery document (`/.well-known/openid-configuration`) and supports the authorisation code flow can be used. It uses the same implementation as the Google and Microsoft presets, without their provider-specific checks. ## What your provider must support - Authorisation code flow with PKCE (S256) and `response_mode=query`. - Client authentication with a client secret. - Scopes `openid email profile`, and an `email` plus `email_verified: true` claim in the ID token if you want first sign-ins to link by email. Without a verified email, members link only through their invitation link. ## Set it up 1. **In your provider**, create an OpenID Connect **web application** (Okta: *App integration → OIDC → Web Application*; Keycloak: a *client* with client authentication on and the standard flow enabled; Authentik: an *OAuth2/OpenID Provider* with an *Application*). Note the **issuer URL**, **client ID** and **client secret**. Issuer examples: Keycloak `https://sso.example.sg/realms/acme`, Okta `https://example.okta.com` (or an authorisation server URL), Authentik `https://auth.example.sg/application/o/crow-hr/`. 2. **Crow HR**: in **Settings → Security** choose **Add a method → OpenID Connect**. Enter a **Button label** (shown as "Sign in with …", for example `Okta`), the issuer URL, client ID and secret. Optionally set allowed email domains for [JIT accounts](https://hr.crow.sg/docs/admin/sign-in-methods/#creating-accounts-on-first-sign-in-jit). Save: Crow HR fetches the discovery document and refuses to save if it is unreachable or its `issuer` does not match what you entered. 3. Copy the **Redirect URI** shown after saving and register it in the provider as the allowed redirect (Keycloak: *Valid redirect URIs*; Okta: *Sign-in redirect URIs*; Authentik: *Redirect URIs*). 4. Use **Test sign-in**, then switch the method on. ## Common errors | Symptom | Cause | | --- | --- | | Save fails: discovery document could not be fetched | The Crow HR server cannot reach `/.well-known/openid-configuration` (DNS, firewall, TLS certificate), or the issuer is mistyped. Crow HR fetches it from the server, not from your browser. | | Save fails: issuer does not match | Enter the issuer exactly as the discovery document's `issuer` value, including any trailing slash. | | Audit reason `email_not_verified` | The ID token lacks `email_verified: true`. Configure the provider to send it, or link through invitations. | Crow HR's automated tests run this flow end to end against a mock identity provider. Okta, Keycloak and Authentik themselves have not been tested. --- # Singpass login > What Crow HR's Singpass login does, what your company must do to become a Singpass relying party, and how to configure and test it. Tested against Singpass staging; not yet against production. Source: https://hr.crow.sg/docs/admin/sso/singpass/ :::caution[Tested against Singpass staging only] Crow HR's Singpass login follows Singpass's FAPI 2.0 login profile. It has been tested end to end against **Singpass staging** (PAR with DPoP, `private_key_jwt`, token exchange and the encrypted ID token, with a staging test account). It has **not** been run against Singpass production, and the button meets Singpass's design specification only once you add the official logo ([below](#the-singpass-button)). Run your own staging test before you go live. ::: ## What your company has to do first Singpass login is only available to organisations that Singpass has onboarded as a **relying party**. Crow HR cannot do this for you, and Crow Tech does not hold a Singpass client you can share. - Your company applies through the [Singpass developer documentation and portal](https://docs.developer.singpass.gov.sg/) and goes through Singpass's own onboarding, review and testing. Eligibility, agreements, fees and timelines are set by Singpass and can change; read their current documentation before you start. - You register Crow HR as your application, with the **redirect URI** and **JWKS URL** that Crow HR shows after saving the provider (steps 1 and 2 below). Singpass requires HTTPS, so `PUBLIC_URL` must be your final HTTPS address. - Singpass issues you a **client ID** for staging and, after their checks, for production. ## What Crow HR implements - Pushed authorisation requests (PAR), PKCE, `private_key_jwt` client authentication and DPoP-bound tokens. - `authentication_context_type=APP_AUTHENTICATION_DEFAULT` on every request (Singpass requires it for Login apps; it matches the portal's "General Authentication" scenario) and a client assertion with header `typ: JWT`. - Decryption of the encrypted ID token with your relying-party key. - Keys: Crow HR generates an ES256 signing key and an ECDH-ES encryption key (P-256) and publishes the public halves at the provider's JWKS URL. The API also accepts your own private JWKS instead. Private keys are encrypted at rest. - Default issuers are Singpass's FAPI 2.0 endpoints: `https://stg-id.singpass.gov.sg/fapi` (staging) and `https://id.singpass.gov.sg/fapi` (production), checked against their published discovery documents. There is an optional override. The bare hosts without `/fapi` are Singpass's older Login API, which has no PAR or DPoP, so don't use them. - Scope `openid` only. Crow HR stores the Singpass UUID from the subject, never the NRIC. There is no Myinfo data retrieval. ## Configure it 1. In **Settings → Security** choose **Add a method → Singpass**. Choose **Staging** and leave the issuer override empty unless Singpass tells you otherwise. Leave the client ID empty: Singpass only issues it after you register the redirect URI and keys. Save. Crow HR generates the relying-party keys and shows the two values for the next step. Until it has a client ID, Singpass stays off and the sign-in page doesn't show it. 2. In the Singpass Developer Portal, create a **Login** app in Staging (authentication scenario "General Authentication") and enter the **Redirect URI** (`/api/v1/auth/oidc//callback`) and the **JWKS URL** (`/api/v1/auth/oidc//jwks.json`). Keep the scopes to OpenID only. A staging app is active as soon as you submit it; its **App ID** is the client ID. Edit the method in Crow HR and add it. Singpass fetches the JWKS URL from its own servers (on AWS). If your server is behind **Cloudflare with Bot Fight Mode** on (or another bot filter), that fetch gets a challenge page and Singpass answers Crow HR's sign-in request with HTTP 502. On Cloudflare's Free plan Bot Fight Mode can't be skipped for one path. Either turn it off for that zone, or choose **JWKS object** in the portal and paste the contents of the JWKS URL (public keys only). With a JWKS object, paste the keys again whenever you replace them in Crow HR. 3. Create a staging test account in the portal (your app → **Test account** → **Create**; up to 5 per app; the password is behind the eye icon). Then run **Test sign-in** in Crow HR and choose **Use password** on the Singpass staging page. Settings → Security asks for this test until it passes, then shows when it passed. If Singpass refuses the request, the test returns to **Settings → Security** with reason `request_rejected`, and Singpass's error code (for example `invalid_client` or `invalid_request`) is in the audit log and the server log. 4. Only after a successful staging test and Singpass's approval, edit the provider, switch the environment to **Production** with the production client ID, test again, and switch it on. Until the provider has a client ID and keys, the sign-in page shows no Singpass button and Settings → Security shows Singpass as not configured. ## Linking people to Singpass Singpass accounts are never linked by email or NRIC. A member is linked to their Singpass identity only: - by choosing the Singpass button on their invitation page; or - by signing in another way and linking Singpass in **My sessions → Linked sign-in methods**. Just-in-time account creation is not available for Singpass. ## The Singpass button Singpass's [button design specification](https://docs.developer.singpass.gov.sg/docs/getting-started/singpass-button-design-specification) (effective 1 September 2026) requires the official Singpass logo inside the button. Singpass publishes the logo for its partners, not under a licence that allows redistribution in an MIT repository, so Crow HR does not bundle it. As a Singpass partner, you add it yourself: 1. Download the Singpass logo from the button specification page (the "Download Singpass logo" file). Use the full-colour logo for the default white button. 2. Save it as `branding/singpass-logo.svg` (or `.png`, at most 200 KB) in the app's data volume, for example: ```sh docker compose exec app mkdir -p /data/branding docker compose cp singpass-logo.svg app:/data/branding/singpass-logo.svg ``` 3. Reload the sign-in page: the Singpass button now shows the logo. No restart is needed. Crow HR serves the file at `/branding/singpass-logo` as an image only (an SVG cannot run script). Without the file, the button shows the plain text "Log in with Singpass". **Do not go live with Singpass until the button shows the official logo.** ## Public demo The [in-browser demo](https://hr.crow.sg/docs/demo/) runs entirely in the visitor's browser, so it cannot hold Singpass keys. To let visitors of a demo you host log in with Singpass for real, a Crow HR server acts as the relying party for it. You only need this to host a public demo; a normal install never does. 1. On that server, add a Singpass method as above (in its own organisation) and register it with Singpass. It does not need to be switched on. 2. Set `DEMO_SINGPASS_PROVIDER_ID` (the method's id, as in its redirect URI) and `DEMO_SINGPASS_RETURN_URL` (the demo's sign-in page, for example `https://hr.crow.sg/sign-in/kopi-kaki`) and restart. 3. Build the demo with `VITE_DEMO_SINGPASS_START_URL=/api/v1/auth/oidc//start?purpose=demo` and, for the logo, `VITE_SINGPASS_LOGO_SRC`. The visitor logs in with Singpass, the server checks Singpass's answer and then forgets the person: no account, session, link or Singpass ID is stored (the audit log records only that a demo login happened). Back in the demo, they choose **HR admin** or **Employee** and look around their own fictional copy. Each network can start 20 demo logins an hour and the server 1,000 a day. Real visitors need a **production** Singpass app; Singpass staging accepts only its test accounts. --- # Adding employees > Hire an employee in Crow HR, what each field is used for, how NRIC/FIN and bank numbers are protected, and the employee profile. Source: https://hr.crow.sg/docs/people/adding-employees/ **People** lists everyone in the organisation, with filters by department, location and status. Owners and HR admins add people; payroll admins add and change pay. Managers see their team, and every member sees the directory (name, job title, department, team, location, work email and phone, manager). ![The People list with status chips for expiring passes, scheduled starts and leavers (fictional company)](../../../assets/screens/people-directory.webp) ## Add one employee Choose **Add employee**. The form follows the record's sections: | Section | Fields | Used for | | --- | --- | --- | | Person | Legal name, preferred name, ID type (NRIC, FIN or other) and number, date of birth, gender, nationality | Payslips, CPF age band, IR8A. NRIC and FIN must pass the check-letter test (S/T for NRIC; F/G/M for FIN, including the M series). | | Residency | Citizen, PR (with PR start date) or foreigner | CPF rates: an SPR's first two years use graduated rates. The PR start date is required for PR and refused otherwise. | | Race and religion | Optional | Default self-help group (SHG) fund. An SHG opt-out can be recorded with its date. | | Contact | Work email, personal email, mobile, address | The work email receives the sign-in invitation. 8-digit mobile numbers are taken as +65. | | Job | Start date, job title, department, team, location, cost centre, manager, employment type, work schedule, probation end | Reporting lines (manager scope), pro-ration, checklists. | | Pay (payroll roles only) | Pay basis (monthly or hourly) and amount | Payroll. Recurring allowances are added through the API for now (`allowances` on the hire or a pay change); the **Pay** tab shows them. | | Work pass (foreigners) | Pass type, number, issue and expiry dates | A foreigner cannot be hired without a pass valid on the start date. See [work passes](https://hr.crow.sg/docs/people/work-passes/). | Saving creates the employee, their first employment period, the onboarding checklist from the default template and a sign-in invitation: emailed when SMTP is configured, otherwise shown once as a link to copy. Checks that stop a hire: - An ID number already used by another employee of the organisation, including a former one (`409 duplicate_id_number`). The message offers to **rehire** that person instead, which keeps their history. - An age below the minimum employment age on the start date (13, Employment Act s 68(3)). The family-only industrial undertaking exception is not supported. - A manager that would create a reporting cycle, or the employee as their own manager. Someone under 16 on the start date can be hired, and the form says what applies as soon as both dates are filled in: aged 13 or 14, light duties only and no industrial work unless with family members; aged 15, for industrial work notify MOM and send a medical report within the time MOM sets; under 16, no night work (11pm to 6am) and limits on daily hours ([MOM: young persons and children](https://www.mom.gov.sg/employment-practices/young-persons-and-children)). Crow HR does not check the hours or the notification for you. An existing sign-in with no employee link is linked automatically only if it holds no assigned roles. An owner or admin sign-in is never linked automatically; the hire succeeds with a message explaining why the invitation was skipped. Employee numbers are generated as `E0001`, `E0002`… unless you enter one. ### Legal and preferred names The **legal name** is the name on the NRIC, FIN card or passport. It goes on payslips, letters, the CPF file and IR8A. The **preferred name** is optional: the name the person goes by, for example *Hafiz* for Muhammad Hafiz bin Ismail or *Jun Jie* for Goh Jun Jie. Crow HR greets people and lists them in the directory by their preferred name, and uses the full legal name when there is none. It never guesses a "first name" from the legal name, because name order differs between Chinese, Malay, Indian and other names. HR can change both names from the profile (**Overview → Names → Edit**); employees can change their own preferred name in **My profile**. The CSV import has an optional `preferred_name` column. ### Workmen, managers and executives (Employment Act Part 4) Part 4 of the Employment Act (hours of work, rest days and statutory overtime at 1.5× the hourly basic rate) covers workmen earning up to S$4,500 basic pay a month and other employees earning up to S$2,600 ([MOM: hours of work and overtime](https://www.mom.gov.sg/employment-practices/hours-of-work-overtime-and-rest-days)). It **never covers managers and executives**, whatever they earn. Tick **Workman** or **Manager or executive** in the Job section when you add someone, or later with **Record change** on the profile. The **Job** tab shows the classification in force. The duties decide the classification, not the job title: a manager or executive has executive or supervisory duties, such as hiring, appraisals or running a team. See [MOM: who is covered](https://www.mom.gov.sg/employment-practices/employment-act/who-is-covered). For someone flagged as a manager or executive, attendance records overtime as contractual, payroll asks for the contractual overtime amount (`OT_NOT_STATUTORY`), and the Part 4 carry-forward of unused annual leave does not apply. ## The employee profile The profile has tabs for the person, work, pay, history and checklists. Records that change over time (job, pay, allowances, bank account, schedule) are **effective-dated**: each change has a start date, a future date is shown as "Scheduled" and applies on the day, and you can look at what was in force on any past date. ## Sensitive fields - **NRIC/FIN, passport and work pass numbers and bank account numbers** are encrypted in the database. NRIC/FIN is shown masked (`S****567D`), bank numbers as their last 4 digits. - People with access can **reveal** one full value at a time. Revealing needs a recent sign-in, is limited to 30 per hour and is audit-logged. - Pay and bank details are hidden from HR admins and managers. The API leaves such fields out and lists them in `redactedFields`. See [roles and permissions](https://hr.crow.sg/docs/roles-and-permissions/) for who sees what. ## Bank account Each employee has at most one current bank account (bank from the list of Singapore banks, account number, holder name). A new account keeps the old one as history, and payroll uses the account that is current on the pay date. Employees change their own bank details through a [change request](https://hr.crow.sg/docs/people/self-service-and-change-requests/). ## Export **Export** downloads the current list (with your filters and chosen columns) as CSV or XLSX. Only columns you can read are offered, managers export only their team, and unmasked NRIC or bank numbers need a recent sign-in. Every export is audit-logged with its columns and row count. --- # Importing from CSV > Import employees, compensation and year-to-date payroll opening balances into Crow HR from CSV, with a preview that lists every error before anything is saved. Source: https://hr.crow.sg/docs/people/importing/ **People → Import** loads three kinds of CSV file. Each has a downloadable template whose columns map one-to-one to fields. The column tables below are generated from the same template definitions the server uses, so they match the version you run. ![The import preview: 3 rows checked, 4 problems listed by row, column, value and how to fix them, import button disabled (fictional data)](../../../assets/screens/people-import-preview.webp) ## How an import works 1. Download the template, fill it in a spreadsheet and save it as CSV (UTF-8, comma-separated, with the header row). At most 5 MB and 2,000 data rows. 2. Upload it. Every row is checked with the same rules as the forms: NRIC/FIN check letters, required fields, existing department names (with the closest match suggested), dates, and so on. 3. The preview lists the rows that will be created and every problem as **row, column, value and how to fix it**. NRIC/FIN values in the preview are masked. 4. Nothing is saved until you confirm, and the confirm button stays disabled while any row has a problem. Fix the spreadsheet and **Upload a fixed file**. 5. Confirming writes all rows in one transaction, or none. Dates accept `YYYY-MM-DD` or `DD/MM/YYYY` only. Money is in dollars with up to 2 decimals (`4000.00`) and is stored as exact cents. ## Employees Creates employees with their first employment record and, for payroll roles, their basic pay. Each new employee gets a sign-in invitation after you confirm (see [members and roles](https://hr.crow.sg/docs/admin/members-and-roles/#inviting-people)). Foreigners need a work pass valid on the hire date. Template file `crowhr-employees-template-v2.csv` (version 2), 33 columns. | Column | Required | What to enter | Example | | --- | --- | --- | --- | | `employee_number` | no | Leave empty to auto-number (E0001…). | | | `legal_name` | yes | As on the NRIC, FIN card or passport. | `Tan Mei Ling` | | `preferred_name` | no | The name they go by, e.g. Hafiz for Muhammad Hafiz bin Ismail. Used in greetings and the directory. Leave empty to use the legal name. | `Mei Ling` | | `id_type` | yes | nric, fin or other. | `nric` | | `id_number` | yes | NRIC/FIN with check letter, or passport number. | `S1234567D` | | `date_of_birth` | yes | YYYY-MM-DD or DD/MM/YYYY. | `12/04/1990` | | `gender` | no | female, male, other or undisclosed. | `female` | | `nationality` | no | Country name. | `Singaporean` | | `residency_status` | yes | citizen, pr or foreigner. | `citizen` | | `pr_start_date` | no | Required for pr: SPR status date on the ICA entry permit. | | | `race` | no | chinese, malay, indian, eurasian or other (SHG fund). | `chinese` | | `religion` | no | buddhism, christianity, islam, hinduism, taoism, sikhism, other, none or undisclosed. | `buddhism` | | `work_email` | no | Used for the sign-in invitation. | `meiling@example.sg` | | `personal_email` | no | | | | `mobile` | no | 8-digit SG number or +country code. | `91234567` | | `hire_date` | yes | First day of work. | `2026-01-05` | | `job_title` | yes | | `Account Executive` | | `department` | yes | Must match an existing department name. | `Sales` | | `team` | no | Existing team name. | | | `location` | no | Existing location name. | | | `cost_centre` | no | Existing cost centre code. | | | `manager_employee_number` | no | Employee number of the manager (existing, or earlier in this file). | | | `employment_type` | yes | full_time, part_time, contract or intern. | `full_time` | | `work_schedule` | no | Schedule name; empty = the default schedule. | | | `probation_end` | no | YYYY-MM-DD or DD/MM/YYYY. | | | `workman` | no | yes for a workman (mainly manual work). Employment Act Part 4 covers workmen up to S$4,500 basic pay a month, other employees up to S$2,600. Empty means no. | `no` | | `manager_or_executive` | no | yes for a manager or executive (Employment Act Part 4 does not cover them: no statutory overtime, no Part 4 leave carry-forward floor). Empty means no. | `no` | | `pay_basis` | no | monthly or hourly. Needs payroll access. | `monthly` | | `basic_pay` | no | Dollars, up to 2 decimals. Needs payroll access. | `4000.00` | | `pass_type` | no | Foreigners: EP, S_PASS, WP, DP_LOC, LTVP_LOC, PEP, ONE, TEP or OTHER. | | | `pass_number` | no | FIN or work permit number. | | | `pass_issued_on` | no | | | | `pass_expires_on` | no | Required with pass_type. | | `manager_employee_number` can refer to an employee earlier in the same file. `workman` and `manager_or_executive` set the Part 4 classification ([who Part 4 covers](https://hr.crow.sg/docs/people/adding-employees/)): `yes` or `no`, empty means no. Files made from the version 1 template, without these columns, still import. `pay_basis` and `basic_pay` need payroll access: an HR admin without the payroll admin role cannot import pay. ## Compensation Records basic pay changes, effective-dated. A row dated in a month whose payroll is already approved or paid needs `retroactive` = `yes`; Crow HR then flags the back pay on the next payroll run (it is not computed for you; see [limitations](https://hr.crow.sg/docs/payroll/limitations/)). Template file `crowhr-compensation-template-v1.csv` (version 1), 6 columns. | Column | Required | What to enter | Example | | --- | --- | --- | --- | | `employee_number` | yes | Existing employee. | `E0001` | | `effective_from` | yes | YYYY-MM-DD or DD/MM/YYYY. | `2027-01-01` | | `pay_basis` | yes | monthly or hourly. | `monthly` | | `basic_pay` | yes | Dollars, up to 2 decimals. | `4200.00` | | `reason` | no | | `Annual increment` | | `retroactive` | no | yes when dated in a finalised payroll month. | `no` | ## Year-to-date opening balances Use this when you move to Crow HR during a year. CPF's additional-wage (AW) ceiling depends on the ordinary wages already paid in the year, so payroll needs the totals from your previous system. Without them, payroll warns on every employee that months before Crow HR are missing and the AW ceiling counts only the months Crow HR knows. Template file `crowhr-ytd-opening-balances-template-v1.csv` (version 1), 11 columns. | Column | Required | What to enter | Example | | --- | --- | --- | --- | | `employee_number` | yes | Existing employee. | `E0001` | | `year` | yes | Calendar year, e.g. 2026. | `2026` | | `through_month` | yes | Last month paid in the previous system: 1-12 or YYYY-MM. | `6` | | `ow_ytd` | yes | Ordinary wages paid, dollars. | `36000.00` | | `ow_cpf_ytd` | no | Ordinary wages subject to CPF (after the OW ceiling), dollars. | `36000.00` | | `aw_ytd` | yes | Additional wages paid (bonus, AWS), dollars. | `0.00` | | `aw_cpf_ytd` | no | Additional wages subject to CPF, dollars. | `0.00` | | `cpf_ee_ytd` | yes | Employee CPF, dollars. | `7200.00` | | `cpf_er_ytd` | yes | Employer CPF, dollars. | `6120.00` | | `shg_ytd` | yes | SHG deductions (CDAC/ECF/MBMF/SINDA), dollars. | `9.00` | | `sdl_ytd` | no | SDL paid, dollars. | `54.00` | One row per employee and year, covering the year up to and including `through_month`, the last month paid in the previous system. For example `ow_ytd` 36000.00 with `through_month` 6 stores S$36,000.00 of ordinary wages for January to June. The next Crow HR run (July) starts from these figures. :::caution[Check the figures] Opening balances drive the AW ceiling for the rest of the year. Take them from your previous system's year-to-date CPF report and reconcile them against what you actually submitted to CPF before your first Crow HR run. ::: --- # Employee lifecycle > Transfers, promotions, salary changes, probation, resignations, terminations and rehires in Crow HR, with effective dates and checklists. Source: https://hr.crow.sg/docs/people/lifecycle/ Every change to someone's job or pay is recorded as a **lifecycle event** with the person who made it, an effective date and the records it produced. Use **Record a change** or **Record leaving** on the profile. | Event | What it does | | --- | --- | | Hire | Creates the employment period, job and pay records, the onboarding checklist and the sign-in invitation. | | Transfer, promotion | New job record (department, team, location, manager, title, schedule…) from the effective date. | | Salary change | New pay record from the effective date (payroll roles only). | | Probation confirmed | Records the confirmation. | | Resignation | Notice date and notice period; computes the last working day. | | Termination | Reason (dismissal, retrenchment, contract end, retirement, death, mutual agreement) and last working day. | | Rehire | A new employment period on the same employee, keeping their number and history. | ## Effective dates Events dated in the future show as **Scheduled** and take effect on the day, computed from the date (Singapore time), not by a background job. A scheduled change can be cancelled, which restores the records before it. Cancelling a scheduled hire or rehire is not supported; record a termination instead. The People list shows states derived from the dates: "Starts 16 Nov 2026", "Leaving 17 Nov 2026", "Work pass expired". ## Resignations and notice The notice date counts as day 1. A 30-day notice given on 3 Nov 2026 gives a last working day of 2 Dec 2026. You can agree a shorter last day. When the contract states no notice period, Crow HR uses the statutory minimum from MOM's rules by length of service: 1 day under 26 weeks, 1 week under 2 years, 2 weeks under 5 years, and 4 weeks from 5 years. Check the employment contract: it usually states the notice period. ## Leaving Only an owner can record leaving for an employee whose sign-in holds an assigned role. The last active owner cannot have a leaving event recorded: appoint another active owner first. Resignations and terminations create the offboarding checklist from the default template. The day after the last working day the person's membership becomes **former**: they can still sign in to read their own released payslips, and nothing else. For the final month's pay, use an off-cycle **final pay** run or include them in the regular run (see [running payroll](https://hr.crow.sg/docs/payroll/running-payroll/)). When the membership becomes former, their open approval tasks pass to other eligible approvers and any out-of-office cover to or from them ends. If that change fails for one leaver, Crow HR retries it and tells the owners once; other leavers are not held up. ## Pay changes and finalised payroll Recurring allowances are pay: adding them at hire or rehire, scheduling changes to them and cancelling those changes need compensation access (payroll admins and owners). Nobody can change or cancel their own allowances. The audit log records these changes without the amounts. A pay change dated in a month whose payroll is already approved or paid is refused unless you mark it **retroactive**. Crow HR then shows a back-pay warning (`BACKPAY_OWED`) on the next run. The back-pay amount is not computed: enter it as a "Back pay" item on that run. ## Checklists Owners and HR admins keep onboarding and offboarding checklist templates. Each item has an assignee role (HR admin, payroll admin, manager or the employee) and a due date relative to the start date or the last working day, for example "Issue KETs, HR admin, +14 days". Open items appear on each assignee's Home and can be completed, or skipped with a reason. Cancelling the event that created a checklist cancels the checklist. --- # Work passes > Record work passes for foreign employees in Crow HR and get expiry reminders. Source: https://hr.crow.sg/docs/people/work-passes/ Foreign employees (residency "foreigner") need a work pass record valid on their start date before they can be hired. ## Pass types Employment Pass, S Pass, Work Permit, Dependant's Pass with Letter of Consent, Long-Term Visit Pass with Letter of Consent, Personalised Employment Pass, ONE Pass, Training Employment Pass, or other. In the import template the codes are `EP`, `S_PASS`, `WP`, `DP_LOC`, `LTVP_LOC`, `PEP`, `ONE`, `TEP` and `OTHER`. Each record has the pass type, the pass number (encrypted at rest), issue and expiry dates, and notes. ## Reminders HR admins get a reminder on Home and in notifications **90, 60, 30 and 7 days** before a pass expires, and on the expiry date. The 90-day lead is a Crow HR default, not a statutory period. Reminders stop when a newer pass with a later expiry is added. :::note Reminders read the **latest** pass of each employee. Record a renewal as a new pass with the new expiry date; editing the old record's dates is not the same. ::: An expired pass with no later pass shows the employee as **Work pass expired** in the People list. ## Not covered - Crow HR does not check work-pass eligibility, quotas or the qualifying salaries for passes. - It does not talk to MOM's systems. Applications and renewals happen in MOM's portals. - The foreign worker levy shown in payroll is an estimate; see [SHG, SDL and FWL](https://hr.crow.sg/docs/payroll/shg-sdl-fwl/#foreign-worker-levy-estimate). --- # Self-service and change requests > What employees can change themselves in Crow HR, and how changes to legal and bank details are approved. Source: https://hr.crow.sg/docs/people/self-service-and-change-requests/ Employees see their own record in **My profile** and their payslips in **Payslips**. ## Changed directly These are saved straight away and audit-logged: - preferred name - personal email and mobile number - address - emergency contacts (up to 3) ## Changed through a request Changes to these fields create a **change request** with an optional attachment: - legal name, ID number, date of birth - residency status and PR start date - race and religion - bank details While the request is pending, the employee sees the new values marked **Awaiting approval**; everywhere else, including payroll, the current values stay in force. Requests go through the [approvals engine](https://hr.crow.sg/docs/approvals/approvals/): by default **bank details go to payroll admins** and everything else to **HR admins**. The approver sees the change and the attachment and approves or rejects with a comment. An approved change applies from the approval date; changes can't be dated in the future. Approvers act from Home or the Inbox. Nobody approves their own request, except an owner when no one else can. ## Segregation of duties Nobody, including owners and payroll admins, edits their own compensation or bank details directly. A payroll admin who needs a raise or a new bank account gets it through someone else, which leaves an audit trail. Bank-change requests, including the holder name and account ending, are visible only to the requester, payroll admins and owners. An HR admin needs the payroll admin role to see them. ## Light or dark Crow HR follows your device's light or dark setting. To choose for yourself, open the account menu (your name or initials, top right) and pick **Theme: System, Light or Dark**. The choice is kept in this browser only, so a shared computer and your phone can differ, and signing out doesn't change it. The in-browser demo has the same setting. Payslip PDFs and letters are documents for printing and filing, so they always stay black on white. --- # Payroll settings > Set the pay day, payslip release, CPF advice code, foreign worker levy profile and the debit account for the bank file before your first Crow HR payroll run. Source: https://hr.crow.sg/docs/payroll/settings/ Payroll is available to owners and payroll admins. Before the first run, check three things. ## 1. Company profile The run cannot be submitted until **Settings → Company** has the legal name, UEN, CPF submission number (CSN) and registered address. The legal name is printed on payslips and the CSN goes into the CPF EZPay file. See [company and structure](https://hr.crow.sg/docs/admin/company-and-structure/#company-profile). ## 2. Employee records Payroll reads everything from People: date of birth (CPF age band), residency and PR start date (CPF rates), race and religion (SHG fund), work schedule (pro-ration), basic pay and recurring allowances, and the bank account current on the pay date. If you start mid-year, [import year-to-date opening balances](https://hr.crow.sg/docs/people/importing/#year-to-date-opening-balances) first. ## 3. Payroll settings Open **Payroll → Settings**: | Setting | What it does | | --- | --- | | Pay day | Day of the month for the default pay date; empty means the last day of the month. MOM requires salary to be paid within 7 days after the end of the salary period, and the run warns when the pay date is later. | | Cutoff day | Day of the month payroll inputs close. Payroll admins get a reminder 3 days before it, or before the pay day when it is empty, until the month's regular run is approved. | | Release payslips on approval | Off by default: payslips become visible to employees only when a payroll admin releases them. On: they are released automatically when the run is approved. | | CPF advice code | Two digits for the EZPay file, usually `01`. Later runs in the same month get the next free code. | | Foreign worker levy: sector, tier and skill | Your company's profile for the [FWL estimate](https://hr.crow.sg/docs/payroll/shg-sdl-fwl/#foreign-worker-levy-estimate). Sectors: services, manufacturing, construction, process, marine shipyard. | | Debit account: bank SWIFT/BIC, account number, account name | The account salaries are paid from, written into the [bank file](https://hr.crow.sg/docs/payroll/bank-file/). | ## Allowance treatment **Payroll → Allowance treatment** (also under **Settings**) lists each recurring allowance type with three settings. Owners and payroll admins change them; a change applies the next time a draft run is computed. | Setting | Default | Meaning | | --- | --- | --- | | CPF | CPF-liable (ordinary wages) | Whether the allowance is subject to CPF. Decide with CPF's guidance on [what counts as wages](https://www.cpf.gov.sg/employer/employer-obligations/what-constitutes-wages-for-cpf-contributions). | | Incomplete month | Pro-rated | Whether it is pro-rated, like basic pay, in a month someone joins or leaves. | | Gross rate of pay | Not set | Whether it counts in the Employment Act gross rate of pay, used for public holiday pay and leave encashment. **Included** for fixed contractual salary allowances; **Excluded** for variable or irregular payments, productivity incentives, reimbursements, and travelling, food and housing allowances. Overtime, bonuses and AWS never count ([MOM: gross rate of pay](https://www.mom.gov.sg/employment-practices/salary/monthly-and-daily-salary)). | The gross rate has no default because no answer is right for every allowance. Answer it for each allowance before your first run: while one is not set, every run lists it as a warning (`ALLOWANCE_GROSS_RATE_UNSET`, with a link to this screen), a public holiday on an off day blocks payroll for the staff who get it (`PH_GROSS_RATE_REQUIRED`), and their leave encashment can't be requested. Changing a setting later does not reprice encashment requests already made. Allowance types, and the recurring allowances on each employee, are added through the API for now ([API reference](https://hr.crow.sg/docs/api/)): allowance types under organisation settings, and allowances on a hire or pay-change event. They show on the employee's **Pay** tab. ## Holiday pay and contractual overtime on a run Two kinds of item need an amount that only you know. The run's issue says so and links to the employee's drawer with the item ready to fill in: - **Holiday pay for hourly or rostered staff.** Under the leave rule **Pay an extra day (payroll)**, an employee covered by the Employment Act earns one day's gross pay for a public holiday on an off day. Payroll adds it automatically for employees on a monthly rate and a fixed week. For anyone else the run blocks with `PH_GROSS_RATE_REQUIRED` until you choose **Enter holiday pay** and enter the day's gross pay; the item is tied to that holiday, so it is paid once. - **Overtime from attendance without a statutory rate.** For employees not covered by Part 4, or paid by the hour, approved overtime blocks the run (`OT_NOT_STATUTORY`, `OT_AMOUNT_REQUIRED`). Choose **Enter the overtime amount**, or **Enter amount** next to the overtime under **From other modules** in the drawer, and enter the contractual pay for those hours. It replaces the fed amount for that overtime claim, so the overtime is not paid twice. Manual items can be edited or removed from the drawer while the run is a draft. Through the API these are an `other_earning` item with `holidayDate`, and an `overtime` item with `overtimeSourceId` (the approved overtime claim's ID); see the [API reference](https://hr.crow.sg/docs/api/payroll/). --- # Running payroll > Create, compute, review, approve and pay a monthly payroll run in Crow HR, plus off-cycle and adjustment runs. Source: https://hr.crow.sg/docs/payroll/running-payroll/ A payroll run covers one organisation and one calendar month. It moves through four states: **Draft** (inputs editable) → **In review** (waiting for approval) → **Approved** → **Paid** (locked). ## 1. Create the run **Payroll → New payroll run**. Choose the month and kind: | Kind | Who is in it | Use it for | | --- | --- | --- | | Monthly (regular) | Everyone employed in the month | The normal monthly payroll. One per month. | | Off-cycle final pay | The employees you choose; they are then left out of that month's regular run | Paying a leaver before the regular run. | | Off-cycle bonus | One-off payments only | A bonus paid outside the regular run. CPF is recomputed for the whole month and the difference charged. | | Adjustment | Created by reopening an approved or paid run | Corrections (see below). | The pay date defaults from [payroll settings](https://hr.crow.sg/docs/payroll/settings/). ## 2. Add the month's items Basic pay and recurring allowances come from People. Some items arrive on their own from the other modules each time the run is computed (see [items fed from other modules](#items-fed-from-other-modules) below); everything else is an item on the run, entered by hand: - **Earnings**: bonus, commission, back pay, other earnings. Each is ordinary wages (OW) or additional wages (AW); an AW item needs the date it became **due and payable**, inside the run's period (CPF keys the AW ceiling to that date). - **Overtime**: minutes worked and the period in which they were worked. For employees covered by Part 4 of the Employment Act, the pay is computed with the statutory rate; for others, enter the contractual amount (the run blocks with `OT_NOT_STATUTORY` until you do). - **No-pay leave** in days, **hours** for hourly-paid staff, and **scheduled days / days worked** for staff without a fixed working week, when they are not fed. - **Deductions**, each in an Employment Act category (accommodation, amenities, damage or loss, advance, loan, unauthorised absence, court order or tax, co-operative society, written consent and others), plus **CPF AW recovery** for an AW top-up (see [limitations](https://hr.crow.sg/docs/payroll/limitations/#cpf)). ### Items fed from other modules When the run is computed, Crow HR adds these items itself, each labelled with where it came from: | Item | From | Rule | | --- | --- | --- | | No-pay leave, unpaid infant care leave, unpaid company leave | [Leave](https://hr.crow.sg/docs/leave/leave/#how-leave-reaches-payroll) | Approved days in the run's period, in half days. A no-pay leave item you enter for the same date replaces it. | | Overtime | [Attendance](https://hr.crow.sg/docs/attendance/attendance/#how-approved-overtime-reaches-payroll) | Approved overtime claims for dates in the period, plus earlier approved claims that no run has paid yet. Items you enter are added on top, so don't enter the same hours twice. | | Days worked | Attendance | Rostered staff who clock in. An item you enter wins. | | Scheduled days | [Published rosters](https://hr.crow.sg/docs/scheduling/scheduling/#payroll-scheduled-days) | Only when the whole month is published and the employee was employed all month. An item you enter wins. | | Claims reimbursement | [Claims](https://hr.crow.sg/docs/claims/claims/#through-payroll) | Approved claims paid with payroll, approved by the end of the month and not yet paid. Shown under "Reimbursements (not wages)": no CPF, not in gross pay. | | Public holiday pay | [Leave rules](https://hr.crow.sg/docs/leave/leave/#public-holidays-and-days-in-lieu) | With **Pay an extra day (payroll)**, one day's gross pay for each public holiday on an off day, for employees covered by the Employment Act on a monthly rate and a fixed week. For others the run blocks until you enter the day's gross pay ([holiday pay and contractual overtime](https://hr.crow.sg/docs/payroll/settings/#holiday-pay-and-contractual-overtime-on-a-run)). | | Leave encashment | [Leave](https://hr.crow.sg/docs/leave/leave/#encash-unused-leave) | Approved encashment requests, approved before both the pay date and the end of the period. Additional wages, CPF-liable. | Fed overtime, holiday pay, encashment and claims are each paid by one run only: recomputing keeps them, another run skips them, deleting a draft run releases them, and an adjustment run pays only the difference. Bonus-only off-cycle runs take none of these; a leaver's final-pay run takes theirs. Fed overtime carries minutes only: for employees not covered by Part 4, or paid by the hour, the run blocks (`OT_NOT_STATUTORY`, `OT_AMOUNT_REQUIRED`) until you enter the contractual amount for it in the employee's drawer ([holiday pay and contractual overtime](https://hr.crow.sg/docs/payroll/settings/#holiday-pay-and-contractual-overtime-on-a-run)). Something approved after you computed the run makes **Submit for approval** ask you to recompute. ## 3. Compute and review **Recompute** calculates every employee from the current records and the items. The overview shows, in this order: 1. **Blocking issues** and **warnings**, each with a link to its source and a link to where it is fixed: the employee's drawer with the item ready to fill in (holiday pay, an overtime amount, hours, scheduled days, an item to correct), **Allowance treatment**, the company profile or the employee's record. Each issue's rule ID (for support and the [troubleshooting](https://hr.crow.sg/docs/help/troubleshooting/) page) is on its icon's tooltip. 2. **Who gets what**: net pay to employees, the total to CPF Board (CPF, SHG and SDL, as in the CPF EZPay file) and the foreign worker levy estimate. Gross pay, CPF and the other columns are totalled in the table's **Total** row. 3. **Changes since last month**: joiners, leavers, pay changes, new items. 4. **The employee table**: dense, numbers right-aligned. Move with the arrow keys or `j`/`k`, open an employee with Enter, close with Escape, and step through employees in the drawer with `[` and `]`. ![October 2026 payroll overview: one blocking issue, the warnings, and what goes to employees, CPF Board and the levy (fictional company)](../../../assets/screens/payroll-run-overview.webp) The drawer shows every line of that employee's pay, the **CPF working** and the issues. See [reading the CPF working](https://hr.crow.sg/docs/payroll/cpf-working/). Things that block submission: - missing UEN, CSN or address on the company profile; - a case the statutory engine refuses (for example `CPF_LOW_WAGE_CAPPED_AW_UNSUPPORTED`): the rest of the run still computes; - deductions over the Employment Act limits (the 50% overall limit is only a warning on final pay); - negative net pay; - staff without a fixed week whose scheduled days and days worked are missing; - an AW item dated outside the run's period. Warnings do not block: a pay date more than 7 days after the period (salary) or 14 days after the period in which overtime was worked, missing year-to-date opening balances, back pay owed from a retroactive change, rates for future years carried forward. ## 4. Submit and approve **Submit for approval** needs a computation with no blocking issues whose inputs still match the records. If someone changed a salary or an item after you computed, submission fails with `409` and asks you to recompute. The run goes through the [approvals engine](https://hr.crow.sg/docs/approvals/approvals/) as a **Payroll runs** request with the net total. By default an **owner** approves. An owner who submitted the run may approve it themselves when nobody else can; that decision is recorded as self-approved. Someone who entered or edited earnings for themselves on the run can never approve it, even as an owner: the approval summary names them, and another eligible owner must decide. A rejection returns the run to draft with the approver's comment. You can **withdraw** a run in review back to draft. ## 5. Release, pay, file After approval: - **Release payslips** (unless automatic release is on). Employees then see them under Payslips. See [payslips](https://hr.crow.sg/docs/payroll/payslips/). - Download the [CPF EZPay file](https://hr.crow.sg/docs/payroll/cpf-ezpay-file/) and upload it in CPF EZPay. - Download the [bank file](https://hr.crow.sg/docs/payroll/bank-file/) (needs a recent sign-in) and upload it to your bank, or pay another way. - **Mark paid** once the money has gone out. This locks the run and marks the claims it reimbursed as paid, dated the pay date. Crow HR does not submit anything to CPF Board, IRAS or your bank itself. ## Correcting an approved or paid run **Return to draft** (an approved run that is not marked paid) is for a change that must not be paid as an adjustment, such as an employee's new bank account: give the reason, kept in the audit log, then recompute and approve the run again. Its payslips are hidden from employees until it is released again. It is refused once a later run of the year has used this run's CPF figures; reopen it as an adjustment instead. **Reopen as an adjustment** creates an adjustment run for the same month, starting from a copy of the original inputs, with a reason kept in the audit log. The original run, its payslips and its files never change; it is marked superseded only when the adjustment is approved. The adjustment charges only the difference in CPF, SHG and SDL, its payslips are labelled as a revision and show the net amount still to pay (or overpaid), and its EZPay file is a supplementary file. Adjustments do not recompute later months. If you reopen a month after later months were finalised, Crow HR warns; CPF's year-end (or last-month) AW recomputation absorbs the difference. ## Every result is reproducible Each employee's result is computed from a stored snapshot of their inputs and the rate tables used. Inputs and results are stored with SHA-256 hashes, and recomputing a snapshot gives a byte-identical result, so you can show later exactly how a figure was produced. ## Leave encashment Approved [leave encashment](https://hr.crow.sg/docs/leave/leave/#encash-unused-leave) enters the next regular run, or a leaver's off-cycle **Final pay** run, as **Leave encashment (N days)** (hours for balances kept in hours), and appears in the run's change list. Its amount and rate working are fixed when the request is made: the payslip shows basic pay and each included allowance, the monthly and daily gross rate, the quantity and the rounding. Encashment is additional wages and CPF-liable, with the normal AW ceiling. --- # Reading the CPF working > How Crow HR computes CPF contributions - OW and AW, the OW and AW ceilings, age bands, SPR graduated rates and rounding - and how to read the working shown for each employee. Source: https://hr.crow.sg/docs/payroll/cpf-working/ Open an employee in a payroll run to see the drawer: every pay line, the **CPF summary**, the full **working** and the issues. Every step names the rate table it used, its effective date and a link to CPF's source. Each working line's rule ID shows when you point at it, and the drawer lists them all under **Rule IDs, for support**, for when you ask for help. ![The employee drawer: pay lines, the CPF summary (category, age band, wage band, OW and AW subject, AW ceiling, headroom) and the working (fictional data)](../../../assets/screens/payroll-cpf-drawer.webp) ## CPF summary | Field | Meaning | | --- | --- | | Category | `SC` (citizen, or SPR from the third year) or an SPR graduated category for the first two years of PR status. | | Age band | From the date of birth: 55 and below, above 55 to 60, above 60 to 65, above 65 to 70, above 70. | | Wage band | Which part of the rate table applies to the month's total wages: up to S$50 (no CPF), above S$50 to S$500 (employer only), above S$500 to S$750 (phase-in) or full rates above S$750. | | OW subject | Ordinary wages subject to CPF, capped at the monthly OW ceiling. | | AW subject | Additional wages subject to CPF this month, after the AW ceiling. | | AW above ceiling | Additional wages not subject to CPF because the AW ceiling was reached. | | AW ceiling (estimate) | The year's AW ceiling as estimated this month (see below). | | Headroom left | How much more AW can be subject to CPF this year. | | Exact total | The total contribution before rounding. | ## Ordinary and additional wages - **Ordinary wages (OW)** are wages for the month's work, payable by the 14th of the next month: basic pay, most fixed allowances, overtime. - **Additional wages (AW)** are not granted wholly for the month's work: bonuses, the annual wage supplement, non-monthly commission. Crow HR does not decide this for you. Each earning item is marked OW or AW by whoever enters it, and each allowance type is OW unless set otherwise. CPF's page on [what constitutes wages](https://www.cpf.gov.sg/employer/employer-obligations/what-constitutes-wages-for-cpf-contributions) is the authority. ## The OW ceiling OW subject to CPF is capped per employee, per employer, per month: **S$8,000** from 1 January 2026 (S$7,400 in 2025), as in CPF's [contribution rate tables](https://www.cpf.gov.sg/content/dam/web/employer/employer-obligations/documents/CPFcontributionratesfrom1Jan2026.pdf). OW above it is not subject to CPF. ## The AW ceiling The AW subject to CPF in a year is limited by the **AW ceiling** ([CPF: OW and AW ceilings](https://www.cpf.gov.sg/service/article/what-is-the-ordinary-wage-ow-ceiling)): > AW ceiling = S$102,000 (annual salary ceiling) − total OW subject to CPF for the year Because the year's OW is not known until December, CPF's procedure has two steps, and Crow HR follows it: 1. **Estimate** when AW is paid: the OW subject so far, plus the expected OW for the rest of the year (or until the employee's known last month). 2. **Recompute** in December, or in the employee's last month: with the actual OW, earlier AW is re-allocated in date order. If the ceiling grew, the extra AW becomes subject (a top-up, shown as a shortfall line); if it shrank, the excess contribution is flagged for a refund from CPF (`CPF_AW_EXCESS_REFUND`). Refunds are applied for with CPF and never netted or deducted. The AW ceiling uses the date each AW became **due and payable**, so enter that date on every AW item. If you started using Crow HR during the year, [import year-to-date opening balances](https://hr.crow.sg/docs/people/importing/#year-to-date-opening-balances). Otherwise the estimate counts only the months Crow HR knows, and every run warns that the months before Crow HR are missing (rule ID `YTD_BEFORE_CROWHR_MISSING`). The engine replays all 16 worked examples in CPF's AW ceiling guide month by month and matches every figure to the dollar (see [how we verify](https://hr.crow.sg/docs/payroll/verification/)). ## SPR graduated rates In the first two years of Singapore permanent residence, CPF rates are graduated. The year is counted from the PR start date on the employee's record, so that date must be right. Three options exist: | Option | Employer | Employee | | --- | --- | --- | | G/G (default) | graduated | graduated | | F/G | full | graduated | | F/F | full | full | F/G and F/F are a joint election with CPF Board. Crow HR stores the option and the month it applies from on the employee's record and never infers it; record it only once CPF has approved it. From the third year, citizen rates apply. In the month someone becomes a PR, only the wages from the PR date (and AW payable on or after it) count, and the engine raises `CPF_SPR_CONVERSION_MONTH` so you can check the split. ## Rounding Crow HR rounds exactly as CPF's online calculator does (confirmed in 15 of 15 cases): 1. Apply the rate to the exact wage, without rounding the wage first. 2. Round the **total** contribution to the nearest dollar (50 cents rounds up). 3. Drop the cents from the **employee** share. 4. **Employer** share = total − employee share. Money is held as integer cents throughout; nothing uses floating point. ## Rates for future years The engine carries CPF rate tables for 2025, 2026 and 2027 as published by CPF. CPF publishes next year's rates during the year; until the 2028 tables exist, months from January 2028 use the 2027 tables and every result carries the warning `CPF_RATES_ASSUMED_CARRIED_FORWARD`. ## Cases Crow HR refuses - A month with total wages above S$50 and up to S$750 where part of the AW is above the AW ceiling (`CPF_LOW_WAGE_CAPPED_AW_UNSUPPORTED`). CPF publishes no rule for it, so the run blocks for that employee instead of guessing. - Negative wages. A correction recomputes the original month with corrected inputs (an adjustment run). See [limitations](https://hr.crow.sg/docs/payroll/limitations/#cpf) for the open CPF questions. --- # SHG funds, SDL and FWL > How Crow HR computes self-help group fund contributions, the Skills Development Levy and its foreign worker levy estimate. Source: https://hr.crow.sg/docs/payroll/shg-sdl-fwl/ ## Self-help group (SHG) funds SHG contributions are deducted from the employee's pay and paid to CPF Board with the CPF contribution, for one of four funds: | Fund | For | | --- | --- | | CDAC | Chinese | | ECF | Eurasian | | MBMF | Muslim (by religion) | | SINDA | Indian descent, including the groups SINDA lists (for example Tamil, Punjabi, Sikh, Sinhalese, Bengali) | Crow HR picks the fund from the race and religion recorded on the employee's profile, following CPF's [rules for determining the fund](https://www.cpf.gov.sg/service/article/how-do-i-determine-which-self-help-group-shg-my-employee-should-contribute-to), and looks up the amount in the fund's table by the month's total wages. Record an opt-out, with its date, on the employee's profile when the employee has opted out with the fund. Check race and religion on import: a missing value means no fund is chosen. The CDAC, ECF and SINDA tables are verified as current, but CPF does not publish their start dates, so Crow HR does not claim history before 2025. ## Skills Development Levy (SDL) SDL is paid by the employer for each employee, never deducted from pay ([CPF: Skills Development Levy](https://www.cpf.gov.sg/employer/employer-obligations/skills-development-levy)): - 0.25% of the month's total wages, at least **S$2** (for wages below S$800) and at most **S$11.25** (for wages above S$4,500); - **S$0** for a month with no wages paid or payable; - exemptions from SSG's [SDL FAQ](https://file.go.gov.sg/sdl-generic-faq.pdf) (domestic workers, no service in Singapore, approved training, school-holiday students and others) are applied only when recorded. SDL is included in the CPF EZPay file under payment code 11. ## Foreign worker levy estimate For S Pass and Work Permit holders, Crow HR shows an **estimate** of the monthly foreign worker levy from the sector, tier and skill in [payroll settings](https://hr.crow.sg/docs/payroll/settings/), using MOM's published monthly rates (services, manufacturing, construction, process, marine shipyard). :::caution[Estimate only] MOM bills the levy and its bill is authoritative. Your tier depends on MOM's own quota computation, which Crow HR does not reproduce. The levy is borne by the employer and must never be deducted from salary; Crow HR shows it as an employer cost only. ::: ## Not computed - Income tax (Crow HR does not withhold tax), IR21 tax clearance for foreign or SPR leavers. - CPF late-payment interest. - Work-pass qualifying salaries. See [limitations](https://hr.crow.sg/docs/payroll/limitations/). --- # Payslips > What Crow HR's itemised payslips contain, when employees can see them, and the PDF version. Source: https://hr.crow.sg/docs/payroll/payslips/ Every employee in an approved run gets an itemised payslip. Employees see their own released payslips under **Payslips** (web and PDF); former employees keep read-only access to theirs. ![A September 2026 payslip with earnings, deductions, net pay, employer CPF and the CPF table used (fictional data)](../../../assets/screens/payslip.webp) ## Contents Payslips contain the items MOM lists for [itemised payslips](https://www.mom.gov.sg/employment-practices/salary/itemised-payslips): - employer's full name and employee's full name; - date of payment and the start and end of the salary period; - basic salary, or for hourly-rated staff the rate and hours; - fixed and ad hoc allowances, and other additional payments; - fixed and ad hoc deductions, including employee CPF and no-pay leave; - overtime hours and pay, with the overtime period when it differs from the salary period; - net salary. They also show employer CPF (not deducted), the self-help group fund, the CPF rate table and age band used, and the year-to-date AW subject to CPF. NRIC/FIN is masked. A payslip missing a mandatory item cannot be released: the release fails and names the item, for example "Employer's full name" when the company profile has no legal name. ## Release Payslips stay hidden from employees until the run is approved **and** released by a payroll admin or owner (or automatically on approval, if you turned that on in [payroll settings](https://hr.crow.sg/docs/payroll/settings/)). Before release, an employee gets `404` for their payslip. Release is audit-logged, and each employee with a Crow HR account is notified ("Your payslip for October 2026 is ready", in the app and by email when email is set up). The notification names the month only, never an amount. Payroll admins can preview any payslip, including the PDF, before release. An adjustment run's payslip is labelled as a revision of the original and shows what is still payable or was overpaid. ## PDF PDFs are generated on your server with fonts shipped in the image; nothing is downloaded at run time. The same payslip always renders to a byte-identical PDF, so a payslip downloaded twice has the same SHA-256. Amounts are formatted `S$1,234.56` and dates `31 Oct 2026`. Names and other text in Chinese or Tamil script print with embedded Noto Sans SC and Noto Sans Tamil. A character that none of the fonts has prints as `?`, and the PDF shows a warning naming its Unicode code point: check the name in Crow HR before issuing the payslip. ## Not available - Payslip emails with the PDF attached (by design, emails never carry pay data). - Daily-rated and piece-rated pay units on the payslip. --- # CPF EZPay file > Download the CPF EZPay (FTP) submission file for a Crow HR payroll run and upload it to CPF EZPay yourself. Source: https://hr.crow.sg/docs/payroll/cpf-ezpay-file/ For an approved or paid run, a payroll admin downloads the **CPF EZPay submission file** from the run page and uploads it in CPF's EZPay service. Crow HR does not submit to CPF Board directly. ## Format The file follows CPF Board's *CPF EZPay (FTP) File Specifications* effective 16 January 2025: - fixed-length records of 150 characters: employer header, a summary record per payment code, detail records, employer trailer with record count and total; - file name `.DTL`; - payment codes CPF (01), MBMF (02), SINDA (03), CDAC (04), ECF (05) and SDL (11); - employment status E, L, N or O from the join and leave dates; - names stripped of the characters the specification forbids. It contains the amounts **this run charged**. An adjustment run produces a supplementary file with only the difference. ## Refusals and exclusions Generation stops with a message saying how to fix it when: - the company profile has no CSN; - an amount would be negative; - a CPF account number does not start with S or T. Employees without an S/T number who have an SHG contribution (foreign employees) are left out of the detail records with a warning to key them in EZPay; their SHG is written as a summary record only. ## Advice codes The month's regular run uses the advice code from [payroll settings](https://hr.crow.sg/docs/payroll/settings/) (usually `01`). Each later run of the same month gets the next free code. A month that would need a code past 99 is refused rather than reusing a code. ## Not confirmed by CPF Board The file is tested against a committed golden file built from the specification, but it **has not been accepted by CPF's systems in a real submission**, and CPF Board has not reviewed it. Points the specification does not settle: - whether foreign employees' SHG should appear as a summary record only (what Crow HR does); - how a top-up on earlier AW should be declared: Crow HR reports it in the current month's amount with no new AW in that month's AW column. Check the first file you upload against CPF EZPay's own validation and your payroll records. --- # Bank payment file > Crow HR's generic ISO 20022 pain.001.001.03 salary file, what it contains and why you must check it with your bank first. Source: https://hr.crow.sg/docs/payroll/bank-file/ For an approved run, a payroll admin can download a **bank payment file** for the run's net pay. It is a generic ISO 20022 `pain.001.001.03` credit-transfer file. Downloading it needs a recent sign-in and is audit-logged. ## What it contains - Category purpose `SALA` (salary) on the payment information and transaction purpose. - The debit account from [payroll settings](https://hr.crow.sg/docs/payroll/settings/) (bank BIC, account number, account name). - One credit transfer per employee, for their net pay, to the bank account that was current on the pay date when the run was computed. - Employees without a bank account are left out and listed as excluded on screen. The file validates against the official ISO 20022 XSD. ## Check it with your bank before first use :::caution[Generic format, not tested with any bank] Singapore's SS611 standard adopts `pain.001.001.03` but leaves the details to each bank, and banks publish their own implementation guides. The file is **not mapped to any bank's guide and has not been tested with any bank**. ::: Known differences you may need to resolve with your bank: - **Service level and rail**: the file has no service level or local instrument, so it does not choose FAST or GIRO. ANZ's Singapore guide, for example, requires service level `URNS` for FAST/PayNow. - **Charge bearer** is fixed at `SLEV`; some banks expect another value or none. - **BIC length**: some banks require 11-character BICs; the file accepts 8 or 11. - **References**: some banks restrict the characters and length of end-to-end IDs. Send your bank a sample file and ask for their validation before paying salaries with it. Bank-specific formats (DBS, OCBC, UOB and others) are not available. ## Bank details changed after computation A run records each employee's bank account when it is computed. If an account changes afterwards, submitting, approving or downloading the bank file tells you the run is out of date: - a run in review: withdraw it, recompute and submit again; - an approved run that is not paid yet: choose **Return to draft** on the run, give the reason, then recompute and approve it again. If a later run already used its CPF figures, use an adjustment instead; - a paid run: use an adjustment. An administrator changing someone's bank details needs a recent sign-in, and the employee is notified. Account holder names in Chinese, Tamil or another non-Latin script stop the file from being generated, with a message saying which. Enter the Latin spelling your bank has on record as the holder name, then recompute and approve again. Crow HR never strips such names from the file silently. --- # IR8A export > Export each employee's IR8A figures, and the Appendix 8A benefits-in-kind and Appendix 8B share-plan gains, from Crow HR in the column layout of IRAS's IR8A import template, for manual import in myTax Portal. Source: https://hr.crow.sg/docs/payroll/ir8a-export/ At year end, a payroll admin opens the IR8A panel on the **Payroll** page, chooses the income year and downloads the IR8A rows, plus the Appendix 8A and 8B rows for the benefits-in-kind and share-plan gains recorded under **Year end**. The downloads contain full NRIC/FIN numbers, so they need a recent sign-in. You paste them into IRAS's IR8A import template and import it in myTax Portal yourself. ## What you get - CSV rows in the column layout of IRAS's **IR8A import template (version 1.0)**, to paste at row 6 of the template's IR8A sheet. - For each part, up to three more files in the layout of the template's **Appendix 8A(Accommodation)**, **Appendix 8A(Hotel & Others)** and **Appendix 8B** sheets, to paste at row 2 of each. A button appears only when the part has rows for that sheet. - At most **200 records per part**; a 201st employee starts a second part with record numbers restarting at 1. Each part's appendix files hold the appendix rows of that part's employees, because one workbook imports at most 200 IR8A records with their appendices. - IR8A income rounded **down** and deductions rounded **up** to the dollar. Appendix 8A amounts keep their cents; Appendix 8B prices and share counts keep up to five decimal places. - Masked IDs on screen; the files carry the full IDs IRAS needs. Treat them like any other file with NRIC numbers. Crow HR does not fill or redistribute IRAS's workbook itself, because its licence is not confirmed. Download the template from IRAS. ### Pasting into the template IRAS's template protects its sheets, and its grey columns are locked: myTax fills them in after import (the IR8A sheet's d7, d8 and the "Appendix 8A indicator"; the appendix sheets' number of days, value and total columns, and the Appendix 8B gross amount). Crow HR leaves those columns empty. If your spreadsheet refuses to paste a row block over them, paste the columns on either side of each grey column separately. After import, check the totals myTax shows against the [IR8A totals on the Year end screen](#appendix-8a-and-8b-benefits-and-share-gains). ## Where the figures come from Approved payslips of the year plus the [year-to-date opening balances](https://hr.crow.sg/docs/people/importing/#year-to-date-opening-balances): | IR8A item | Filled from | | --- | --- | | (a) Gross salary, fees, leave pay, wages and overtime | Basic pay after no-pay leave, overtime, back pay and other earnings | | (b) Bonus | Bonus items, dated by their last pay date | | d1 Allowances | Allowances and cash reimbursements whose claim type is marked taxable | | d2 Commission | Commission items | | d7(a), d7(b) Share-plan gains | Appendix 8B records (myTax computes them from the 8B sheet) | | d8 Benefits-in-kind | Appendix 8A records (myTax computes them from the 8A sheets) | | Employee CPF | Employee CPF, including AW top-up recoveries | | SHG donations | SHG deductions | Back pay is reported in the year it was paid. An employee with appendix records but no pay in the year, such as a former employee with a share gain, gets an IR8A record with only those amounts. ## Appendix 8A and 8B: benefits and share gains Open **Payroll → IR8A panel → Benefits and share gains**, or go to **Year end** for the income year. Owners and payroll admins record, per employee: - **Appendix 8A (benefits-in-kind)**: each place of residence (one record per address and unbroken period, at most 10 a year), with its utilities, driver and servant costs; hotel stays; cars; and the other item 4 benefits (home leave passages, interest benefits, insurance premiums, holidays, education, club fees, gains from assets, a vehicle given, other non-monetary awards). - **Appendix 8B (share-plan gains)**: each ESOP exercise, or ESOW grant or vesting, in the year the gain accrues (at most 30 a year). Leave out benefits IRAS exempts or grants a concession for, such as group medical insurance or festive gifts up to S$200 for all staff ([IRAS list](https://www.iras.gov.sg/taxes/individual-income-tax/employers/understanding-the-tax-treatment/list-of-benefits-in-kind-granted-administrative-concession-or-exempt-from-income-tax)). Cash allowances, such as a housing or car allowance, are d1 allowances, not benefits-in-kind. Every saved record shows what Crow HR computed, item by item, marked **computed** or **entered**, with the working. Every change is audit-logged. ### What Crow HR computes, and what you enter Crow HR computes the values IRAS gives a formula for, using IRAS's [explanatory notes for Appendix 8A](https://www.iras.gov.sg/docs/default-source/individual-income-tax/employers/explanatory-notes-on-form-ir8a-and-appendix-8a-for-ya2027.pdf) and [Appendix 8B](https://www.iras.gov.sg/docs/default-source/individual-income-tax/employers/explanatory-notes-on-appendix-8b-for-ya2027.pdf), its pages on [accommodation](https://www.iras.gov.sg/taxes/individual-income-tax/employers/understanding-the-tax-treatment/accommodation-and-related-benefits) and [cars](https://www.iras.gov.sg/taxes/individual-income-tax/employers/understanding-the-tax-treatment/car-and-car-related-benefits), and the AIS data item rules. You enter the rest. | Item | Computed by Crow HR | You enter | | --- | --- | --- | | Days of occupation or car use | Both ends counted | The dates | | 2a Annual value, premises the employer owns | Annual value ÷ employees sharing × days ÷ 365 | The premises' annual value (property tax bill or e-Valuation List); or 2a itself if the annual value changed during the year | | 2b Furniture and fittings | 40% of 2a if partly furnished (fittings only), 50% if fully furnished | Partly or fully furnished | | 2c Rent, premises the employer rents | Rent ÷ employees sharing | Rent for the period, including furniture and fittings | | 2f Taxable value of the residence | 2a + 2b, or 2c, less rent the employee paid; not below zero | Rent the employee paid | | 2g Utilities, phone, gadgets; 2i servant, gardener | | Actual amounts | | 2h Driver | Annual cost × private km ÷ total km | Cost and mileage | | 3 Hotel stay | Cost less what the employee paid | Both amounts | | 4i Car | 3/7 × [(cost − PARF rebate) ÷ 10 × days ÷ days in the year + running costs] for a new car; ÷ years to COE expiry (rounded up) for a second-hand car; (renewal cost + PARF rebate forgone) ÷ 5 or 10 for a renewed COE; 3/7 × (rental + running costs) for a leased car | Costs, rebate, years and running costs | | 4a–4h, 4j | | The cost of each benefit. For 4b interest benefits, IRAS's rate is 3-month SORA + 1.5 points ([IRAS](https://www.iras.gov.sg/taxes/individual-income-tax/employers/understanding-the-tax-treatment/benefits-relating-to-loans)) | | 8B Gross gain | (open market value − price paid) × shares | Plan, grant date, the date the gain accrues, prices in S$ and shares | | 8B section | ESOP granted before 1 Jan 2003: S10(1)(g), IR8A d7(b); everything else S10(1)(b), d7(a) | | | IR8A d8, d7(a), d7(b) | Sum, decimals dropped | | Computed values are rounded **down to the cent**: IRAS publishes no rounding rule, and its worked examples truncate. With this rule Crow HR reproduces IRAS's examples to the dollar. For Appendix 8B, the gain accrues on the exercise date (ESOP), the vesting date (ESOW with vesting), the grant date (ESOW without vesting) or, with a selling moratorium, the day it is lifted. Use the SGX last done price on the listing date for listed shares, and the net asset value per share when there is no market price. Convert foreign prices to S$ at that day's rate, or at a source used consistently for all employees and years. IRAS does not take losses, and a loss can't offset another plan's gain. Fill in the granting company only when it isn't the employer. ### Not supported - **Premises the employer owns** (annual value basis): IRAS's import template has this method disabled, so the accommodation row leaves 2a and 2b empty. The IR8A panel notes the 2a and 2b values to enter in myTax after import. - **Leap years**: IRAS has not published how to apportion the annual value in a year of 366 days, so for income year 2028 Crow HR asks you to enter 2a yourself. - **ERIS** records (phased out after YA 2024; IRAS asks software not to send them), **QEEBR** tax deferral (the employee applies) and the **deemed exercise** rule for leaving foreigners (reported in their IR21, which Crow HR does not prepare). - Exchange rates, loan interest calculations and annual values are not looked up. - Benefits-in-kind don't appear on payslips or affect CPF. - Printed Appendix 8A and 8B forms for employers outside AIS. ## Not filled: complete these yourself - residential address (not recorded in Crow HR); - director's fees; - d3 gratuity, notice pay and similar (anything entered as "other earnings" lands in (a); move it by hand); - d6 excess or voluntary employer CPF; - tax borne by the employer, remission and exempt income; - 2a and 2b of premises the employer owns (see above). Employees with an ID type other than NRIC or FIN, or without a recorded sex, are left out of the IR8A and appendix files and listed with the reason. Leavers who needed IR21 tax clearance are only flagged; Crow HR does not prepare IR21. ## No direct submission Direct submission through IRAS's AIS API is **not available**. It requires IRAS to approve the software, plus Corppass and APEX credentials and whitelisted servers. The export is for manual import in myTax Portal, which the employer does. ## Taxable cash reimbursements A claim type's **Taxable benefit** flag marks its reimbursements as taxable cash benefits. Those enter d1; genuine business reimbursements stay out. The flag is recorded when payroll is computed, so changing a type later does not change past runs; claims paid outside payroll count in the year they were paid. A run replaced by an adjustment is counted once, as the adjustment. This follows [IRAS's Tax Principles and Flexible Benefits](https://www.iras.gov.sg/taxes/individual-income-tax/employers/understanding-the-tax-treatment/tax-principles-and-flexible-benefits): employers must track taxable benefits for IR8A. The flag does not determine whether a reimbursement legally attracts CPF. Non-cash benefits are recorded under Year end (Appendix 8A), and tax borne by the employer is entered in myTax. --- # How we verify statutory calculations > How Crow HR's CPF, SDL, SHG, FWL and Employment Act rules were checked - cited tables, CPF's worked examples, an independent recomputation and 15 cases confirmed in CPF's online calculator. Source: https://hr.crow.sg/docs/payroll/verification/ Singapore's statutory numbers live in one package, `packages/sg-rules`: pure, dependency-free TypeScript with effective-dated rule tables and calculators. This page summarises how they were checked. The full record, including every disagreement and how it was resolved, is [`packages/sg-rules/VERIFICATION.md`](https://github.com/Crow-Tech-Pte-Ltd/CrowHR/blob/main/packages/sg-rules/VERIFICATION.md) in the repository. :::note[What this does and does not mean] These checks show that the engine reproduces the official sources and examples listed below. They are not an approval: CPF Board, IRAS and MOM have not reviewed or endorsed Crow HR. You remain responsible for your payroll and filings. ::: ## Every number has a source Each constant (CPF rates and ceilings, SDL, SHG tables, FWL rates, Employment Act thresholds, public holidays) carries an effective date range and a source URL in the code. Every rule family has contiguous, non-overlapping date ranges from 1 January 2025, the engine's coverage start, which a test enforces. Where an agency does not publish a start date (CDAC, ECF and SINDA tables, some leave and levy rows), the row starts at 1 January 2025 and is marked as such: no earlier history is claimed. ## Checks against official material | Check | Result | | --- | --- | | CPF rate tables 1–5 for 2025, 2026 and 2027 (15 tables, 5 age bands each) | Machine-compared against the text of CPF's three rate PDFs: 0 mismatches. | | CPF internal consistency | For every cell: employer rate + employee rate = total rate; phase-in coefficient = 3 × employee rate; the phase-in formula meets the full-rate formula at S$750. | | CPF AW ceiling | All **16** worked examples in CPF's AW ceiling guide replayed month by month (about 150 months) with state carried between months as payroll does. Every month's OW subject, AW subject, total and employee share match CPF to the dollar, including rehires, AW paid after leaving, age-band changes and shortfalls. | | SDL | The S$2 minimum and S$11.25 maximum are continuous with 0.25%; start date and exemptions from SSG's SDL FAQ. | | FWL | MOM's published daily rates equal ceil(monthly × 12 / 365) for all 26 current rows. | | Working-day calendar | Reproduces all 36 cells of MOM's 2026 incomplete-month salary table (5, 5.5 and 6-day weeks). | | Research test vectors | 91 of 91 pass to the cent (62 CPF, 12 SDL, 17 SHG), after two fixture corrections found by the independent review. | The build fails if the tests of `packages/sg-rules` cover less than 95% of its lines. ## Independent review Two reviews were made separately from the implementation, by a second AI model working from primary CPF, MOM, IRAS and SSG sources rather than from the research notes. They are not a professional or agency review. - **Review of the statutory research data** (`research/verification/statutory-data-review.md`): recomputed all 91 vectors with a standalone Python script using integer and decimal arithmetic. It found real problems: AW keyed to the payment date instead of the *due and payable* date, a missing zero-wage branch and history for SDL, an AW fixture that overstated SDL, a 2028 rate table that does not exist, and an unsafe low-wage AW case. Each was fixed or turned into a refusal; the resolutions are listed in `VERIFICATION.md`. - **Payroll choices review** (`research/verification/payroll-choices.md`): checked seven legal and format choices in the payroll implementation (deduction limits, CPF recovery, the EZPay file, shift pro-ration, payslip items, payment deadlines, the bank file). Items marked wrong were fixed: pro-ration for rostered staff no longer guesses a week, overtime deadlines run from the period in which it was worked, payslips keep full names and every overtime period, the AW top-up recovery and its deadline are modelled, EZPay advice codes are stable. Items marked **unclear** are listed on the [limitations](https://hr.crow.sg/docs/payroll/limitations/#where-the-law-or-format-is-unclear) page. ## Confirmed in CPF's online calculator On 31 October 2026, 15 cases were run through CPF Board's public [CPF contribution calculator](https://www.cpf.gov.sg/employer/tools-and-services/calculators/cpf-contribution-calculator) and compared with the engine. **15 of 15 match to the dollar** on total, employee and employer share. | Case | Inputs | What it stresses | Total / employee / employer | | --- | --- | --- | --- | | RD-03 | Citizen, born 1996, Apr 2026, OW S$1,001.34 | Rate applied to the exact wage, no pre-rounding | S$370 / 200 / 170 | | RD-04 | Citizen, 65–70, Apr 2026, OW S$1,003.00 | Same, older age band | S$165 / 75 / 90 | | WB-02 | Citizen, Mar 2026, OW S$50.01 | Start of the employer-only band | S$9 / 0 / 9 | | WB-04 | Citizen, Mar 2026, OW S$500.01 | Start of the phase-in band | S$85 / 0 / 85 | | WB-06 | Citizen, Mar 2026, OW S$750.00 | Top of the phase-in band, S$277.50 rounds up | S$278 / 150 / 128 | | WB-08 | Citizen, Mar 2026, OW S$7,999.99 | Employer share = total − employee | S$2,960 / 1,599 / 1,361 | | WB-13 | Citizen, 65–70, Mar 2026, OW S$555.55 | Phase-in with fractional cents | S$62 / 12 / 50 | | SPR-10 | 1st-year SPR G/G, Mar 2026, OW S$1,700.00 | Band chosen on post-conversion OW | S$153 / 85 / 68 | | PM-01 | Citizen, May 2026, OW S$1,363.64 | Pro-rated wage | S$505 / 272 / 233 | | X-01 | Citizen, 55–60, Jun 2026, OW S$1,025.00 | Total exactly S$348.50 | S$349 / 184 / 165 | | X-02 | Citizen, 60–65, Jun 2026, OW S$1,002.00 | Total exactly S$250.50 | S$251 / 125 / 126 | | X-03 | Citizen, above 70, Jun 2026, OW S$633.33 | Pre-rounding would give S$68 | S$67 / 19 / 48 | | X-04 | Citizen, Dec 2026, OW S$4,321.09 + AW S$2,345.67 | Bonus month with cents | S$2,467 / 1,333 / 1,134 | | X-05 | 2nd-year SPR G/G, Jun 2026, OW S$612.34 | SPR phase-in band | S$106 / 50 / 56 | | X-06 | Citizen, 55–60, Feb 2027, OW S$1,100.00 | 2027 table | S$391 / 209 / 182 | What the calculator cannot check: it does not ask for the SPR date (so the SPR year and conversion-month pro-ration remain your inputs), it assumes the AW ceiling has already been applied, and it takes no year-to-date history. Those parts rest on CPF's AW ceiling examples above. ## Payroll tests On top of the engine, the payroll module has end-to-end tests with exact cents: a fictional 12-person company for October 2026 (every age band, SPR years 1 and 2, a foreigner, a joiner, a leaver, a bonus hitting the AW ceiling, no-pay leave, overtime, a deduction cap) and one employee from January to December 2026 with two bonuses and the December recomputation. Recomputing any stored result gives a byte-identical hash. ## Not verified - Overtime rounding: MOM publishes no rule; the default reproduces MOM's only worked example (S$13.60 an hour cap for non-workmen). - The CPF EZPay file and the bank file have not been accepted by CPF's or any bank's systems. - Anything listed on the [limitations](https://hr.crow.sg/docs/payroll/limitations/) page. --- # Limitations and what needs your judgement > What Crow HR does not do, statutory questions it cannot settle for you, and the results you must check before paying or filing. Source: https://hr.crow.sg/docs/payroll/limitations/ Crow HR computes what the cited rules say and shows its working, but some questions have no published answer, some inputs only you know, and some features are not built. This page lists them. Nothing here, or elsewhere in these docs, is legal, tax or CPF advice. ## Decisions that are yours Crow HR does not decide these; it computes from what you enter. - **OW or AW.** Each earning is marked ordinary or additional wages by the person entering it, and each allowance type is CPF-liable OW unless changed. Use CPF's guidance on [what constitutes wages](https://www.cpf.gov.sg/employer/employer-obligations/what-constitutes-wages-for-cpf-contributions). - **The date an AW became due and payable**, which keys the AW ceiling. - **Retroactive pay**: a later-decided increment is AW of the month paid; one paid late by mistake is OW of the original months and needs those months recomputed (reopen them as adjustments). - **Whether a deduction is permitted** under Employment Act s 27, and that you have the employee's written consent where needed. Crow HR checks the amount limits, not the legal basis. - **"Days worked"** for incomplete-month salary: whether outpatient sick leave or childcare leave counts is your policy. - **SPR rate options** (F/G, F/F): record them only after CPF approves the joint election. - **Opening balances** when you start mid-year: they drive the AW ceiling for the rest of the year. ## CPF - **2028 rates are not published.** From January 2028 the 2027 tables are carried forward with warning `CPF_RATES_ASSUMED_CARRIED_FORWARD`. Re-check when CPF publishes the new rates. - **Low-wage months with capped AW** (total wages above S$50 and up to S$750 with AW over the ceiling) are refused with `CPF_LOW_WAGE_CAPPED_AW_UNSUPPORTED`: CPF publishes no rule, so the run blocks for that employee. - **Open questions** (no official answer found): whether AW payable in one year but paid in the next also changes the rate table; whether a known leaving month should shorten the AW ceiling estimate before the last month; when an approved SPR F/G or F/F election takes effect and whether it can be reversed; mid-month changes of residency. - **AW top-up recovery** (CPF Act s 7(9)): the employee share of a top-up on earlier AW may be deducted with a "CPF AW recovery" item until 30 June of the following year; otherwise the employer bears it, shown as "Employee share absorbed". Remittance never waits for recovery. Recovering other CPF arrears caused by the employer is blocked; the s 7(6A) route (non-negligent error, with consent) and waivers for leavers are not supported. - **CPF late-payment interest** is not computed. ## Payroll inputs - **Fed inputs**: approved no-pay and other unpaid leave, approved overtime, rostered staff's days worked and scheduled days, and approved claims reach the run automatically ([items fed from other modules](https://hr.crow.sg/docs/payroll/running-payroll/#items-fed-from-other-modules)). **Approved claims are paid by payroll**: to pay one by transfer instead, mark it paid outside payroll under Claims before the run is computed, or it is paid twice. Hours for hourly-paid staff are still typed in. - **Fed overtime has no amount**: for employees not covered by Part 4, or paid by the hour, approved overtime from attendance blocks the run until you enter the contractual amount on the run ([holiday pay and contractual overtime](https://hr.crow.sg/docs/payroll/settings/#holiday-pay-and-contractual-overtime-on-a-run)). - **Rest-day and public-holiday work premiums** are entered by hand. Pay for a public holiday on an off day is automatic for monthly-paid staff on a fixed week; for hourly or rostered staff you enter the amount on the run. A holiday on a rest day gives a substitute day off. - **Leave encashment**, including days encashed at year end, is paid only after an approved request. The employee's active allowances must first be classified for the gross rate in **Payroll → Allowance treatment** ([allowance treatment](https://hr.crow.sg/docs/payroll/settings/#allowance-treatment)); for shift staff the request states the contractual average workdays per week. - **Back pay** from a retroactive change is flagged on the next run (`BACKPAY_OWED`) but not computed; enter the amount as a "Back pay" item. - **Staff without a fixed week** (rostered or shift) need scheduled days and days worked for an incomplete month; the run blocks without them. They come from published rosters and attendance when the whole month is covered, otherwise HR enters them. A mid-month rate change and SPR graduated-to-full conversion are blocked for these staff. - **Not handled**: daily-rated and piece-rated pay. - **Allowance types and recurring allowances** are added through the API; their treatment (CPF liability, pro-ration, gross rate) is set in **Payroll → Allowance treatment**. - **Adjustments do not recompute later months**; CPF's December (or last-month) AW recomputation absorbs the difference, and Crow HR warns when you reopen an earlier month. ## Employment Act checks - **Payment deadlines**: salary is checked against 7 days after the period (s 21(1)) and each overtime entry against 14 days after the period in which it was worked (s 21(2)). The Interpretation Act rule that moves a deadline falling on a Sunday or public holiday to the next day is not applied, so a run can be flagged a day early. Paying on a non-working day is allowed and only noted. - **Deduction limits**: accommodation, amenities and services share one 25% cap; damage or loss, advances and loans are 25% each; all deductions together 50%, with employee CPF and SHG counting towards it; the 50% limit is only a warning on final pay. - **Final pay timing** when the employer ends the employment (last day, or within 3 working days) is not checked yet. - **Overtime rounding** has no MOM rule; the default reproduces MOM's published example. ## Files you upload - **No direct submission** to CPF Board, IRAS or any bank. Crow HR produces files; you upload them. - **CPF EZPay file**: built from CPF's specification and a golden-file test, not confirmed by CPF Board or accepted in a live submission. See [CPF EZPay file](https://hr.crow.sg/docs/payroll/cpf-ezpay-file/). - **Bank file**: generic ISO 20022 `pain.001.001.03`, not mapped to any bank's guide and not tested with any bank. See [bank file](https://hr.crow.sg/docs/payroll/bank-file/). - **IR8A**: rows for IRAS's import template, with Appendix 8A and 8B rows from the benefits and share gains recorded under Year end; several items are not filled, owned-premises 2a and 2b are keyed in myTax, and AIS API submission is not available. See [IR8A export](https://hr.crow.sg/docs/payroll/ir8a-export/). - **Not available**: IR21 tax clearance, income tax withholding, bank-specific formats (DBS, OCBC, UOB and others), MOM or Myinfo integrations. ## Where the law or format is unclear The independent review of the payroll choices marked these as **unclear**: the available sources do not settle them. Crow HR's current choice is shown; check it against your own advice. | Question | Crow HR's choice | | --- | --- | | Should foreign employees' SHG appear in the EZPay file only as a fund summary, without detail records? | Summary record only; employees without an S/T number are listed for you to key in EZPay. | | How is a top-up on earlier AW encoded in the EZPay file when the month has no new AW? | Reported in the current month's CPF amount, with no new AW in that month's AW column. | | Is a pay date after the raw 7- or 14-day deadline always late, given the Interpretation Act rule for Sundays and public holidays? | Flagged as late on the raw count (may be a day early). | | Should the bank file set a service level (FAST/GIRO), and which charge bearer? | No service level; charge bearer `SLEV`. Depends on your bank. | | Are 8-character BICs and punctuation in references accepted? | Accepted by the generic file; some banks require 11 characters and plainer references. | ## Platform and sign-in - **Singpass** is tested against Singpass staging only (not production) and its button needs the official logo, which you add yourself. See [Singpass](https://hr.crow.sg/docs/admin/sso/singpass/). - **Invitation and password-reset emails are not retried**: they are sent once, because their one-time links are never stored. If one doesn't arrive, resend the invitation or have an owner create a reset link. Other emails are retried. - **Changing the sign-in email needs SMTP**: the new address is verified by a link, so a server without email can't change it ([changing your sign-in email](https://hr.crow.sg/docs/admin/sign-in-methods/#changing-your-sign-in-email)). An owner can't change someone else's sign-in email. - **No row-level security** in the database: isolation is enforced by the application and composite foreign keys, with a test that every route refuses another organisation's IDs. - **The common-password list** is a curated list of a few hundred entries plus patterns, not a breach corpus. - **Reverse proxies:** the Caddy, nginx and Traefik examples are tested automatically, with test certificates instead of Let's Encrypt; Cloudflare Tunnel was tested by hand ([reverse proxy](https://hr.crow.sg/docs/self-hosting/reverse-proxy/)). - **Virus scanning is optional**: configure your own clamd with `CLAMAV_HOST` / `CLAMAV_PORT` ([configuration](https://hr.crow.sg/docs/self-hosting/configuration/#optional-virus-scanning)) and receipts, documents and medical certificates are scanned in the background. Without it, uploads are stored unscanned. --- # Leave > Statutory and company leave in Crow HR - types and eligibility, policies, accrual and carry-forward, applying and approvals, public holidays in lieu, part-timers in hours, the Government-paid leave report and year end. Source: https://hr.crow.sg/docs/leave/leave/ **Leave** has two tabs: **My leave** (your balances, requests and children) and **Calendar** (your team's leave). Owners and HR admins set policies, holidays and rules under **Settings → Leave**. Statutory leave is set up for each organisation automatically from the Employment Act and the Government-paid leave schemes, the first time anyone opens Leave. The leave year is the **calendar year**. ## Leave types ### Statutory types | Type | Entitlement | Eligibility | Paid by | | --- | --- | --- | --- | | Annual leave | 7 days in the first year of service, rising by one day a year to 14 days from the 8th year | 3 months' service | Employer | | Sick leave (outpatient) | 5 days after 3 months' service, 8 after 4, 11 after 5, 14 from 6 months | 3 months' service | Employer | | Hospitalisation leave | 15, 30, 45, then 60 days on the same steps; outpatient days count towards the 60 | 3 months' service | Employer | | Maternity leave | Citizen child: 16 weeks (Government-Paid Maternity Leave). Other child: 12 weeks under the Employment Act | 3 months' service before the birth | Citizen child: employer weeks 1–8 and Government 9–16 for the 1st and 2nd child, Government all 16 from the 3rd. Other child: employer weeks 1–8, weeks 9–12 unpaid (all unpaid from the 3rd child) | | Paternity leave | Citizen child, father married to the mother: 4 weeks for births from 1 Apr 2025 (earlier dates use the rows in force then); 2 weeks for a stillbirth | 3 months' service | Government | | Shared parental leave | 6 weeks for children born from 1 Apr 2025, 10 weeks from 1 Apr 2026; not for a stillbirth | 3 months' service | Government | | Adoption leave | 12 weeks, for a citizen child under 12 months at the formal intent to adopt | 3 months' service | Employer weeks 1–4, Government 5–12; Government all 12 from the 3rd child | | Childcare leave | 6 days a year for a citizen child under 7 (pro-rated in the first year of service); 2 days under the Employment Act otherwise | 3 months' service | Citizen child: employer days 1–3, Government 4–6. Otherwise employer | | Extended childcare leave | 2 days a year for a citizen child aged 7 to 12, when there is no child under 7 | 3 months' service | Government | | Unpaid infant care leave | 12 days a year for a citizen child under 2, at most 24 days per child | 3 months' service | Unpaid | | NS (reservist) leave | No fixed allowance; needs the call-up notice | — | Employer, with make-up pay from MINDEF | | No-pay leave | No fixed allowance | — | Unpaid | Children's ages are taken on 1 January. Crow HR also creates **Compassionate leave** (3 days) as a company type you can change. Parental and childcare leave are per child. Employees add their children under **My leave → Children** (name, date of birth or due date, citizenship and birth order), and pick the child when they apply. ### Company types **Company leave type** under **Settings → Leave → Policies** adds your own type, such as birthday leave or study leave, with a code and name, paid or unpaid, half days, a supporting-document rule, whether it is private, and a policy. Company types count working days. They can be archived and restored; statutory types cannot be archived. ## Policies, accrual and carry-forward Each type's policy is edited from **Settings → Leave → Policies**: - **Entitlement**: **Statutory minimum**, **Same days every year**, **By years of service** (steps you add) or, for company types, **No fixed allowance**. - **Months of service before it can be used** (the Employment Act allows at most 3). - **Pro-rate in the first year and the year of leaving**. Annual leave is pro-rated by completed months in the first calendar year of service and the year of leaving, half a day or more rounding up; later years use the service year reached by 31 December. Each balance explains how it was worked out. - **Earned**: **All on 1 January**, or **Month by month** (completed months × yearly days ÷ 12, rounded down to a half day). With monthly accrual, a request is checked against what will have been earned by its last day. - **Carry unused days into next year**, **Up to (days)** (blank means all) and **Use within (months)** (blank means they never expire). Annual leave carries everything forward by default, to be used within 12 months. - **Allow leave encashment (including unused year-end days)**, and **Allow employees to request encashment** if staff may ask themselves (see [encash unused leave](#encash-unused-leave)). - **Allow half days**, **Private** (colleagues see only "On leave"), and the **Supporting document**: not asked for, optional or required. The Employment Act sets the floor, and Crow HR refuses a policy below it (`below_statutory`): annual leave below the statutory scale in any service year, sick leave below 14 days or hospitalisation below 60, more than 3 months' service required, or parental and childcare types moved off the statutory entitlement. Parental, childcare, infant care, NS and no-pay entitlements are fixed by law and can't be edited. **Settings → Leave → Rules** has three organisation-wide settings: | Setting | Options (default first) | | --- | --- | | A public holiday on an off day | **Pay an extra day (payroll); no day off**, or **Give the next working day off** | | No-pay leave and service | **Only months that are entirely no-pay leave**, **Any month with a day of no-pay leave**, or **Keep counting service** | | Comparable full-timer (for part-timers) | **The default work schedule**, or a fixed schedule you choose | MOM's guidance is ambiguous on whether one day of no-pay leave removes a whole month from the service count, hence the setting. ## Applying for leave **Apply for leave** on My leave opens the form: the leave type, the dates, the child where needed, an optional reason and the supporting document. For a single day, choose **Full day**, **Morning** or **Afternoon**; over several days, the first day can start **From noon** and the last day end **To noon**. ![Applying for annual leave: four days counted out of five, Monday being Deepavali in lieu, with the balance before and after (fictional company)](../../../assets/screens/leave-apply.webp) As you fill it in, Crow HR shows how many days the request takes from each leave year, what is available and what is left after it. **Show dates** lists each date and why any date is not counted (rest day, off day, public holiday, not rostered). Rest days, off days and public holidays are left out automatically; for maternity, paternity, shared parental and adoption leave, public holidays inside the leave count, as the schemes count weeks. A request is refused when it overlaps another pending or approved request (a morning and an afternoon don't clash), the balance after pending requests is too small, you are not eligible yet, the type doesn't allow half days, a date is outside your employment, no date is a working day, it spans more than 200 calendar days, or a required document is missing. Leave across 31 December is split between the two leave years. **Supporting documents** (PDF, JPEG, PNG, WebP or HEIC, up to 5 MB) are checked by their content. A medical certificate is required for outpatient sick and hospitalisation leave and an NS call-up notice for NS leave by default. Attachments can be opened only by the employee, owners, HR admins and an approver while their task on the request is open; to anyone else they don't exist. Uploads go through the same content checks and optional virus scan as other files. **On behalf**: owners and HR admins can apply for an employee (the form has an **Employee** field for them). The request is routed exactly as if the employee had made it and shows "Entered by HR". ### Approval Leave requests go through the approval engine as **Leave**, to the employee's **manager** by default (escalating after 3 days; to HR admins when there is no manager). Change the chain under **Settings → Approvals** ([approvals](https://hr.crow.sg/docs/approvals/approvals/)). Approvers decide from Home or the Inbox. The balance is checked again at approval: if it no longer covers the request, approval is refused until the request is rejected or the balance adjusted. - A pending request can be **withdrawn** by the employee. - An approved request can be cancelled with **Cancel leave** and a reason. That sends a **Leave cancellation** request for approval; the leave stays booked until it is approved, and then the days return to the balance. - Owners and HR admins can **Cancel leave now** without approval (not their own leave). It is recorded in the audit log. When leave is approved for a date where the employee already has a shift on a published roster, the roster's last publisher and the HR admins are told to reassign the shift. See [scheduling](https://hr.crow.sg/docs/scheduling/scheduling/). ## The calendar **Calendar** shows two weeks at a time by half day; pending requests have a dashed outline and public holidays are marked. - **My team** (managers) or **Everyone** (owners, HR admins, payroll admins) shows each person's leave type and pending requests, with a link to the request. - **Who's away** shows colleagues outside your scope too, but only approved leave, and only the type's name for non-private types. Private types show "On leave". Reasons are never shown. Outpatient sick, hospitalisation, maternity, unpaid infant care, compassionate and no-pay leave are private by default. ![The team calendar for two weeks, with sick, annual and paternity leave and a public holiday (fictional company)](../../../assets/screens/leave-team-calendar.webp) ## Public holidays and days in lieu Crow HR includes the gazetted public holidays for 2026 and 2027. Add extra holidays, such as Polling Day, under **Settings → Leave → Holidays → Add an extra holiday**. When a holiday doesn't fall on a working day, Crow HR follows MOM's rules for leave counting: - A holiday on a **Sunday** that is the rest day moves to the gazetted Monday. - A holiday on any other **rest day** moves to the next working day, shown as "Deepavali (in lieu)". - A holiday on an **off day** (for example a Saturday in a Monday-to-Friday week) depends on the rule above. With **Give the next working day off**, the next working day is a holiday in lieu and is not counted as leave. With **Pay an extra day (payroll); no day off**, no day off is created, and the extra day's salary is owed instead. :::note[How the extra day is paid] With **Pay an extra day (payroll)**, payroll adds one day's gross pay for the holiday to employees covered by the Employment Act who are paid monthly on a fixed week, once their allowances are classified for the gross rate ([allowance treatment](https://hr.crow.sg/docs/payroll/settings/#allowance-treatment)). For hourly-paid or rostered staff the run blocks until you enter the day's gross pay on the run ([holiday pay and contractual overtime](https://hr.crow.sg/docs/payroll/settings/#holiday-pay-and-contractual-overtime-on-a-run)). ::: ## Part-timers: leave in hours Employees whose employment type is **part-time** hold annual leave, sick and hospitalisation leave and company working-day types **in hours**, using MOM's formula: part-timer's weekly hours ÷ full-timer's weekly hours × full-timer's days × full-timer's hours a day rounded half up to one decimal place, as in MOM's examples. The comparable full-timer is the schedule named in **Rules**, or the default fixed schedule (its longest working day gives the hours a day; with neither, 44 hours a week and 8 a day). The part-timer's weekly hours come from their own work schedule. Each day of leave takes that day's scheduled hours, or half of them for a half day. The regulation's own rounding could not be confirmed, so balances in hours carry the warning `PT_LEAVE_ROUNDING_UNVERIFIED`. ## Government-paid leave report Employers pay Government-paid leave and claim it back from the Government. Crow HR can't submit these claims (the government portal has no API), so it lists what to claim: **Settings → Leave → Government-paid**, for owners, HR admins and payroll admins. ![Government-paid leave to claim: one paternity leave request with 20 Government-paid days and the date to claim by (fictional company)](../../../assets/screens/leave-government-paid.webp) Pick the dates. Each row shows the employee and child, the scheme and where to claim it, the dates, the employer-paid and Government-paid days in the period, and the **claim by** date (3 months after the last day of leave; NS make-up pay is claimed automatically by MINDEF). **CSV** downloads the same rows with the unpaid days and the claim route. Use it to fill in the claims on the government portal with Corppass. The report lists **days only**: it does not compute amounts or apply the schemes' weekly caps. For shared parental leave, Crow HR does not know how much the other parent has used; the parents' split is theirs to declare. ## Year end At the start of each new year, a background job closes the previous leave year for every employee, once: - unused days carry forward up to the policy's cap, and expire after the policy's period (carried days are used first, and expired days never carry forward again); - for employees covered by Part 4 of the Employment Act (monthly-paid, under the salary threshold), at least their unused statutory annual leave carries forward for 12 months, whatever the policy says; - the rest is forfeited or, where the policy allows encashment, recorded as encashed days. There is no button: it runs in the server's background jobs, and running it again changes nothing. Encashed days need an approved payout request before payroll pays them; use **Request payout** on the employee's Leave tab. ## How leave reaches payroll Approved leave of every **unpaid** type (no-pay leave, unpaid infant care leave and unpaid company types) goes to payroll automatically: each payroll run adds the approved days in its period, in half days, as items such as "No-pay leave (approved in Leave)", and payroll reduces salary for them. A no-pay leave item entered by hand on the run for the same date replaces the fed one. Leave being cancelled still counts until the cancellation is approved. The unpaid weeks of Employment Act maternity leave (weeks 9 to 12, for a non-citizen child) are not fed to payroll; enter them on the run. ## Encash unused leave Turn on **Allow leave encashment** in a paid leave type's policy (**Settings → Leave → Policies**). Turn on **Allow employees to request encashment** as well if staff may ask themselves; otherwise only HR can. - HR: **People → employee → Leave → Encash leave**. Employees: **Leave → Leave encashment → Encash leave**. Choose the type and quantity, and **Send for approval**. - Days encashed at year end have a **Request payout** action instead. They were deducted at year end and are not deducted again; if the payout is rejected or withdrawn, they go back to that year's balance. - A pending request holds its quantity. Approval deducts it from the balance; rejection or withdrawal releases it. Only a pending request can be withdrawn; an approved payout needs a payroll correction. - The request goes through [approvals](https://hr.crow.sg/docs/approvals/approvals/) as **Leave encashment**, to HR admins by default (escalating after 3 days). Only HR admins, payroll admins and owners can decide, and never on their own payout. - The card shows each request as awaiting approval, awaiting payroll, in payroll, paid, rejected or withdrawn, with the rate working. Approved encashment is paid by the next regular payroll run, or a leaver's off-cycle **Final pay** run ([running payroll](https://hr.crow.sg/docs/payroll/running-payroll/#leave-encashment)). **Rate.** Encashment uses the [MOM gross rate of pay](https://www.mom.gov.sg/employment-practices/salary/monthly-and-daily-salary): monthly gross is basic salary plus the fixed allowances included in the gross rate, in force when the request is made (on the last working day if the employee has left). For monthly-paid staff the daily gross rate is `12 × monthly gross / (52 × average workdays per week)`; the exact rate is multiplied by the days and rounded once, half up, to the cent. For example, S$2,600 basic plus a S$260 included allowance is S$2,860 monthly gross, S$132 a day on a five-day week, and S$330 for 2.5 days. - Each of the employee's active allowances must be classified as in or out of the gross rate first ([allowance treatment](https://hr.crow.sg/docs/payroll/settings/#allowance-treatment)); an unclassified one blocks the request and is named. - For shift staff, enter the contractual average workdays per week on the request; the approver checks it. - Balances kept in hours use the gross hourly rate: monthly gross × 12 / (52 × contractual weekly hours). For hourly-paid staff, the hourly equivalent of included monthly allowances is added to the hourly rate. - Later changes to salary, allowances or their classification don't reprice a request already made. **CPF.** [CPF is payable on encashed leave](https://www.cpf.gov.sg/service/article/are-cpf-contributions-payable-on-encashment-of-leave), including leave paid on termination: it is earned leave, not termination compensation, and accumulated leave is [additional wages](https://www.cpf.gov.sg/employer/employer-obligations/what-constitutes-wages-for-cpf-contributions). For payments after someone has left, [CPF's rules for ex-employees](https://www.cpf.gov.sg/service/article/are-cpf-contributions-payable-on-additional-wages-payable-to-ex-employees-after-they-have-left-employment) apply. ## Reports [Reports](https://hr.crow.sg/docs/reports/running-reports/) has **Leave taken** and **Leave balances and liability**, for owners, HR admins and managers (their team). ## Who can do what | Task | Owner, HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | | Apply for leave | Own, or for anyone | Own | Own | Own | | See requests and balances | Everyone | Everyone | Team | Own | | Policies, holidays, rules | Yes | — | — | — | | Government-paid report | Yes | Yes | — | — | ## Limitations - **Balance adjustments** and editing a child's record exist only in the API. - An employee can attach one document when applying; more, or later, only through the API. - **Shift workers**: dates in a week covered by the employee's published roster count only when they have a shift. Dates without a published roster count every day except public holidays, with a warning on the quote. Leave already applied for keeps its count even if the roster changes later. Parental leave assumes a 5-day week for shift workers. - Employment Act maternity leave for a non-citizen child approximates "fewer than 2 living children" by birth order. - The lifetime caps per child for childcare leave are not enforced, and the 2026 National Day Rally childcare changes are not applied. --- # Attendance and overtime > Clock in and out (also offline), optional location and office-network checks, timesheets and corrections, optional timesheet approval, lateness rules, overtime claims under Part 4 of the Employment Act, and how approved overtime reaches payroll. Source: https://hr.crow.sg/docs/attendance/attendance/ **Attendance** has up to five tabs: **Clock** and **My timesheet** for everyone with an employee record, **Team** for managers and HR, **Timesheets** for managers and HR when [timesheet approval](#timesheet-approval-optional) is on, and **Summary** for the period report. Owners and HR admins set the rules under **Settings → Attendance**. ## Clocking in and out **Clock** shows the time in Singapore, whether you are clocked in ("Clocked in since 08:45"), one big **Clock in** or **Clock out** button, and today's punches. Each punch is marked **OK**, or **Check** when it carries a flag (below). A punch your manager added says so. The time recorded is the moment you tapped, corrected to the server's clock: Crow HR stores the device time, the time the device sent the punch, the time the server received it, and the corrected time it uses for your timesheet. A punch that is sent twice (for example after a dropped connection) is recorded once. ### Working offline Punches work without a connection. A punch that can't be sent waits on the device and sends itself when the connection is back: on the next page load, when the browser comes back online, after your next tap, and every 30 seconds while the page is open. The screen says "1 punch waiting to send. Queued — will send when you're back online." Up to 200 punches can wait on one device. The queue is kept in the browser's local storage, so it survives closing the tab, but not clearing the site's data or switching device. ![Attendance on a phone: clocked in since 23:00, with one punch waiting to send while offline (fictional company)](../../../assets/screens/attendance-clock-offline.webp) A queued punch that the server refuses (for example, one more than 7 days old) moves to a **Not recorded** card with the reason and "Ask your manager to add it if it was right." ### Flags and refusals These are **refused**: - a punch more than **7 days** old ("Ask your manager to add it to your timesheet"); - a punch more than a minute in the future, by the server's clock. These are **flagged but never block**; the timesheet shows them and the punch is marked **Check**: - **Clock skew**: the device's clock was off by more than the allowed skew (default 2 minutes, set under **Settings → Attendance**). The punch is corrected to server time: "Device clock was off; corrected to server time". The skew is estimated as server time minus the device's send time, so a slow network adds its delay to the estimate. - **Late sync**: the punch reached the server more than 10 minutes after it was tapped (it waited offline). The tapped time is kept: "Sent late (offline); kept the time you tapped". - **Outside every office** or **from another network**, when those checks are set to flag (below). **Overnight work** is split at 04:00 Singapore time: a clock-out before 04:00 closes the previous day's open shift; anything later starts a new day. A published overnight shift follows the same rule. ## Location and office network (optional) Both checks are off by default. **Location** has three settings: **Don't collect location** (default), **Collect it when the device allows** and **Require it for every punch**. You can add up to 50 **offices** (name, latitude, longitude and a radius from 20 m to 5 km). **Outside every office** is either **Record and flag it** (default) or **Refuse the punch**, which tells the employee how far they are from the nearest office. Up to 50 m of the browser's reported accuracy is credited towards the radius. With no offices added, location is stored but not checked. When location is off, the browser does not ask for it, and the server drops any coordinates it is sent anyway. **Allowed IP ranges** takes up to 50 IPv4 or IPv6 ranges in CIDR form (empty means any network). **From another network** is again flag (default) or refuse ("You can only clock in from the office network…"). Location reported by a phone can be faked on a rooted or jailbroken device; office IP ranges are the stronger control. Every refusal tells the employee to ask their manager to add the punch, which a manager can do as a correction. :::note[PDPA notice] Location is personal data. Before an employee's first punch with location on, Crow HR shows a notice titled "Your location and clocking in", from your organisation, and the employee must confirm it before the punch is sent; they can reopen it from "Why?" on the Clock screen. The default text says the location and network are recorded only to check that the employee is at an approved work location, kept with their attendance records, seen by their manager and HR, and not used for anything else. You can replace it under **Settings → Attendance → PDPA notice**. Collect location only if you need it, and say so in your own data protection notice; see [privacy and PDPA](https://hr.crow.sg/docs/help/privacy-pdpa/). ::: ## Timesheets **My timesheet** shows one week (Monday to Sunday; with [timesheet approval](#timesheet-approval-optional) on, the approval period) with each day's type (working day, half day, off day, rest day, public holiday, leave, shift), first in, last out, hours worked, overtime and notes, and the week's totals: worked, overtime, late and missing punches. Timesheets are calculated from the punches whenever you open them; nothing is stored separately. **Team** shows one day for your team (managers) or everyone (owners, HR admins, payroll admins): "6 in · 1 late · 1 missing a punch". ### How a day is worked out - **Worked time** is first in to last out. For employees on a fixed week, the **unpaid break** (default 60 minutes) is taken off days longer than 6 hours; a rostered shift uses its own break instead. - **Late** and **early out** are measured against the scheduled start and end. They count only beyond the grace (default 5 minutes each), and then the whole difference counts, not just the minutes past the grace. Half-day leave in the morning skips the lateness check; in the afternoon, the early-out check. - **The scheduled start** is the **usual start** in settings (default 09:00) for fixed-week staff. For [rostered staff](https://hr.crow.sg/docs/scheduling/scheduling/#how-a-published-roster-is-used) on a date with a published roster, it is the shift's own start, end and break. Rostered staff without a published roster that week have no start time, so lateness and early out are not computed, and their scheduled time is a fifth of their weekly hours. - **Missing punch**: a day with a clock-in but no clock-out (or the reverse) is marked **Missing punch** and has no worked time until it is corrected. - Approved leave and public holidays show on the day. ### Corrections Managers correct their team's timesheets, and owners and HR admins anyone's, from **Team → Correct**: **Remove** a wrong punch, or **Add a punch** (clock in or out, the time in SGT and a reason of 3 to 300 characters, which the employee sees). Removed punches are kept, marked void. Every correction is audit-logged. Nobody can correct their own timesheet, whatever their role. Corrections have no 7-day limit. With timesheet approval on, days in an approved timesheet are [locked](#what-an-approved-timesheet-locks). ## Timesheet approval (optional) Off by default: until an owner or HR admin turns it on under **Settings → Attendance → Timesheet approval**, nothing is submitted or locked and managers and HR correct attendance directly. When it is on, each period's timesheet is submitted, approved and then locked. The setting chooses: - **Period**: **Calendar month** (default), **Half month** (1st–15th and 16th–end) or **Week** (Monday–Sunday). - **Who submits**: **The employee** (default; owners and HR admins can also submit on an employee's behalf), or **their manager or HR**. When managers submit, employees can't submit their own, and the manager who submitted a timesheet can't approve it: with the default chain it goes to the HR admins. ### Submitting **My timesheet** then shows a period instead of a week, with its status: **Not submitted**, **Waiting for approval**, **Approved**, **Returned**, **Withdrawn** or **Reopened**. A period can be submitted from 04:00 on the day after it ends (the overnight cut-off, so no shift can still be open); before that the screen says from when. **Submit for approval** records the period's totals and sends the timesheet through the **Timesheets** chain in **Settings → Approvals** (default: the employee's manager, escalating after 3 days). Submitting warns, without stopping you, about days with a missing punch, overtime not yet claimed and overtime claims still waiting. Claim overtime before the timesheet is approved. Home shows "Submit your timesheet for 1–31 Oct 2026" for the latest ended period until it is submitted; when managers submit, the manager sees "Submit 3 timesheets for 1–31 Oct 2026" instead. The employee, or whoever submitted it, can **Withdraw** a timesheet while it waits. ### Approving or returning Approvers find the task in the Inbox, with days worked, hours, overtime by the clock and claimed, late days, early outs, missing punches and leave days. **Attendance → Timesheets** lists everyone you can see for the period with their status and totals ("4 approved · 2 waiting (1 for you) · 3 to submit"); **Review** opens the person's days with **Approve** and **Return**. Returning needs a comment, which the employee sees; they get the days corrected and submit again. A timesheet waiting for approval is not locked: the manager can still correct punches, and what is approved is the figures at the moment of approval. The request says when the figures changed after it was sent. ### What an approved timesheet locks For the employee's days in an approved timesheet: - **punches are refused**, including punches queued offline that arrive later: "Your timesheet for 2–8 Nov 2026 is approved, so this punch can't be added. Ask HR to add it if it was right."; - **managers can't correct them**: those days show **Locked**, and the correction sheet says to ask an HR admin; - **new overtime claims** for those days are refused. Owners and HR admins can still correct a locked day. The correction sheet warns that saving reopens the timesheet, and the button reads **Add punch and reopen** (or **Remove and reopen**); through the API, send `reopen: true` (without it the API answers `409 timesheet_locked`). They can also **Reopen** an approved timesheet from **Timesheets**, with a reason. Reopening is audit-logged, the employee (and whoever submitted it) is notified, and the period must be submitted and approved again. Nobody can reopen their own timesheet. Turning timesheet approval off lifts every lock; approved timesheets stay as history. ## Overtime ### What counts as overtime On a working day (or a rostered shift), overtime is the time worked beyond the scheduled time. On a rest day, off day, public holiday or full day of leave, all time worked is overtime. Less than the **minimum OT** (default 30 minutes) is not overtime; the rest is rounded **down** to **OT blocks** (default 15 minutes). ### Claiming it Overtime is paid only when it is claimed and approved. On **My timesheet**, a day with overtime has **Claim OT**: enter the minutes (up to what the timesheet shows for that day) and, optionally, what it was for, then **Send for approval**. One claim can be open or approved per day. If the timesheet shows no overtime, fix the punches first. ![Claiming overtime for one day: up to 150 minutes, as worked against the 8 hours scheduled (fictional company)](../../../assets/screens/attendance-claim-ot.webp) A claim goes to the employee's **manager** by default (escalating after 3 days); change the chain under **Settings → Approvals** ([approvals](https://hr.crow.sg/docs/approvals/approvals/)). The approver sees the date, the claimed and timesheet minutes, the basis and the reason, and approves or rejects the whole claim; partial approval is not possible. A pending claim can be withdrawn from the request in the Inbox. ### Part 4 eligibility Each claim is marked **statutory** or **contractual** when it is made, using the statutory engine's Part 4 test of the Employment Act: the employment record must be marked as covered by the Employment Act, and basic monthly salary must be at most **S$4,500 for a workman** or **S$2,600 for anyone else**. Hourly-rated staff are compared using a monthly equivalent (hourly rate × weekly hours × 52 ÷ 12). A contractual claim says so: "Not covered by Part 4 … contractual (company policy)." ### The 72-hour monthly limit The Employment Act limits overtime to 72 hours a month unless MOM grants an exemption. When a claim would take the employee's pending and approved overtime for the month past 72 hours, the employee is warned and the approver sees "OT in October: 75 of 72 h (over the 72-hour monthly limit: lawful only with an MOM exemption)". It is a **warning only**: Crow HR does not know whether you hold an exemption, so it never blocks. ## How approved overtime reaches payroll Approved overtime goes to payroll automatically; nobody retypes it. - When a payroll run is computed, each **approved** claim whose date worked falls in the run's period becomes an item "Overtime (approved in attendance)" with its minutes and date. Approved claims from earlier periods that no run has paid yet are added too. - A claim approved after the run was computed makes **Submit for approval** fail with a request to recompute; the recompute picks it up. - A claim for October approved after October's run was approved is paid once, by whichever run is computed next: November's, or an [adjustment](https://hr.crow.sg/docs/payroll/running-payroll/#correcting-an-approved-or-paid-run) of October. Overtime must be paid within 14 days after the period in which it was worked and the run warns when it is late, so approve overtime before the month's run is submitted. - Bonus-only off-cycle runs ignore overtime. - For **monthly-rated employees covered by Part 4**, payroll computes the pay at 1.5 × the hourly basic rate, with the working shown in the CPF drawer, and checks it is paid within 14 days after the salary period. - Overtime typed in by hand on the run is still possible and is **added on top**; it does not replace the fed items, so don't enter the same hours twice. - **Days worked** for rostered staff who clock in also comes from attendance ("Days worked (from attendance)"): days with worked time, plus public holidays and paid leave; no-pay leave days don't count. A "Days worked" item entered by hand on the run takes precedence. See [scheduling](https://hr.crow.sg/docs/scheduling/scheduling/#payroll-scheduled-days). ### Payroll from approved timesheets only With timesheet approval on, **Payroll uses approved timesheets only** (off by default) limits both feeds: - an approved overtime claim reaches payroll only when its date is inside an approved timesheet. Overtime whose timesheet is approved later is paid by the next run computed, because payroll also reads unpaid overtime from earlier periods; - **days worked** reaches payroll only for rostered staff whose every employed day in the pay period is inside an approved timesheet. Otherwise the run has no days-worked item for them and, for an incomplete month, blocks as it does for staff who don't clock in: approve the timesheet (or enter the figure by hand) and recompute. Without it, payroll reads attendance as described above, approved timesheets or not. :::caution[Contractual and hourly-rated overtime] A fed overtime item carries minutes, not an amount. For an employee **not covered by Part 4** the run blocks with `OT_NOT_STATUTORY` ("Enter the contractual OT amount"), and for an **hourly-rated** employee with `OT_AMOUNT_REQUIRED`. The issue links to the employee's drawer in the run, where you enter the contractual amount for that overtime claim ([holiday pay and contractual overtime](https://hr.crow.sg/docs/payroll/settings/#holiday-pay-and-contractual-overtime-on-a-run)); it replaces the fed amount, so the overtime is paid once. ::: Work on a rest day or public holiday reaches payroll as plain overtime minutes. The separate rest-day and public-holiday pay rules (a day's or two days' basic pay, an extra day for a holiday) are shown as text on rosters but are not paid from attendance; enter them as items on the run. ## Summary report **Summary** lists, per employee for up to 62 days, days worked, hours, late days, early outs, missing punches, overtime by the clock, approved overtime and leave days, with a **CSV** download. Managers see their team. The same figures are in [Reports](https://hr.crow.sg/docs/reports/running-reports/) as "Lateness, missing punches and overtime". ## Settings → Attendance | Setting | Default | | --- | --- | | Location | Don't collect location | | PDPA notice | The standard notice (blank) | | Offices, and **Outside every office** | None; Record and flag it | | Allowed IP ranges, and **From another network** | Any network; flag | | Usual start (SGT) | 09:00 | | Unpaid break (min), taken off days over 6 hours | 60 | | Clock skew allowed (s) | 120 | | Late after (min) | 5 | | Early out grace (min) | 5 | | OT in blocks of (min), rounded down | 15 | | Minimum OT (min) | 30 | | Submit timesheets for approval | Off | | Period | Calendar month | | Who submits | The employee | | Payroll uses approved timesheets only | Off (needs approval on) | Office checks that refuse punches need location, so saving location off with offices set to refuse is refused. Every change is audit-logged. ## Who can do what | | Owner, HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | | Clock in, claim overtime | Own | — | Own (as an employee) | Own | | See timesheets | Everyone | Everyone | Team | Own | | Correct timesheets | Everyone except themselves | — | Team | — | | Submit a timesheet (approval on) | Anyone's, on their behalf | — | Team, when managers submit | Own, when employees submit | | Approve or return a timesheet | Their approval tasks | Their approval tasks | Their approval tasks | Their approval tasks | | Correct a locked day, reopen a timesheet | Everyone except themselves | — | — | — | | Attendance settings | Yes | — | — | — | Owners and HR admins can also file an overtime claim for an employee through the API; the web app files claims for yourself only. The full rules are in the [permission matrix](https://hr.crow.sg/docs/roles-and-permissions/). ## Limitations - Lateness for fixed-week staff is measured from one usual start time for the organisation; per-schedule start times exist in the API but have no screen. - After a claim is rejected or withdrawn, the day shows that status instead of **Claim OT**; a new claim for that day can only be made through the API. - The late-sync threshold (10 minutes) is fixed. - There is no list of all overtime claims in the web app; approvers work from the Inbox. - Timesheet approval is per organisation, not per team. Hours of hourly-rated staff are not taken from approved timesheets; payroll asks for them per run. - Leave approved after a timesheet is approved still shows on its days. The approved totals keep the figures that were approved, but payroll's days-worked figure is worked out from the days as they are. - Changing the period setting doesn't move timesheets already submitted; a new period that overlaps one waiting or approved can't be submitted until that one is withdrawn or reopened. - Home reminds you only of the latest ended period, without a due date. --- # Scheduling > Weekly shift rosters in Crow HR - shift templates, the week grid and its keyboard shortcuts, publishing, conflicts and hour warnings, swaps and open shifts, and how published rosters feed attendance, leave and payroll. Source: https://hr.crow.sg/docs/scheduling/scheduling/ **Schedules** is where managers and HR build weekly rosters for staff without a fixed working week, check them against leave, employment dates and the Employment Act's hour limits, and publish them. Staff see their published shifts under **My schedule** (the **Shifts** tab on a phone) and can ask to swap. Rosters matter for employees on a **shift** work schedule (see [work schedules](https://hr.crow.sg/docs/admin/company-and-structure/#work-schedules)). Employees on a fixed week can appear on a roster, but their attendance, leave and pay keep following their fixed schedule. ## Shift templates Owners and HR admins define the shifts managers pick from under **Settings → Shift templates** (**Add shift**): - a **Name** and a **Code** of 1 to 6 letters or digits (`AM`, `PM`, `OPN`), unique among active templates; - **Starts** and **Ends**; an end at or before the start means the shift ends the next day; - an **Unpaid break (minutes)**, shorter than the shift. **Paid time** is the length minus the break; - an optional **Location** (shown for reference; every template is offered on every roster); - a **Marker** colour, shown as a thin bar on the shift, never a filled cell. A location can have at most 30 active templates. A template in use can be archived, not deleted, and editing a template doesn't change shifts already on a roster. ## Building a roster A roster is one week (Monday to Sunday) for a **location**, a **department**, or a department at one location. Pick them at the top of **Schedules**, with the week; it opens on next week. The roster lists everyone employed in that scope during the week; it holds at most 150 employees (split it by department to roster more). ![The week grid for an outlet: shifts per person and day with their template codes, rest days, weekly hours per person and paid hours per day (fictional company)](../../../assets/screens/schedules-week-grid.webp) - **Click** an empty cell to add a shift there, or a shift to edit it. The editor takes a template or custom times and a break. - **Assign**: click a template in the toolbar, then click empty cells to fill them with it; **Stop assigning** ends it. - **Drag** a shift to another person or day to move it (it keeps its times). - **Rest day**: mark one cell per person per week as the rest day. - **Open shifts**: a shift with nobody on it goes in the **Open shifts** row, and anyone on the roster can ask to pick it up. - **Copy last week** copies the previous week's roster (including unpublished edits), skipping and naming anyone who has left, wasn't employed yet or already has a shift then. Managers copy only their team's shifts and open shifts. - **Clear week** removes every shift you can edit from the draft; what staff already see stays until you publish again. - **CSV** downloads the week (employee, date, start, end, break, paid minutes, template and conflicts), including unpublished edits. Each row shows the person's rostered hours for the week, and the footer the paid hours for each day. ### Keyboard shortcuts The grid works without a mouse. Tab into it, then: | Key | Action | | --- | --- | | Arrow keys | Move between cells | | Home / End | Jump to Monday / Sunday | | Enter or Space | Edit the cell's (first) shift, or add one | | 1 to 9 | Put the 1st to 9th template (in start-time order) in the cell, replacing its first shift | | R | Make the cell a rest day | | Delete or Backspace | Remove every shift in the cell | Below 1400 px wide, shifts show their times on two lines and drop the template code (it stays in the tooltip). On a phone, the grid becomes a list for one day at a time, with **Add shift** and **Off**; there is no keyboard or drag there. ### Who can edit Owners and HR admins edit any roster. A manager edits rosters where at least one of their team works, and can roster only their team, so a manager can't roster themselves. Two people editing the same roster see each other's changes when they reload; editing a shift that someone else changed in the meantime is refused with "Someone else changed this shift since you opened the roster. Reload and try again." A shift that overlaps another shift for the same person, on any roster, can't be saved. ## Publishing Staff see only the **published** roster, never the draft. The status beside the week says **Draft** (not visible to staff yet), **Published** (with its version) or **Unpublished changes** (staff still see the previous version). **Publish** (or **Publish changes**) opens a check: ![Publishing a week: warnings about a 45-hour week, no rest day, a 13-hour day and rest-day work, which can still be published (fictional company)](../../../assets/screens/schedules-publish.webp) - **Check these before publishing**: conflicts that must each be ticked to acknowledge them. Acknowledgements are recorded in the audit log. - **Warnings (you can still publish)**: hour and pay warnings. The first publish of a week notifies everyone with a shift ("Your schedule for the week of 2 Nov 2026 is published"). Publishing again notifies only the people whose shifts changed, with the old and new times ("Your shift on Wed 4 Nov 2026 changed from 09:00–17:00 to 10:00–18:00"). Notifications are in-app and by email when SMTP is set, to staff with a sign-in. ## Conflicts and hour warnings | What | Label on the grid | Effect | | --- | --- | --- | | Two shifts overlap for one person | Overlaps | Can't be saved | | Approved leave on the date (a half day is checked against the shift's hours) | On leave | Must be acknowledged to publish | | Before the start date or after the last day of employment | Not employed | Must be acknowledged to publish | | Pending leave on the date | Leave pending | Hint on the grid only | | Hours beyond normal daily hours (8 h when rostered more than 5 days that week, otherwise 9) | Overtime | Hint on the grid only | | A shift on a public holiday | Holiday name | Warning, with what Part 4 staff are owed | | A shift on the rest day | Rest day | Warning, with what Part 4 staff are owed | | More than 12 hours in a day | Over 12 h | Warning | | More than 44 normal hours in the week | Over 44 h | Warning | | Paid time on all 7 days | No rest day | Warning | | Projected overtime above 72 hours in the calendar month | Over 72 h OT | Warning | The hour warnings are planning checks from the Employment Act's limits, computed from rostered paid time across all rosters, drafts included. They show for everyone: Crow HR does not check whether each employee is covered by Part 4. The 72-hour check counts rostered overtime only; attendance checks claimed overtime separately. Without a marked rest day, the work schedule's rest day applies, or Sunday for shift schedules ("rest Sun (assumed)"). The rule that a rest day other than Sunday must be set before the month starts is not checked. The pay text on rest-day and public-holiday shifts (a day's or two days' basic pay for rest-day work, an extra day's pay for holiday work) is guidance from the statutory engine; payroll does not price these shifts from the roster. ## Swaps and open shifts Staff work from **My schedule**, which lists the next 14 days of published shifts ("Next week's schedule hasn't been published yet" when it isn't). - **Swap**: on one of your shifts, choose a colleague on the same roster and either **Swap for one of their shifts** or **Give it away**, with a note, and **Send request**. The colleague gets a notification and an item on Home ("Swap your Tue for Aaron's Wed?") to **Accept** or **Decline**. - **Pick up** an open shift from the **Open shifts** list. An accepted swap, or a pickup, goes for approval as a **Shift swaps** request, to the requester's **manager** by default (escalating after 2 days). On approval the shifts move in both the published roster and the draft, after checking again that nobody ends up overlapping or outside their employment; the published version number goes up. Rules: swaps stay within one roster; a shift with unpublished edits can't be offered until the roster is published again; one open request per shift. The requester can cancel before approval, and a request that is still open when the earlier shift starts expires. Editing, deleting or clearing a shift cancels its swap requests and tells both people. ## How a published roster is used Only published rosters count; drafts never do. For employees on a shift schedule: ### Attendance On a date with a published roster, lateness, early out and overtime in [attendance](https://hr.crow.sg/docs/attendance/attendance/) are measured against the shift: lateness from its start, early out from its end, with its own break. Work on an unrostered day or the rest day is all overtime. Without a published roster there is no start time, so lateness and early out are not computed. ### Leave In a week covered by a published roster, a leave request counts only the days with a shift; the date list says "Not rostered" or "Rest day" for the others. Weeks without a published roster count every day except public holidays, with a warning. The count is fixed when leave is applied for. When leave is approved after a roster was published, the roster's last publisher and the HR admins are told "Nadia Rahman's approved leave overlaps a published shift … Reassign the shifts or mark them open, then publish the roster again." The shift shows **On leave** in the editor and must be acknowledged at the next publish. Shifts are not removed automatically. ### Payroll scheduled days Payroll pro-rates an incomplete month for staff without a fixed week from their **scheduled days** and **days worked** (Employment Act s 20A). Crow HR supplies them: - **Scheduled days** come from published rosters ("Scheduled days (from published roster)"): the shift days, plus public holidays not on a rest day, plus approved leave days. They are supplied only when every date of the month has a published roster for the employee and the employee was employed for the whole month; otherwise HR enters them on the run (MOM's denominator is the whole month). - **Days worked** come from [attendance](https://hr.crow.sg/docs/attendance/attendance/#how-approved-overtime-reaches-payroll) for staff who clock in. - A "Scheduled days" or "Days worked" item entered by hand on the run wins over the fed one. - If days worked exceed scheduled days (for example work on an unrostered day), the run blocks with `ROSTER_DAYS_INVALID` for HR to decide. ## Reports [Reports](https://hr.crow.sg/docs/reports/running-reports/) has **Scheduled hours**: shifts, rest days and paid hours per employee from published rosters, for up to 62 days. ## Who can do what | | Owner, HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | | Shift templates | Edit | — | Use | — | | Rosters: build and publish | Any | — | Their team | — | | See published rosters | All | — | Their team | Rosters they are on | | Swap, give away, pick up | Own shifts | — | Own shifts | Own shifts | See the [permission matrix](https://hr.crow.sg/docs/roles-and-permissions/). ## Limitations - No real-time collaboration: changes appear on reload. - Drag moves a shift (no copy-drag). A cell can hold several shifts, but Enter, 1–9 and R act on the first one. - Open shifts are picked up through approval only; there is no first-come assignment. - The approver's link from a shift swap task opens My schedule, not the roster week, and notification links always open the next 14 days. - The CSV export is for editors only and includes unpublished edits; staff see the published roster on screen. --- # Claims > Expense claims in Crow HR - claim types and caps, receipts and upload checks, foreign currency, approvals, and reimbursement through payroll or outside it. Source: https://hr.crow.sg/docs/claims/claims/ Employees file expense claims under **Claims**, with a photo or PDF of each receipt. Claims go through [approvals](https://hr.crow.sg/docs/approvals/approvals/) and are then reimbursed with the next payroll run, or paid by transfer and recorded as paid. Owners and HR admins set up claim types under **Settings → Claim types**. ## Claim types A claim type has: - a **name** and a **code** (2 to 32 capitals, digits or underscores, such as `TRANSPORT`), used in approval rules and exports; - a **category**: medical, dental, transport, meals, entertainment, travel, phone, training or other. Medical receipts and details are shown only to HR, the employee and the current approver; - a **receipt rule**: **Always required**, **Required above an amount** (a line strictly above it) or **Not needed**; - an optional **cap** per employee: **Per claim**, **Per calendar month** or **Per calendar year**, one cap per type; - **Who can claim**: employment types (full-time, part-time, contract, intern; none ticked means everyone), and whether it is **Available during probation**; - whether **lines may carry GST**, whether it is a **taxable benefit**, how it is **paid** by default (**With payroll** or **By transfer, outside payroll**) and an optional **GL code** for your accounts. On an empty list, Crow HR offers a starter set you can edit: | Type | Receipt | Cap | Who can claim | | --- | --- | --- | --- | | Transport | Above S$20 | none | Everyone | | Meals | Above S$10 | none | Everyone | | Client entertainment | Always | none | Everyone | | Medical (outpatient) | Always | S$500 a year | Everyone | | Dental | Always | S$300 a year | Everyone | | Mobile phone | Always | S$50 a month | Full-time | Types are archived, not deleted, once used: an archived type disappears from the claim form, and a draft that still uses it can't be submitted. **Restore** brings it back. The **submission window** (default 90 days, from 7 to 730) is how long after the expense date a claim may be filed. Whether an employee can use a type (employment type, probation) is checked against their employment record as it is today, not on the expense date. ## Filing a claim **My claims** shows your claims and totals ("S$15.20 waiting for approval · S$0.00 to be paid · S$18.40 paid this year") with tabs for **Waiting**, **To be paid**, **Paid**, **Drafts** and **Closed**. **New claim** opens the claim form: ![The new claim form: snap a receipt or choose a file, then currency, amount, type, date, merchant and description (fictional company)](../../../assets/screens/claims-new-claim.webp) 1. **Snap receipt** (opens the phone camera) or **Choose file**. 2. Currency and amount, the type, the date, the merchant and a description. 3. **Add another expense** for more lines: a claim holds 1 to 30 lines, each with up to 5 receipts, and can mix types. 4. **Submit**, or **Save draft** to finish later. Drafts are only checked for structure; the full checks run on submit, and a claim that fails them stays as a draft. Submitting checks that each line's type is open to you, the date is not in the future or older than the submission window, required receipts are attached and every merchant is filled in. The claim then gets a number such as `C-0004`. Lists and exports sort claim numbers in number order, so `C-10000` comes after `C-9999`. ### Filing for an employee Owners and HR admins can file a claim for any employee, for example from a paper form or a receipt handed in at the office. **New claim** (on **My claims** or **All claims**; **New claim for an employee** if your account isn't linked to an employee record) has a **Claim for** field at the top: search by name or employee number, or keep **Me**. The claim types, caps and receipts then follow that employee: only the types they may use are offered, the remaining cap is theirs, and receipts are uploaded as theirs. Choosing another employee removes receipts already attached, because a receipt belongs to the employee it was uploaded for. The claim is the employee's: it goes to their approver, they see it under **My claims**, and either they or you can withdraw it while it is waiting. A draft you save for an employee stays theirs when you edit it. Only owners and HR admins see the **Claim for** field; managers and payroll admins file their own claims only. ### Caps Caps are per employee and type, counted by expense date in Singapore time (the calendar month or year of the expense). The form shows what is left as you type ("S$30.00 left of S$100.00 in October"). On submit, this claim plus your waiting, approved and paid claims must fit the cap; on approval it is checked again against approved and paid claims, so two claims that each fit cannot both be approved over the cap. The error names the numbers: "Mobile phone has a monthly cap of S$50.00: used S$35.50, pending S$0.00, remaining S$14.50 for October 2026. This claim asks for S$20.00. Reduce the amount to S$14.50 or less." ### Duplicate receipts A receipt file that is already attached to another submitted claim is flagged, not blocked: "Possible duplicate of claim C-0002: the same receipt image is attached there." The approver decides. ## Receipts - **Accepted**: PDF, JPEG, PNG, WebP and HEIC/HEIF, up to **10 MB**. The type is checked from the file's content, never its name or extension; anything else is refused with "This file is not a PDF or image. Upload a photo or PDF of the receipt". Files that look like a disguised web page, script or archive are refused too. - **Viewing**: JPEG, PNG and WebP receipts preview in the app. PDFs open in your PDF viewer, and HEIC files are stored but not previewed ("Preview not available. Download to view."). Downloads are served with the detected type and headers that stop the browser running them. - **Who sees them**: the employee, approvers, HR and payroll admins, and managers for their team; for medical and dental-category lines, only owners, HR admins, the employee and the approver whose task is open. - **Uploads never attached**: a receipt that is on no claim line (for example one removed from a draft, or left behind when a draft is deleted) is deleted once it is 7 days old. Receipts on any claim, drafts included, are kept. :::caution[Scanning is optional] Without a configured scanner, receipts are stored **unscanned** and usable after the content and size checks; owners see that scanning is off. With your own clamd configured (`CLAMAV_HOST` / `CLAMAV_PORT`), receipts are scanned in the background and must come back clean before the claim can be submitted. Infected files are removed and the uploader is notified; a receipt that can't be scanned after three attempts stays blocked. See [server configuration](https://hr.crow.sg/docs/self-hosting/configuration/#optional-virus-scanning). ::: ## Foreign currency Pick the currency on a line and enter the **rate in SGD per 1 unit** (up to 6 decimal places), for example the rate on your card statement. The form shows the SGD amount as you type. Crow HR does not fetch exchange rates. Each line is converted once and rounded half-up to the cent: MYR 125.50 at 0.301234 is S$37.80. The claim total is the sum of the rounded lines. Currencies without cents (JPY, KRW, VND) and with three decimals (KWD) are handled. GST can be entered only on SGD lines, from a tax invoice, and never more than the amount. Approvers see the original amount, the rate and the SGD amount ("MYR 125.50 @ 0.301234"). ### Unusual rates When a submitted claim's rate is more than 20% above or below the last rate used in your organisation for that currency, the claim page and the approval request show a warning: "MYR 0.400000 is 33.34% above the last MYR rate used, 0.300000 on 2 Nov 2026." It is a prompt to check the receipt or card statement, never a block; the approver decides. The last rate used is the rate on the most recently submitted other claim with a line in that currency, among claims submitted before this one that are still waiting, approved or paid (the last such line on it). Drafts, rejected and withdrawn claims don't count, nor do other lines of the same claim. Exactly 20% doesn't warn, and the first claim in a currency has nothing to compare with. ## Approval A submitted claim goes through the approval engine as a **Claims** request. The default chain is the employee's **manager**, then an **HR admin**, each escalating after 3 days. Under **Settings → Approvals** you can add rules, for example an extra owner step for claims of S$1,000 or more, or a different chain for certain claim types. A claim with several types is matched on its largest type by SGD amount. - Approvers decide from **Home** or the **Inbox**; the request links to the claim with its receipts and any duplicate flags. - Rejecting needs a comment, which the employee sees ("Not approved: …"). - The employee can withdraw a claim while it is waiting, and **Copy to new draft** a rejected or withdrawn claim to fix and resubmit it. **Claims → All claims** (owners, HR admins, payroll admins) or **Team claims** (managers) lists everything in scope with tabs **Waiting**, **To pay**, **Paid**, **Closed** and **All**, shows how many days a claim has been waiting, totals by expense date (by type, department, employee or month, with GST), and **Export** of the line register, totals and payout register as CSV or Excel. ## Reimbursement ### Through payroll Approved claims to be paid **with payroll** are added to the employee's next regular monthly run automatically: - A run picks up every approved, unpaid claim whose **approval date** (Singapore time) is on or before the last day of the run's month. The payroll cutoff day in payroll settings only drives the reminder; it does not hold claims back. - When the run is computed, those claims are reserved for it so no other run can pay them. Discarding a draft run releases them. - A claim approved **after the run was computed** but while it is still a draft makes **Submit for approval** fail with a request to recompute, which picks it up. - A claim approved **after the run was submitted**, or after the month ended, **rolls over** to the next month's run. - The payslip shows one line per claim type ("Claims reimbursement: Transport") under **Reimbursements (not wages)**. Reimbursements are not wages: they add to net pay but not gross pay, attract no CPF and exempt business reimbursements are not reported in IR8A. Cash reimbursements marked taxable are included in IR8A d1; review [tax classifications](https://hr.crow.sg/docs/payroll/ir8a-export/#taxable-cash-reimbursements). - When the run is marked **paid**, its claims become **Paid**, dated the run's pay date. Off-cycle bonus runs pay no claims; an off-cycle final-pay run pays the leaver's approved claims. An adjustment run of a month carries that month's claims over without paying any claim twice. ### Outside payroll Claims whose types are paid **by transfer**, or any approved claim you choose to pay yourself, are recorded on **Claims → All claims → To pay**. Tick the claims, **Mark N paid**, and enter the date paid and the bank or FAST/PayNow reference. Up to 200 claims at once; the batch is refused if any claim is already in a payroll run, paid or not approved. A claim marked paid outside payroll is never paid again by payroll. Each one is audit-logged with the reference. Only owners and payroll admins can mark claims paid. ![Marking an approved claim paid outside payroll with the date and FAST reference (fictional company)](../../../assets/screens/claims-mark-paid.webp) ## Who can do what | | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | File claims | Anyone | Anyone | Own | Own | Own | | See claims | All | All | All | Team | Own | | Edit claim types | Yes | Yes | — | — | — | | Mark paid outside payroll | Yes | — | Yes | — | — | | Claims report and exports | Yes | Yes | Yes | — | — | Owners and HR admins file claims for any employee ([Filing for an employee](#filing-for-an-employee)). See the [permission matrix](https://hr.crow.sg/docs/roles-and-permissions/). ## Claim reports **Reports → Claims** has five reports, each with CSV and Excel downloads: claims by type, department or month (with GST totals), claims waiting by age (more than 7 days flagged), cap usage by employee for a month, the payout register, and the claim lines register. Merchants, descriptions and receipt counts of medical lines are shown only to owners and HR admins; payroll admins see the amounts. See [Reports](https://hr.crow.sg/docs/reports/running-reports/) for how each figure is worked out. ## Not available - Automatic exchange rates. - Mileage or per-diem claim types, and corporate cards. - Non-cash benefits as claims: record them under Payroll → Year end ([Appendix 8A](https://hr.crow.sg/docs/payroll/ir8a-export/#appendix-8a-and-8b-benefits-and-share-gains)). The **Taxable benefit** flag covers cash reimbursements in IR8A d1. --- # Approvals > How Crow HR routes requests for approval - policies, steps, fallbacks, delegation, escalation - and where approvers act on them. Source: https://hr.crow.sg/docs/approvals/approvals/ Every request that needs a decision goes through one approval engine: - **profile changes** (employees' changes to legal, residency, race/religion and bank details); - **payroll runs**; - **leave**, **leave cancellation** ([leave](https://hr.crow.sg/docs/leave/leave/#approval)) and **leave encashment** ([encashment](https://hr.crow.sg/docs/leave/leave/#encash-unused-leave)); - **claims** ([claims](https://hr.crow.sg/docs/claims/claims/#approval)); - **overtime** claims ([attendance](https://hr.crow.sg/docs/attendance/attendance/#claiming-it)); - **timesheets**, when your organisation turns on [timesheet approval](https://hr.crow.sg/docs/attendance/attendance/#timesheet-approval-optional) (off by default; until then managers and HR correct attendance directly, without a request); - **shift swaps** and open-shift pickups ([scheduling](https://hr.crow.sg/docs/scheduling/scheduling/#swaps-and-open-shifts)); - employees' **employment letter requests** ([letters](https://hr.crow.sg/docs/documents/letters-and-kets/#employment-letter-requests)). ## Where approvers decide - **Home** lists everything waiting for you, overdue first, then by due date. Profile changes can be approved or rejected inline. - **Inbox** shows open tasks with the request's summary, the requester's context, the approval chain with its progress and earlier comments. ![Home: work to do, with approvals waiting, checklist items, an expiring work pass and a probation review (fictional company)](../../../assets/screens/home-work-to-do.webp) Rejecting needs a comment (1 to 500 characters); approving does not. When several people can decide a step, the first decision closes it and the others' tasks are marked superseded. Deciding a task that someone already decided gives `409 already_decided`. ## Policies Owners and HR admins edit the chain for each request type in **Settings → Approvals**. Only owners edit policies for payroll runs, compensation and profile changes (which include bank details). ![Settings → Approvals with the default chains and the out-of-office cover section (fictional company)](../../../assets/screens/settings-approvals.webp) A policy has: - an optional **condition**: an amount at or above a threshold, or a type code in a list; - a **priority** (the highest-priority matching policy wins, otherwise the default); - **1 to 5 steps**, each approved by the requester's **manager**, their **manager's manager**, anyone holding a **role** (HR admin, payroll admin, owner) or a **specific member**; - an **escalation** after N calendar days (default 3; 0 turns it off). Defaults, used until you edit them: | Request | Default chain | | --- | --- | | Payroll run | Owner | | Profile change | Bank details: payroll admin. Other fields: HR admin. | | Leave, leave cancellation, overtime, timesheets | Manager | | Leave encashment | HR admin | | Shift swap | Manager (escalates after 2 days) | | Employment letter request | HR admin | | Claims | Manager, then HR admin | The chain is copied onto each request when it is submitted, so editing a policy does not change requests already in flight. ## When a step has nobody A step is skipped (and the reason recorded) when it resolves to the requester themselves, to nobody (for example, no manager) or to a suspended or former member. If every step is skipped, the request goes to eligible HR admins, then owners. Payroll runs and bank changes fall back to owners. Only owners decide payroll runs; only payroll admins and owners decide bank changes. If no eligible member other than the requester exists, an owner who is the requester may decide, and the decision is marked **self-approved**. Explicit exclusions always apply, including to owners: someone who filed a request for another employee, benefits from a shift swap, or entered their own earnings in a payroll run cannot decide that request. If nobody eligible remains, the request stays pending. Appoint an uninvolved approver, then withdraw and resubmit the request to resolve its chain again. A request is never approved without a recorded decision by a member. ## Delegation (out-of-office cover) Anyone who approves requests (an approver role, or tasks waiting) can set cover from the Inbox: a delegate, a start and end date (inclusive) and optionally which request types. While cover is active, the delegate also gets the delegator's tasks; the delegator keeps them too. A delegate must be eligible for the subject and cannot be the requester, filer or an excluded beneficiary. Role-based steps only go to delegates who hold that role, and the delegate can read a request only while its task is open. HR admins can set cover for anyone in Settings → Approvals. ## Escalation and reassignment When a task passes its due time, its assignees get a reminder. Role steps escalate within that role, then to eligible owners, keeping the required role on the new task. Manager steps try the next manager, eligible HR admins, then owners. Every candidate must be allowed to decide that subject. This happens once per step. Owners and HR admins can reassign a pending task to another eligible member holding the task's required role, with a reason (HR admins cannot reassign payroll run tasks). Nobody can reassign a task on a request they made, filed or benefit from. When a requester's manager changes, open manager tasks move to the new manager. Suspending a member or making them former supersedes their open tasks, revokes cover to and from them, and re-resolves steps that have no approver left. Inactive members cannot act on approvals. ## Withdrawing A requester can withdraw a pending request; open tasks are superseded and the approvers are told. A payroll run in review can be withdrawn back to draft. ## Background processing Escalations, reminders, the email outbox and date-triggered changes (such as a leaver's membership becoming former) are processed by background jobs the server runs every 60 seconds. Nothing is processed twice, and after downtime the next run catches up. --- # Notifications and reminders > In-app and email notifications in Crow HR, what reminders are sent and what emails never contain. Source: https://hr.crow.sg/docs/approvals/notifications/ ## In the app The bell at the top right shows unread notifications. You are notified when: - a task is assigned, escalated or reassigned to you; - someone decides or withdraws one of your requests; - your payslips are released, or HR asks you to read and acknowledge a document; - a reminder is due (below); - something happens to your account's security, such as a sign-in from a new browser ([security notices](#security-notices)). Each notification links to what it is about. Notifications are kept for 180 days. ## By email Email is optional. When `SMTP_URL` and `MAIL_FROM` are set ([configuration](https://hr.crow.sg/docs/self-hosting/configuration/#email)), notifications are also emailed. Each person chooses which categories to receive in **Settings → Notifications** (all on by default). - Emails carry the organisation name, a short summary and a link. They **never** contain salary or other amounts, NRIC/FIN, bank or medical details. - They go through an outbox: a failed send is retried after 1, 5, 30, 120 and 720 minutes, then marked failed. Owners see failed emails and the SMTP status in Settings → Notifications. - Without SMTP, everything works in the app, and invitation and password-reset links are shown to copy. Invitation and password-reset emails are sent directly rather than through the outbox, because their links carry one-time tokens that Crow HR never stores; they are not retried. If one doesn't arrive, resend the invitation, or an owner creates a reset link to hand over. ## Security notices Security notices are in the **Security** category: they always appear in the app, with or without email, and are always emailed when SMTP is set (you can't turn them off). Each one says what happened and what to do if it wasn't you, and links to **My sessions**. You get one when: | Notice | Sent to | | --- | --- | | Someone signs in from a browser that hasn't been used with your account before (not your very first sign-in) | You | | The mobile app signs in on a new device, or an app session is ended because an old sign-in token was reused | You | | Your password is changed or reset, or an owner creates a reset link for you | You | | Sign-in from new devices is paused after many wrong passwords, or two-step verification is paused after wrong codes | You | | Two-step verification is turned on or off, or an owner resets it; a recovery code is used | You | | A single sign-on method is linked to or unlinked from your account | You | | Sign-in settings change: password sign-in on or off, who must use two-step verification, session timeouts, single sign-on methods added, changed or removed | Every owner, including the one who made the change | | Someone joins through single sign-on automatic sign-up (JIT) | HR admins (owners if there are none) | Notices never contain passwords, codes, IP addresses or other personal details. Every one of these events is also in the [audit log](https://hr.crow.sg/docs/admin/members-and-roles/#audit-log). ## Reminders Reminders are created once per subject and threshold, and stop when the condition is resolved: | Reminder | When | To | | --- | --- | --- | | Work pass expiry | 90, 60, 30 and 7 days before, and on the day | HR admins | | Probation ending | 14 days before | The employee's manager and HR admins | | Payroll cutoff | 3 days before the cutoff day in payroll settings (or the pay day), until the month's regular run is approved (a cutoff on the 1st to 3rd is reminded at the end of the month before) | Payroll admins | | Backups | Last successful backup more than 48 hours old, or scheduled backups disabled without `BACKUP_PASSPHRASE` (on Home) | Owners | | Document expiry | 30 and 7 days before, and on the day | HR admins, and the employee when the category is visible to them | | Acknowledgement | 3 and 7 days after HR asked, while not yet acknowledged | The employee | ## Home Home lists your actionable items from every source: approval tasks (including delegated and escalated ones), checklist items for your role, reminders, organisation setup steps and payroll due. With nothing to do it says "Nothing waiting for you". It never shows placeholder statistics. ## Not available Notification emails use fixed wording and do not carry the company logo. --- # Employee documents > Store contracts, passes, certificates and medical documents per employee in Crow HR, with category access rules, versions, expiry reminders and retention reviews. Source: https://hr.crow.sg/docs/documents/documents/ Each employee has a **Documents** tab on their profile. The **Documents** page has **My documents** (your own documents, acknowledgements and letter requests) and, for HR, **Expiring**, **Acknowledgements** and **Retention review** across the company. HR manages categories and letter templates under **Settings → Documents**. ## Categories and who sees what Every organisation starts with these categories: | Category | Sensitivity | Employee sees | Manager sees | Employee uploads | | --- | --- | --- | --- | --- | | Contract & KETs | normal | yes | no | no | | Identity & work pass | normal (views audited) | yes | no | yes | | Certificates & licences | normal | yes | yes | yes | | Medical | medical | yes | no | yes | | Letters | normal | yes | no | no | | Other | normal | no | no | no | Access follows the `documents` rows of the [permission matrix](https://hr.crow.sg/docs/roles-and-permissions/) and each category's flags: - **Owners and HR admins** see every category. - **Payroll admins** see only categories marked "visible to payroll" (none by default), never medical. - **Managers** see "manager-visible" categories for their own team, never medical. A medical category cannot be made manager-visible; the save fails and says why. - **Employees** see their own documents in employee-visible categories, medical included, and former employees keep read-only access to them. Anything outside your access answers `404`, exactly as if it did not exist. Every view or download of a medical or identity document is audit-logged. You can add categories, rename them and change their flags; a category that still holds documents, or is used by a letter template, cannot be deleted. ## Uploading - Accepted: PDF, JPEG, PNG, WebP, DOCX and XLSX, up to **20 MB**. The type is checked from the file's content, never its name. DOCX and XLSX must be real Office packages; macro-enabled files (`.docm`, `.xlsm`) are refused with "Macro-enabled documents are not accepted. Save as .docx or PDF". - Each document has a title (1 to 120 characters), a category, optional notes and an optional expiry date, which is required when the category says so. - HR uploads to any category for any employee. Employees upload only to their own employee-uploadable categories (Identity & work pass, Certificates & licences, Medical). - **Virus scanning is optional.** With your own clamd configured (`CLAMAV_HOST` / `CLAMAV_PORT`), uploads are scanned in the background; without it they are stored unscanned after the content and size checks. Crow HR does not bundle a scanner. See [configuration](https://hr.crow.sg/docs/self-hosting/configuration/#optional-virus-scanning). - Files are served as downloads (`Content-Disposition: attachment`, `X-Content-Type-Options: nosniff`); PDFs and images can also be opened in the browser. DOCX and XLSX are never rendered in the app. **Replace** creates a new version. The previous version is marked superseded and stays downloadable by HR under "Previous versions"; the employee sees only the current one. ## Expiry A document with an expiry date is **valid**, **expiring** (within 30 days) or **expired**, by today's date in Singapore. HR admins get a reminder 30 days before, 7 days before and on the expiry date; the employee gets it too when the category is visible to them. Each reminder is sent once. A newer version, or a newer document in the same category with a later expiry, stops the reminders for the old one. HR lists everything expiring or expired across the company, filtered by category, under **Documents → Expiring**. Home shows employees only acknowledgement requests, not expiring documents. ## Deleting and purging Deleting is soft: the document disappears from every list, and the deletion is audit-logged. Owners see deleted documents in **Documents → Deleted**, where they can purge one: give a reason and type the document title to confirm. Purging removes its files from storage and cannot be undone; only a record that the document existed remains, and the audit event records the reason and a hash of the original title. ## Retention review The Employment Act requires employment records to be kept for an ex-employee for one year after they leave ([MOM: employment records](https://www.mom.gov.sg/employment-practices/employment-records)). Crow HR flags an ex-employee's documents for review once the category's keeping period after the last working day has passed (12 months by default, set per category). Tax and CPF records may need longer, so you can raise the period for a category. Flagging is all it does. **Nothing is deleted automatically.** HR decides on each flagged document under **Documents → Retention review**: keep it for another 12 months (it is flagged again later) or delete it, which is the same soft delete as above, after which an owner may purge it. ## Not available - Company-wide documents not tied to an employee, such as a handbook library. - Full-text search inside documents, and OCR. - Payslips and IR8A forms live in payroll, not here; see [payslips](https://hr.crow.sg/docs/payroll/payslips/). Letters, KETs and acknowledgements are on the next page: [HR letters and KETs](https://hr.crow.sg/docs/documents/letters-and-kets/). --- # HR letters and KETs > Generate offer letters, Key Employment Terms, confirmation, salary-change and employment letters from templates, and collect employee acknowledgements. Source: https://hr.crow.sg/docs/documents/letters-and-kets/ Letters are generated from templates under **Settings → Documents**, rendered to PDF and filed as a document on the employee (Contract & KETs for offer letters and KETs, Letters for everything else), with the template version used. ## Templates Crow HR ships these templates, which you can reword: - Key Employment Terms - Offer letter - Confirmation of employment - Salary adjustment - Certificate of employment You can add your own (kinds: offer, KET, confirmation, promotion, salary adjustment, resignation acceptance, employment certificate, custom). Templates are written in a restricted Markdown, with a live preview in the editor: - `#`, `##` and `###` headings, paragraphs (line breaks are kept, for address blocks and sign-offs), `**bold**`, `*italic*`, bullet and numbered lists, pipe tables, and `\pagebreak` on its own line for a new page; - `https` links only; - merge fields written `{{namespace.field}}`, for example `{{employee.full_name}}`. Raw HTML, images (the company logo is added for you) and non-https links are refused when you save, with the line number. Merge fields are filled in after the template is parsed, so a value can never turn into formatting or markup. ## Merge fields Saving a template with an unknown field fails and names it, with a suggestion: "Unknown field employee.salary on line 12. Did you mean compensation.basic_pay?". The editor's field list shows them all: | Group | Fields | | --- | --- | | Company | legal name, UEN, address | | Employee | full name, preferred name, employee number, NRIC/FIN (masked), home address | | Employment | job title, department, location, place of work, manager, start date, employment type, probation end date and period, working days, daily working hours, rest day, last working day, notice period | | Pay (salary) | basic pay, pay basis, fixed allowances | | Contract terms | main duties, duration, salary period, fixed deductions, overtime payment period and rate, other salary components, types of leave, medical benefits, effective date of a change, purpose of a letter | | General | today's date, signatory name and job title | Values are formatted the Singapore way: `S$4,200.00 a month`, `31 Oct 2026`. The full NRIC/FIN is deliberately not a field; only the masked form (`S****567D`) is. **Contract terms** are things Crow HR doesn't store, such as main duties or medical benefits. Either write them into the template itself, or enter them when you generate the letter. Values entered for one document are saved on that document. ## Generating a letter Pick the template, the employee and an "as at" date (for example the start date for a KET); every field is resolved from the employee's records as at that date. If any field has no value, generation stops and lists what is missing and where to fill it, for example "Manager (set it on the employment record)". You can fill in a missing value for this document only. Templates that use **salary** fields can be generated only by an owner or a payroll admin (with salary access to that employee). An HR admin without payroll admin gets an error naming the salary fields. Generated documents are frozen: the PDF, the template and version, the as-at date and a snapshot of the values used (without salary fields) are kept. Generating again creates a new document. ## Key Employment Terms The KET template has a section for each of the items MOM requires in [Key Employment Terms](https://www.mom.gov.sg/employment-practices/contract-of-service/key-employment-terms), in MOM's order: 1. Full name of employer 2. Full name of employee 3. Job title, main duties and responsibilities 4. Start date of employment 5. Duration of employment (fixed-term contracts) 6. Working arrangements: daily working hours, working days per week, rest day 7. Salary period 8. Basic salary (or rate of pay) 9. Fixed allowances 10. Fixed deductions 11. Overtime payment period 12. Overtime rate of pay 13. Other salary-related components (bonuses, incentives) 14. Types of leave 15. Medical benefits 16. Probation period 17. Notice period 18. Place of work (optional) MOM allows items 11 and 12 to be left out for employees not entitled to overtime; enter "Not applicable" for them in that case. Each section is marked with an anchor such as ``. You can change the wording, but saving fails if a mandatory section or its merge fields are removed (place of work is optional). KETs must be issued in writing within 14 days of the start of employment. Generating a KET completes the employee's "Issue KETs" onboarding checklist item. ## Acknowledgements HR can ask an employee to read and acknowledge any document in a category they can see (generating a letter offers this too). The employee gets a notification and an item on Home. - They must open the document before **I acknowledge** works; acknowledging without opening it is refused (`409 not_viewed`). - The acknowledgement records the time, the IP address, the browser's user agent and the SHA-256 of the exact file version they opened. It cannot be withdrawn. - Reminders go to the employee 3 days and 7 days after the request if it is still open. - Replacing the document with a new version needs a new acknowledgement; the old one stays on record against the old version. HR sees outstanding and completed acknowledgements per document and per employee, and can download them as CSV. ## Employment letter requests Employees can ask for an employment letter (certificate of employment) from **Documents**, saying what it is for. The request goes through [approvals](https://hr.crow.sg/docs/approvals/approvals/) to HR. When HR approves, the letter is generated from the active certificate-of-employment template and filed in the employee's Letters, in the same step as the approval. If the letter can't be generated (for example a field is missing), the approval is refused with the reason. ## Limitations - Acknowledgement is not an electronic signature. There is no Singpass Sign or DocuSign integration. - *Italic* text prints in the regular typeface in PDFs (the embedded fonts have no italic face). - The company logo is printed only when it is a PNG. - Letters are PDF only; there is no DOCX output. --- # Reports > The reports Crow HR ships, who can run each one, the exact formulas behind the numbers, and the CSV and XLSX exports. Source: https://hr.crow.sg/docs/reports/running-reports/ **Reports** lists the reports you may run, grouped by the module that supplies the data. Each report has its parameters at the top, then a dense table (50 rows per page, sortable by any column, a totals row where totals make sense), the rules behind the numbers, and **CSV** and **Excel** (XLSX) download buttons. Where it helps, a simple bar chart follows the table; the table always comes first. ## The reports | Report | What it shows | Who can run it | | --- | --- | --- | | Headcount | Employees on the books on a date, grouped by department, location, employment type, residency or work pass, with the share of the total. Optional monthly basic pay column. | Owner, HR admin | | Headcount over time | Headcount at the end of each month (up to 36 months), with joiners and leavers in the month | Owner, HR admin | | Joiners, leavers and turnover | Everyone who joined or left in a period, the reason for leaving, and the turnover rate | Owner, HR admin | | Work pass expiry | Current employees' latest work passes that have expired or expire by a date, soonest first | Owner, HR admin, payroll admin | | Leave taken | Approved leave in a period by leave type, by department and type, or by employee and type | Owner, HR admin; managers for their team | | Leave balances and liability | Entitlement, carried forward, taken, pending and available leave as at a date, and the annual leave liability | Owner, HR admin; managers for their team | | Lateness, missing punches and overtime | Days worked, hours, late days and minutes, early outs, missing punches, timesheet and approved overtime hours (up to 62 days) | Owner, HR admin; managers for their team | | Scheduled hours | Shifts, rest days and paid hours per employee from published rosters (up to 62 days); drafts never count | Owner, HR admin; managers for their team | | Claims by type, department or month | Claim amounts and GST by expense date, per status | Owner, HR admin, payroll admin | | Claims waiting, by age | Claims waiting for approval or payment and how many days each has waited; waiting more than 7 days is flagged | Owner, HR admin, payroll admin | | Cap usage by employee | For each employee and capped claim type in a month (yearly caps: that year): cap, used, pending, remaining and the share taken up | Owner, HR admin, payroll admin | | Claims payout register | Paid claims with the payment date, payroll or outside payroll, and the reference | Owner, HR admin, payroll admin | | Claim lines register | Every submitted claim line with merchant, description, amount, SGD, GST and receipt count | Owner, HR admin, payroll admin | | Payroll cost | Gross pay, employer CPF, SDL, FWL estimate and total employer cost by month and department | Owner, payroll admin | The permissions come from the server's [permission matrix](https://hr.crow.sg/docs/roles-and-permissions/) (`reports_people`, `reports_leave`, `reports_attendance`, `reports_claims`, `reports_payroll_cost`, `work_pass` for the expiry list, and `rosters` for scheduled hours). A report you may not run answers `403`; a report from a module that isn't installed answers `404`. Reports never run at "own" scope: an employee's own data is on their own pages. ## Scope and sensitive columns - **Managers** see only their team (their direct and indirect reports) in leave and attendance reports. Totals are computed over the rows you can see, never over the whole company. - **Salary columns** (headcount's monthly basic pay, leave liability, every payroll cost amount) need salary access to every employee in the report. An HR admin who is not also a payroll admin gets the report without those columns; the response and the export list them in `redactedColumns` (for example `basicPay`). An HR admin who also holds payroll admin sees them. - **Work pass numbers** in the work pass expiry list are an identity field: readers without access to personal details get the list without them, listed in `redactedColumns` the same way. - Viewing a report that shows sensitive columns (salary or work pass numbers) is audit-logged (`report.viewed`), and so is every export (`report.exported`, with the parameters, the row count and the columns left out). ## How the numbers are worked out **Headcount** counts an employee on a date when a tenure has a start date on or before the date and either no last working day or a last working day on or after it. Someone whose last day is 31 Oct 2026 is counted on 31 Oct and not on 1 Nov; someone starting later is not counted yet. Department, location and employment type are the ones on the employment record in force on the date. Percentages are to one decimal place, rounded half-up. **Turnover rate** = leavers in the period ÷ ((headcount at the start + headcount at the end) ÷ 2) × 100, to one decimal place, rounded half-up. With 40 people on 1 Jan, 44 on 31 Dec and 6 leavers, turnover is 6 ÷ 42 × 100 = 14.3%. When the average headcount is 0 the rate is shown as "n/a". A rehire counts as a joiner on the rehire date. Leavers are split into voluntary (resignation, retirement), involuntary (dismissal, retrenchment, contract end) and other (death, mutual agreement, or no reason recorded). **Payroll cost** reads only finalised runs (approved or paid). A month with only a draft or in-review run shows no figures and the note "No finalised payroll for Nov 2026". The totals reconcile with payroll to the cent: - gross pay, employer CPF, FWL, employee CPF and SHG are summed over the payslips of the month's effective runs; a run replaced by an adjustment run counts once, as the adjustment; - SDL is the employer's monthly total exactly as payroll charged it (rounded once for the whole company), split across departments in proportion to each employee's SDL-liable wages; the cents left over by rounding go to the departments with the largest remainders, so the departments always add up to the month's SDL; - employer total = gross pay + employer CPF (+ any employee CPF share the employer bore) + SDL + FWL; - the department is the one on each payslip's employment snapshot (as at the end of the pay period). FWL is an estimate from the levy settings, as on the [SHG, SDL and FWL](https://hr.crow.sg/docs/payroll/shg-sdl-fwl/) page; payroll never deducts it. Employee CPF and SHG are shown as deductions, not as employer cost. **Leave liability** = available annual leave days × daily basic rate, where the daily rate is 12 × monthly basic salary ÷ (52 × working days a week), the Employment Act formula, rounded half-up to the cent. Hourly and daily-rated employees show no liability. Balances are for the leave year of the date, and pending requests are not counted as available. **Leave taken** counts approved leave days in the period (half days as 0.5), with the department on each leave day. **Claims** leave out drafts, take the department on each expense date and count medical claims in every total. In the claim lines register, merchants, descriptions and receipt counts of medical lines are shown only to owners and HR admins (a payroll admin sees "Medical, hidden" and the amount). **Cap usage** counts approved and paid claims as used and submitted claims as pending, by expense date; remaining = cap − used − pending, never below zero. **Days waiting** counts whole days since submission, or since approval for claims approved but not yet paid. ## Exports Every export holds the full result, not just the page on screen, with the same columns and redactions. - **CSV**: UTF-8 with a byte-order mark (so Excel on Windows reads it correctly), comma-separated, RFC 4180 quoting, a header row of column titles, dates as `YYYY-MM-DD`, money as plain decimals with two places and no symbol (`1234.56`), percentages with one place. Text cells starting with `=`, `+`, `-` or `@` get a leading apostrophe so a spreadsheet cannot run them as formulas. - **XLSX**: typed cells, money as numbers formatted `#,##0.00` (123456 cents is the number 1234.56), dates as real dates formatted `dd mmm yyyy`, a bold frozen header row with filters, a totals row, and a second sheet "Parameters" with the report, its parameters, the columns left out, who generated it and when. An export of more than 50,000 rows is refused with `422 too_many_rows`; narrow the dates or pick a smaller group. ## Not available - Custom report builders, saved views, scheduled or emailed reports. - The chart shows the rows on the current page of the table, not the whole result. - Cost-centre breakdowns of payroll cost (payslips record the department only). - The CPF EZPay file, bank file and IR8A export are payroll files, not reports; see [running payroll](https://hr.crow.sg/docs/payroll/running-payroll/). --- # Roles and permissions > Crow HR's permission matrix - which role can read or change what, with which scope - generated from the server's source code. Source: https://hr.crow.sg/docs/roles-and-permissions/ Crow HR checks every API request on the server against one permission matrix before it reads any data. Hiding a button in the web app is cosmetic; the server decides. The table below is generated from that matrix (`packages/core/src/access/matrix.ts`) when the docs are built, so it is always the version the code enforces. ## Roles - **Owner**, **HR admin** and **payroll admin** are granted by an owner. One person can hold several. - **Manager** applies automatically while the member's employee record has at least one active direct report. Their *team* is everyone whose current reporting chain leads to them, at any depth, but not themselves. - **Employee** applies automatically when the member is linked to an employee record. A member's rights are the union of their roles. See [members and roles](https://hr.crow.sg/docs/admin/members-and-roles/) for how roles are granted. ## The matrix 71 permissions in 32 areas. Cells: All = every record in the organisation, Team = the member's direct and indirect reports (not themselves), Own = their own records, Assigned = only items they are the assigned approver for, and a dash = denied. ### Security settings (sign-in methods, SSO, MFA policy, timeouts) | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `security_settings:read` | All | — | — | — | — | | `security_settings:update` | All | — | — | — | — | ### Members and invitations | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `members:read` | All | All | All | — | — | | `members:create` (hr_admin may only invite members with no assigned roles.) | All | All | — | — | — | | `members:update` (hr_admin may not grant or revoke roles.) | All | All | — | — | — | ### Role grants | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `member_roles:grant` | All | — | — | — | — | ### Company profile and structure | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `org_structure:read` | All | All | All | All | All | | `org_structure:create` | All | All | — | — | — | | `org_structure:update` | All | All | — | — | — | | `org_structure:archive` | All | All | — | — | — | ### Employee directory | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `directory:read` | All | All | All | All | All | ### Employment records and lifecycle | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `employment:read` | All | All | All | Team | Own | | `employment:create` | All | All | — | — | — | | `employment:update` | All | All | — | — | — | ### Personal details | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `personal_details:read` | All | All | All | — | Own | | `personal_details:update` (Employees update via change request where required.) | All | All | — | — | Own | ### Emergency contacts | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `emergency_contacts:read` | All | All | — | Team | Own | | `emergency_contacts:update` | All | All | — | — | Own | ### Work passes | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `work_pass:read` | All | All | All | — | Own | | `work_pass:create` | All | All | — | — | — | | `work_pass:update` | All | All | — | — | — | ### Compensation | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `compensation:read` | All | — | All | — | Own | | `compensation:create` (Nobody changes their own compensation directly.) | All | — | All | — | — | | `compensation:update` (Nobody changes their own compensation directly.) | All | — | All | — | — | ### Bank details | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `bank_details:read` | All | — | All | — | Own | | `bank_details:update` (Own bank details change only via change request.) | All | — | All | — | Own | ### Payroll runs and statutory files | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `payroll:read` | All | — | All | — | — | | `payroll:create` | All | — | All | — | — | | `payroll:update` | All | — | All | — | — | | `payroll:finalise` | All | — | All | — | — | ### Payslips and tax forms | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `payslips:read` (Employees see released ones only.) | All | — | All | — | Own | ### Leave | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `leave:read` | All | All | All | Team | Own | | `leave:create` (owner and hr_admin create on behalf of employees.) | All | All | — | — | Own | | `leave:update` (Nobody adjusts their own balance.) | All | All | — | — | — | ### Government-paid leave report | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `leave_claims:read` | All | All | All | — | — | ### Claims | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `claims:read` | All | All | All | Team | Own | | `claims:create` (owner and hr_admin create on behalf of employees.) | All | All | — | — | Own | | `claims:pay` | All | — | All | — | — | ### Attendance, overtime and timesheets | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `attendance:read` | All | All | All | Team | Own | | `attendance:create` (owner and hr_admin create on behalf of employees.) | All | All | — | — | Own | | `attendance:update` (Nobody corrects their own timesheet.) | All | All | — | Team | — | | `attendance:reopen` (Nobody reopens their own timesheet.) | All | All | — | — | — | ### Approval tasks | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `approval_tasks:decide` | Assigned | Assigned | Assigned | Assigned | Assigned | | `approval_tasks:reassign` (hr_admin may not reassign payroll_run tasks.) | All | All | — | — | — | ### Out-of-office cover for others | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `approval_delegations:manage` | All | All | — | — | — | ### Email delivery status | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `notification_delivery:read` | All | — | — | — | — | ### Rosters and shifts | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `rosters:read` (Employees also see the published roster of their own location.) | All | All | — | Team | Own | | `rosters:create` | All | All | — | Team | — | | `rosters:update` | All | All | — | Team | — | | `rosters:publish` | All | All | — | Team | — | ### Shift templates | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `shift_templates:update` | All | All | — | — | — | ### Shift swaps and open-shift pickup | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `shift_swaps:create` (Only for the employee's own published shifts.) | — | — | — | — | Own | ### Documents | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `documents:read` (payroll_admin: payroll-visible categories; manager: manager-visible categories, never medical; employee: employee-visible categories.) | All | All | All | Team | Own | | `documents:create` (Employees upload to employee-uploadable categories only.) | All | All | — | — | Own | | `documents:update` | All | All | — | — | — | | `documents:delete` | All | All | — | — | — | ### Approval policies, leave and claim types | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `policies:read` | All | All | — | — | — | | `policies:update` | All | All | — | — | — | ### Claim types | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `claim_types:read` | All | All | All | — | — | ### People reports | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `reports_people:read` (Headcount and turnover.) | All | All | — | — | — | | `reports_people:export` | All | All | — | — | — | ### Leave reports | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `reports_leave:read` | All | All | — | Team | — | | `reports_leave:export` | All | All | — | Team | — | ### Attendance reports | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `reports_attendance:read` | All | All | — | Team | — | | `reports_attendance:export` | All | All | — | Team | — | ### Claims reports | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `reports_claims:read` | All | All | All | — | — | | `reports_claims:export` | All | All | All | — | — | ### Payroll cost reports | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `reports_payroll_cost:read` | All | — | All | — | — | | `reports_payroll_cost:export` | All | — | All | — | — | ### Audit log | Permission | Owner | HR admin | Payroll admin | Manager | Employee | | --- | --- | --- | --- | --- | --- | | `audit_log:read` (hr_admin: non-security, non-payroll events; payroll_admin: payroll, compensation and bank events.) | All | All | All | — | — | | `audit_log:export` | All | All | All | — | — | ## Rules on top of the matrix - **Records outside your scope look missing.** A record of another organisation, or outside your team or own records, answers `404`, so its existence is never revealed. A permission you do not have at all answers `403`. - **Sensitive fields** carry a class: `salary`, `nric`, `bank` or `medical`. You receive a sensitive field only if the matrix gives you its resource (compensation, personal details, bank details). `medical` is further limited to owners, HR admins, the employee and the approver assigned to that item. Fields you may not read are left out and listed in `redactedFields`. Exports apply the same rules. - **NRIC/FIN and bank numbers** are masked; revealing one needs a recent sign-in, is limited to 30 per hour and is audited. - **Segregation of duties**: nobody changes their own compensation or bank details directly, whatever their role, and nobody decides their own approval request, except an owner when no one else is eligible (recorded as self-approved). - **Former members** keep read-only access to their own released payslips and employee-visible documents. - **Install-level** information (Settings → System) is visible to owners only. - **Rosters**: managers see leave status and employee numbers on a roster only for their own reports, and can publish roster changes only for them; HR publishes changes that affect other teams. - **Children's records** (for parental and childcare leave) need personal-details access. A manager reviewing a leave request sees whether the employee is eligible, not the child's details. --- # Integrations > What Crow HR connects to today (SSO, SMTP, file storage, files for CPF, banks and IRAS) and what is not available (IRAS AIS API, bank-specific formats, Myinfo). Source: https://hr.crow.sg/docs/integrations/ Crow HR is designed to run without any external service. Everything below is optional and configured by you. ## Available | Integration | How | Guide | | --- | --- | --- | | Google Workspace sign-in | OpenID Connect | [Google Workspace](https://hr.crow.sg/docs/admin/sso/google-workspace/) | | Microsoft Entra ID sign-in | OpenID Connect, single tenant | [Microsoft Entra ID](https://hr.crow.sg/docs/admin/sso/microsoft-entra-id/) | | Okta, Keycloak, Authentik and other OIDC providers | OpenID Connect with discovery | [Generic OIDC](https://hr.crow.sg/docs/admin/sso/generic-oidc/) | | Singpass login | FAPI 2.0 profile; needs your own relying-party onboarding; tested against Singpass staging, not production yet | [Singpass](https://hr.crow.sg/docs/admin/sso/singpass/) | | Email | Any SMTP server (`SMTP_URL`, `MAIL_FROM`) | [Configuration](https://hr.crow.sg/docs/self-hosting/configuration/#email) | | CPF Board | CPF EZPay (FTP) file, uploaded by you | [CPF EZPay file](https://hr.crow.sg/docs/payroll/cpf-ezpay-file/) | | Banks | Generic ISO 20022 `pain.001.001.03` file, uploaded by you | [Bank file](https://hr.crow.sg/docs/payroll/bank-file/) | | IRAS | IR8A rows for IRAS's import template, imported by you in myTax Portal | [IR8A export](https://hr.crow.sg/docs/payroll/ir8a-export/) | | Spreadsheets | CSV import of employees, compensation and YTD balances; CSV/XLSX export of employees; CSV export of the audit log | [Importing](https://hr.crow.sg/docs/people/importing/) | | Your own tools | The REST API used by the web app, documented in OpenAPI | [API reference](https://hr.crow.sg/docs/api/) | ## Files Uploaded files are stored on the server's disk in the data volume (`FILE_STORAGE_DIR`, default `/data/files`) and included in every backup. Object storage such as S3 is not supported. ## API access for integrations The API authenticates browser sessions (cookie) and native-app tokens (bearer, from the native sign-in flow). There are **no API keys or service accounts** for server-to-server integrations. See [API conventions](https://hr.crow.sg/docs/developers/api-conventions/). ## Not available - **IRAS AIS API** (direct IR8A submission): requires IRAS to approve the software as a vendor, Corppass authorisation, APEX credentials and whitelisted servers. - **Direct CPF submission**: you upload the EZPay file in CPF's portal. - **Bank-specific formats and bank APIs** (DBS, OCBC, UOB and others): only the generic ISO 20022 file exists, untested with any bank. - **Myinfo**: Singpass login requests only `openid`; no personal data is retrieved from Myinfo. - **MOM systems** (work pass applications, levy billing). - **Accounting exports** (journal entries, GL codes), **calendar feeds**, **webhooks**, **Slack or Teams** notifications. - **Push notifications** to phones: the [mobile apps](https://hr.crow.sg/docs/mobile-apps/) check for new notifications in the background and show them as local notifications instead. --- # Mobile apps > Native iOS and Android apps for Crow HR, version 1.0.0 on the App Store and Google Play. How connecting a phone to your company's server works. Source: https://hr.crow.sg/docs/mobile-apps/ Android: on [Google Play](https://play.google.com/store/apps/details?id=crowtech.crowhr) (1.0.0). iPhone and iPad: on the [App Store](https://apps.apple.com/app/id6831992308) (1.0.0). Without the app, the web app works on phones too, with a bottom tab bar for employees. The native apps are open source, in the same repository: iOS in SwiftUI (`apps/ios`) and Android in Kotlin and Jetpack Compose (`apps/android`). Both are built and tested against a real Crow HR server. On an iPad the iOS app shows a sidebar in landscape and can share the screen in Split View, Slide Over and Stage Manager. The apps cover what employees and managers do most: payslips, leave, clock in and out (also offline), claims with a photo of the receipt, your schedule, approvals and notifications. Everything else stays on the web. ## Try it with a demo company You don't need a server of your own to try the app. Open the [try page](https://hr-demo.crow.sg/try) on Crow Tech's demo server and tap **Start my demo company**. You get a private copy of Kopi Kaki, the fictional café group from the [demo](https://hr.crow.sg/docs/demo/), with four months of payroll, leave, claims and rosters. Then open it: - **on your phone**: tap **Open in the Crow HR app** (on Android it opens Google Play if the app isn't installed yet; on an iPhone or iPad, install it from the App Store first); - **on a computer**: scan the QR code with the app or the phone's camera; - **in the browser**: **Open in this browser**, on the same company. Sign in by picking a person, with no password: Hafiz (Employee), Siti (his manager), the HR admin, the payroll admin or the owner. Everyone sees what their role allows, so you can apply for leave as Hafiz on the phone and approve it as Siti in the browser. The app labels the server as a demo server with fictional data. Your demo company is yours alone (its short name, `demo-` and 12 characters, is the key to it) and is deleted with everything in it 3 days after you start it. The try page keeps it for you in that browser until then. In a demo company, sign-in and security settings, invitations, passwords and email are switched off, and uploads are limited to 25 MB. The app doesn't upload photos to a demo company, so receipts there are added in the browser. Each network can start a few demo companies an hour, and the server a few dozen. Nothing is retained: what you enter stays in your demo company until it ends and is then deleted with it, and the start limits keep only a count per network (not its address) for at most a day. Running your own demo server? See [demo companies](https://hr.crow.sg/docs/self-hosting/configuration/#demo-companies) in the configuration reference. ## How the apps connect The apps connect only to your company's own Crow HR server. Crow Tech runs no server for them, and they collect no data: no analytics, crash reporting or third-party SDKs. The apps' [privacy policy](https://crow.sg/apps/crow-hr/privacy/) and [support page](https://crow.sg/apps/crow-hr/support/) are on crow.sg, where the store listings link. Each person finds their connection code in **My profile → Mobile app**: - a **QR code** to scan with the app. It holds `crowhr://connect?server=&org=` and nothing else: no password, session or token, so it is safe to show on screen or print for a notice board; - the **server address** (your `PUBLIC_URL`) to type into the app instead, with a copy button, and the organisation's short name; - links to the app on Google Play and the App Store. If you type the address and the server hosts more than one organisation, the app also asks for the organisation's short name (its ID). The app then checks the server, shows your organisation's name for you to confirm, and signs you in through your phone's browser with the same methods you use on the web (password, Google, Microsoft, Singpass or your identity provider). The app needs HTTPS. On a plain-HTTP server (a LAN install without a certificate), My profile says so: the app will connect over HTTP only to a private network address or a `.local` name, after warning that the connection is not encrypted. See [reverse proxy](https://hr.crow.sg/docs/self-hosting/reverse-proxy/) to add HTTPS. On Android 17 and later, connecting to a server on your office network (a private address such as `192.168.1.20`) also needs the **local network** permission; the app asks for it before connecting. A server with a public HTTPS address needs no extra permission. ## Clocking in offline A clock-in made without signal is saved on the phone and sent when it reconnects. The app sends the tap time and how long ago the tap was, measured by the phone's own timer, which changing the phone's clock doesn't affect. So the server records the real time even if the clock was changed while offline, flags a wrong phone clock as clock skew, and marks punches that arrive more than 10 minutes late as sent late. Punches more than 7 days old are refused, as on the web; the app keeps them visible with the server's reason so a manager can add the time to the timesheet. The server side the apps use is part of every install: native sign-in with PKCE and device sessions (listed in **My sessions**, where you can sign a device out), `GET /api/v1/meta` for the organisation's name, logo, sign-in methods and features, and `GET /api/v1/notifications?since=` for background refresh ([API conventions](https://hr.crow.sg/docs/developers/api-conventions/#new-notifications-since-a-cursor)). The apps check the server's features rather than its version, so they keep working with servers older than the app. --- # Architecture > How the Crow HR codebase is organised - bun workspace packages, the runtime-agnostic core, the request lifecycle, tenancy, RBAC and audit. Source: https://hr.crow.sg/docs/developers/architecture/ Crow HR is a TypeScript monorepo (bun workspaces). Source is the artefact: packages export `src/*.ts` directly, Node 24 runs the server with native type stripping, and Vite and Vitest consume the same files. There is no per-package build step, so imports use explicit `.ts` extensions and enums and namespaces are not allowed (`erasableSyntaxOnly`). The contributor-facing version of this page, with more code, is `docs/architecture.md` in the repository. ## Packages ``` apps/web ──► packages/ui │ (types only) ──► packages/core apps/server ──► packages/core ──► packages/sg-rules apps/docs (this site) ──► reads packages/core sources at build time packages/sg-rules ──► nothing (pure, zero-dependency) ``` | Package | Owns | | --- | --- | | `packages/core` | Hono app factory `createApp(deps)`, request context, error envelope, validation, services, permissions, Drizzle schema and migrations, the OpenAPI generator, a PGlite test harness (`testing/`). | | `packages/sg-rules` | Effective-dated, cited statutory tables and calculators: CPF, SDL, SHG, FWL, Employment Act coverage, overtime, incomplete-month salary, leave entitlements, public holidays, deduction limits, payment deadlines. | | `packages/ui` | Crow Tech tokens, Tailwind preset, self-hosted fonts, components, Singapore formatting (`formatMoney`, `formatDate`, `maskNric`). | | `apps/server` | The Node host: configuration, node-postgres (or PGlite in development), argon2id hashing, disk file storage, security headers, migrations, backups, the scheduler, the `crowhr` CLI, and serving the built web app. | | `apps/web` | The React app (Vite, React 19, TanStack Router and Query, Tailwind 3.4). | | `apps/docs` | This documentation site (Astro Starlight). | ## A runtime-agnostic core `packages/core` never imports Node built-ins or Node-only packages. Everything host-specific arrives through `AppDeps`: | Dependency | Server | Tests | Browser demo (`packages/demo`) | | --- | --- | --- | --- | | `db` (Drizzle) | node-postgres pool | in-memory PGlite | PGlite on IndexedDB | | `passwordHasher` | argon2id | fast fake | PBKDF2 via Web Crypto (refused by the server) | | `fileStore` | local disk | in-memory | `demo_files` table in the visitor's PGlite | | `clock` | system clock | fixed or movable clock | system time shifted onto 31 Oct 2026 (the seed's "today") | | `ids` | UUIDv7 via Web Crypto | same, fixed clock | same | | `logger` | JSON lines on stdout | in-memory capture | console | The reason is the [in-browser demo](https://hr.crow.sg/docs/demo/), which runs the same core in the browser. A test (`src/runtime-agnostic.test.ts`) fails on any Node-only import under `src/`. ## Request lifecycle ``` HTTP ─► apps/server (security headers, proxy trust) ─► core: request context ─► session or bearer auth ─► CSRF ─► /api/v1 router ─► defineRoute: access check ─► validate params, query, body ─► handler ─► service(deps, auth, grant) ─► org-scoped query ─► response parsed by its schema ─► JSON any throw ─► { error: { code, message, requestId, details? } } ``` - Every route is declared with `defineRoute`. That one declaration validates input, checks permissions, serialises output and generates the OpenAPI document. - Responses are parsed through their declared schema: unknown fields fail in tests and are stripped in production. - Errors are `AppError(code, message)`; anything else becomes an opaque `500 internal`, logged with the request ID. - Unmatched `/api/*` paths answer JSON 404 before the static web app sees them, so API paths never return `index.html`. ## Tenancy, permissions and audit - **Tenancy**: every tenant table has `org_id` (a schema test enforces it), references between tenant tables are composite foreign keys `(org_id, id)`, and queries go through `orgScope(db, auth)`. A sweep test calls every route with another organisation's IDs and expects 404. - **Permissions**: the matrix is data in `access/matrix.ts`. `authorize(c, permission)` returns a grant with a scope (`all`, `team`, `own`, `assigned`); handlers narrow per record and answer 404 outside scope. See [roles and permissions](https://hr.crow.sg/docs/roles-and-permissions/). - **Sensitive data**: response schemas mark fields `sensitive(…, "salary" | "nric" | "bank" | "medical")`; NRIC/FIN and bank numbers are encrypted with AES-256-GCM and have a keyed HMAC blind index for lookups. - **Audit**: `recordAudit` appends to a per-organisation SHA-256 hash chain inside the same transaction; the database rejects updates and deletes on the audit table. ## Effective-dated data Records that change over time (employment terms, compensation, allowances, bank accounts, work schedule versions) use half-open `[effective_from, effective_to)` ranges, where `null` means "until further notice". Writes go through `planInsert`, which closes the version in force and handles future-dated versions in one transaction. Status such as "Scheduled" or "Leaving on" is derived from dates and the injected clock in Asia/Singapore, never stored. ## Money Money is integer cents (`number`, always a safe integer), stored as `bigint` columns in mode `number`. Never floats. Rounding is explicit and named, for example `roundHalfUpToDollar`. ## Background work Escalations, reminders, the email outbox and date-triggered transitions run in `tick(deps, now)`, called by the server every 60 seconds. Work is claimed with `FOR UPDATE SKIP LOCKED` or de-duplicated with unique keys, so two replicas never double-process. Core never uses timers. Scheduled backups run on the same scheduler in `apps/server` because `pg_dump` is Node-only. --- # Module guide > How to add a module to Crow HR's core - routes with defineRoute, org-scoped data access, permissions, audit, approvals and the tests every module adds. Source: https://hr.crow.sg/docs/developers/modules/ A module is a directory under `packages/core/src//` that exports one `ApiModule`. The full guide with more examples is `docs/architecture.md` ("How to add a module") in the repository. ## Routes ```ts // packages/core/src/teams/routes.ts import { z } from "zod"; import { defineModule, defineRoute } from "../http/route.ts"; import { listQuery, pageOf } from "../http/list.ts"; import { AppError } from "../errors.ts"; const team = z.object({ id: z.uuid(), name: z.string(), status: z.enum(["active", "archived"]) }); export const teamsModule = defineModule({ name: "teams", basePath: "/teams", // → /api/v1/teams tag: "Teams", routes: [ defineRoute({ method: "get", path: "/:id", summary: "Get a team", access: { permission: "org_structure:read" }, // a key of MATRIX in access/matrix.ts request: { params: z.object({ id: z.uuid() }) }, responses: { 200: team }, errors: ["not_found"], handler: async ({ deps, auth, params }) => { const found = await getTeam(deps, auth, params.id); // org-scoped query in ./service.ts if (!found) throw new AppError("not_found", "That team doesn't exist."); return found; }, }), ], }); ``` Then add the module to `V1_MODULES` in `packages/core/src/app.ts`, run `bun run openapi:generate` and commit the updated snapshot. Never register raw Hono routes under `/api/v1`: they would be undocumented and invisible to the cross-organisation test. Rules of the road: - **`access`** is required: `"public"`, `"authenticated"` (the handler limits itself to the caller's own data) or `{ permission }`. Narrow per record with the grant: `await grant.assertEmployee(row.employeeId)` (404 outside scope) or `grant.employeeFilter(...)` for lists. - **Sensitive actions** set `recentAuth: true`. - **Responses** declare every status the handler can produce. - **Errors** say how to fix the problem; list extra codes in `errors`. - **Lists** follow the [API conventions](https://hr.crow.sg/docs/developers/api-conventions/#lists) via `listQuery` and `pageOf`. - **Services, not routes,** hold logic and queries, so HTTP, jobs and the CLI share the same rules. ## Data access and audit ```ts const org = orgScope(deps.db, auth); const row = await org.getById(employees, params.id, "employee"); // 404 for other organisations await grant.assertEmployee(row.id); // 404 outside team/own scope await deps.db.transaction(async (tx) => { await tx.update(compensation).set(next).where(org.whereId(compensation, id)); await recordAudit(tx, deps, auditContext(c), { action: "compensation.updated", targetType: "employee", targetId: params.id, diff: diffFields(before, next, { sensitive: ["amountCents"] }), }); }); ``` ## Schema One file per area in `packages/core/src/db/schema/`, snake_case columns, UUID primary keys from `deps.ids`, `timestamp with time zone`, money as `bigint` cents in mode `number`. Run `bun run db:generate` and commit `packages/core/drizzle/`. CI fails if the schema and migrations disagree. ## Approvals A module whose records need approval implements a `SubjectAdapter` (`workflows/types.ts`) and adds a `WorkflowPlugin` to `CORE_WORKFLOW_PLUGINS` in `workflows/registry.ts`. Submit inside the transaction that creates the record; the engine calls `onApproved` / `onRejected` / `onWithdrawn` inside the decision's transaction, so a throwing callback rolls the decision back. Home items come from `InboxSource`s and reminders from `ReminderSource`s on the same plugin. ## Web screens Routes live in `apps/web/src/routes/_app/.tsx` inside the shell, built from `@crowhr/ui` components. Use `formatMoney(cents)`, `formatDate("YYYY-MM-DD")` and `maskNric`; numbers use the `num` class (Azeret Mono, tabular). Every screen has loading, empty, error and success states. ## Tests every module adds - **Cross-organisation**: automatic. `access/cross-org.test.ts` calls every non-public route with a path parameter using another organisation's IDs and expects 404. Seed one row of each of your tables for organisation B there. - **Permission matrix**: adding a key to `MATRIX` adds it to `access/matrix.http.test.ts` automatically, for every role, in and out of scope. Changing a cell is a spec change. The [docs table](https://hr.crow.sg/docs/roles-and-permissions/) updates on the next docs build. - Use `seedOrg`, `seedMember`, `clientAs` and `movableClock` from `@crowhr/core/testing`. --- # API conventions > Versioning and compatibility rules, request and response conventions, lists, errors and authentication for the Crow HR REST API. Source: https://hr.crow.sg/docs/developers/api-conventions/ The web app, the [mobile apps](https://hr.crow.sg/docs/mobile-apps/) and integrations all use the same versioned REST API. The contract is generated from the route declarations in `packages/core`, served by a running server at `GET /api/v1/openapi.json`, committed as `packages/core/openapi/v1.snapshot.json` and rendered in the [API reference](https://hr.crow.sg/docs/api/). ## Versions and compatibility - Every application endpoint is under `/api/v1/`. `GET /api/health` stays unversioned. - **Within v1, changes are additive only**: new endpoints, new optional request fields or query parameters, new response fields, and new enum values only where the schema sets `x-extensible-enum: true`. - **Breaking changes need `/api/v2`**: removing or renaming an endpoint or field, making an optional input required, adding a required input, changing a field's type or meaning, removing an enum value, adding a value to a closed response enum, or tightening validation. - After `/api/v2` ships, `/api/v1` is served for **at least 12 months**. - A deprecated endpoint still answers and adds `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers. - An unsupported version (`/api/v9/...`) answers `404 not_found` with `details.supportedVersions`. `bun run check` fails when the committed snapshot differs from what the code generates, or when it has breaking changes against the newest released snapshot. ## Requests and responses | Topic | Convention | | --- | --- | | Bodies | JSON only (`Content-Type: application/json`), camelCase field names. | | IDs | UUIDv7 strings. | | Money | Integer cents, `…Cents` suffix (`basicPayCents: 450000`). Never floats. | | Dates | `YYYY-MM-DD` for calendar dates (Singapore local); ISO 8601 UTC for instants. | | Sensitive fields | Marked `x-sensitivity: salary`, `nric`, `bank` or `medical`. Omitted for readers without access and listed in `redactedFields`. NRIC/FIN is masked unless revealed through the dedicated endpoint. | | Unknown fields | Responses never contain undeclared fields. | ## Lists ``` GET /api/v1/members?page=2&pageSize=50&sort=-createdAt&q=tan&status=active,invited 200 { "items": [...], "page": 2, "pageSize": 50, "total": 132 } ``` - `page` is 1-based; `pageSize` defaults to 50, maximum 200. - `sort` names one declared field; prefix `-` for descending. The ID is always the tiebreaker. - `q` is free-text search where the endpoint supports it. - Filters are query parameters named after the field; multi-value filters are comma-separated; date ranges are `From` / `To`, inclusive. ### New notifications since a cursor `GET /api/v1/notifications` also returns `cursor`, an opaque string for the newest notification in the response's view (`null` when you have none). Send it back as `since` to get only newer notifications, oldest first: ``` GET /api/v1/notifications?since=bjEuMTc5...&pageSize=50 200 { "items": [...], "total": 2, "unread": 5, "cursor": "bjEuMTc5..." } ``` With `since`, `cursor` points at the last item returned, so keep calling with the new cursor until `items` is empty. The cursor doesn't move when nothing is new or when you read items. A cursor the server didn't issue answers `400 validation_failed`. The mobile apps use this for background refresh. ## Errors ```json { "error": { "code": "validation_failed", "message": "Some fields need attention.", "requestId": "…", "details": { "issues": [{ "path": "email", "message": "Enter a valid email address, like name@company.sg." }] } } } ``` Switch on `code`, never on `message`. Each operation lists its codes under `x-error-codes`. Common codes: | Status | Codes | | --- | --- | | 400 | `validation_failed`, `ambiguous_credentials`, `invalid_grant` | | 401 | `unauthenticated`, `invalid_credentials`, `invalid_mfa_code`, `invalid_setup_code`, `session_expired`, `session_revoked` | | 403 | `forbidden`, `csrf_rejected`, `reauth_required`, `mfa_enrolment_required`, `password_sign_in_disabled`, `self_change_requires_approval`, `disabled_in_demo` | | 404 | `not_found`, also for records outside your organisation or scope | | 409 | `conflict`, `last_owner`, `setup_required`, `duplicate_id_number`, `in_use`, `reporting_cycle`, `already_decided` | | 429 | `rate_limited`, with `Retry-After` | | 5xx | `internal` (500, details are only in the server log), `not_implemented` (501), `service_unavailable` (503, for example while starting or restoring) | ## Authentication - **Browser**: an HttpOnly session cookie (`__Host-crowhr_session`, or `crowhr_session` when `PUBLIC_URL` is plain http). State-changing requests must be same-origin, or they get `403 csrf_rejected`. - **Native apps**: `Authorization: Bearer ` from the native authorisation-code + PKCE flow (access tokens last 15 minutes). Tokens are never accepted in query strings, and a request with both a cookie and a bearer token gets `400 ambiguous_credentials`. - There are no API keys for server-to-server integrations. - In the OpenAPI document, `security: []` marks public operations, `x-permission` names the permission checked and `x-recent-auth: true` means the session must have authenticated in the last 10 minutes. --- # Testing > How Crow HR is tested - Vitest on PGlite, the permission and cross-organisation sweeps, sg-rules coverage, OpenAPI checks, Playwright, the self-host script and the docs checks. Source: https://hr.crow.sg/docs/developers/testing/ Calculations, permissions and workflows are written test first. A green build is not treated as evidence of correctness on its own: statutory numbers also need cited sources and the [verification record](https://hr.crow.sg/docs/payroll/verification/). ## Commands Run from the repository root after `bun install`: | Command | What it runs | | --- | --- | | `bun run check` | Everything below except e2e: Biome, the third-party licence check (`scripts/third-party-notices.ts`), TypeScript for every package, all Vitest suites, sg-rules coverage (≥ 95% lines), the OpenAPI snapshot check, and the docs build with its link check. | | `bun run test` | Vitest across every package and app. | | `bun run typecheck` | `tsc` for each package. | | `bun run coverage:sg-rules` | sg-rules tests with the coverage threshold. | | `bun run openapi:check` | Snapshot is current; v1 is additive-only against released snapshots. | | `bun run docs:build` | Builds this site, then checks every internal link and anchor and that every API path has a page. | | `bun run e2e` | Builds the web app and runs Playwright. | ## Unit and integration tests - **Vitest** everywhere. Integration tests run the real Hono app against **PGlite**, an in-process PostgreSQL in WebAssembly, so no Docker is needed. Use `createTestDb()` and `createTestDeps(db)` from `@crowhr/core/testing`, call `createApp(deps).request(...)`, and close the database in `afterEach`. - Response schemas run in **strict** mode in tests: an undeclared field fails the test. - `access/matrix.http.test.ts` checks every cell of the permission matrix for every role, in and out of scope. - `access/cross-org.test.ts` calls every route that takes a record ID with another organisation's IDs and expects 404. - `packages/sg-rules` runs the official and derived test vectors, CPF's 16 AW-ceiling examples and the 15 calculator-confirmed cases. - Payroll has golden files (the CPF EZPay file), byte-identical PDF and result-hash tests, a 12-person company month and a full-year run. ## End-to-end - **Playwright** specs in `e2e/` run the built web app against the real server. People and payroll screens use dev-only seeded servers (`packages/core/testing/*-dev-server.ts`, bound to 127.0.0.1) with fictional staff. `e2e/seed.ts` creates four fictional organisations: the main one, one with every SSO preset (sign-in page), a fresh one with only its owner (setup checklist, claim types) and one for the single sign-on round trip, which runs against the in-process mock OpenID provider served on 127.0.0.1 by `e2e/mock-idp-server.ts` (test only; it signs in whoever the test names). The first-run wizard runs against a second, empty server. - **`e2e/self-host.sh`** builds the image and follows the install page in a throwaway compose project: clean `up`, setup wizard, backup, `down -v`, restore, lost-data-volume recovery, and the Caddy, nginx and Traefik examples from the reverse-proxy page over TLS with test certificates. It removes only what it created. ## Docs checks The docs site has its own tests (`apps/docs/tests/`), run by `bun run test`: - every environment variable the server, CLI, Dockerfile and compose file read is documented in the [configuration reference](https://hr.crow.sg/docs/self-hosting/configuration/), and nothing documented there is unused; - every `crowhr` CLI command is documented in the [CLI reference](https://hr.crow.sg/docs/self-hosting/cli/); - every permission resource has a label on the [roles and permissions](https://hr.crow.sg/docs/roles-and-permissions/) page (the table itself is generated from the matrix); - the OpenAPI helpers group and render every operation. After `astro build`, `scripts/check-dist.ts` fails on any broken internal link or `#anchor`, and on any OpenAPI path without a section in the API reference. --- # The OpenSpec process > How requirements, change proposals and task lists are kept in openspec/ and how a change moves from proposal to archive. Source: https://hr.crow.sg/docs/developers/openspec/ Crow HR keeps its requirements in the repository with [OpenSpec](https://github.com/Fission-AI/OpenSpec). The rule: substantial work starts as a change proposal; trivial fixes do not need one. ## Layout ``` openspec/ config.yaml # project context and rules for artefacts specs/ # current requirements (filled as changes are archived) changes// proposal.md # why, what changes, non-goals (under 600 words) design.md # decisions and trade-offs specs//spec.md # requirements as SHALL statements with scenarios tasks.md # numbered tasks, each naming its package and the test that proves it ``` ## How a change moves 1. **Propose**: write the proposal, design, spec deltas and tasks. Requirements are testable: each has at least one `WHEN … THEN …` scenario. 2. **Apply**: implement task by task, writing the named test first. Tick a task only when its test passes. A stub stays unticked, is marked `// NOT IMPLEMENTED:` in the code and is listed in `docs/limitations.md`. 3. **Archive**: when every task is done, the spec deltas are merged into `openspec/specs/` and the change moves to the archive. Changing a cell of the permission matrix, the API contract or a statutory rule is a spec change and goes through this process. ## Where to find changes Every change, finished or in progress, is a directory in [`openspec/changes/`](https://github.com/Crow-Tech-Pte-Ltd/CrowHR/tree/main/openspec/changes); its `tasks.md` shows what is done and what is open. For what the product does today, see [project status](https://hr.crow.sg/docs/status/). ## Ground rules From the project's working agreement (`AGENTS.md` in the repository): - Nothing is marked done if it is stubbed or mocked. - Statutory numbers come from cited sources, with an effective date and a source URL. - Money is integer cents; rounding is explicit and named. - Permissions are enforced on the server; hiding UI is cosmetic. - Every tenant table has `org_id`, and cross-organisation access has a test proving it fails. --- # Contributing > How to set up a Crow HR development environment, the checks a change must pass, and how to propose larger changes. Source: https://hr.crow.sg/docs/developers/contributing/ Crow HR is MIT-licensed and open to contributions. The short version is `CONTRIBUTING.md` in the repository; this page adds detail. ## Set up You need [bun](https://bun.sh) 1.3 and Node 24. ```sh git clone https://github.com/Crow-Tech-Pte-Ltd/CrowHR.git cd CrowHR bun install bun run dev # API on 127.0.0.1:8080 (PGlite in ./data), web app with Vite ``` No PostgreSQL or Docker is needed for development or tests: the server falls back to PGlite, and tests use in-memory PGlite. Docs: `bun run --cwd apps/docs dev` serves this site at `http://localhost:4321/docs/`. ## Before you open a pull request ```sh bun run check ``` It must pass: Biome (format and lint), the third-party licence check, TypeScript, all tests, sg-rules coverage, the OpenAPI snapshot, and the docs build with its link check. If you changed routes, run `bun run openapi:generate` and commit the snapshot. If you changed the database schema, run `bun run db:generate` and commit `packages/core/drizzle/`. If you added or upgraded a dependency, run `bun run licences` and commit `THIRD-PARTY-NOTICES.md`: shipped dependencies must use a permissive licence. ## What we look for - **A test first** for calculations, permissions and workflows. - **Cited sources** for any statutory number: an effective date and a URL to CPF, MOM, IRAS or SSG. No uncited constants. - **Integer cents** for money, explicit named rounding. - **Server-side permissions** through the matrix; never rely on hiding UI. - **Honest status**: if something is stubbed, say so in the code (`// NOT IMPLEMENTED:`), in the task list and in `docs/limitations.md`. Never document a feature that does not work. - **The design language**: calm, dense, precise. Hairline borders, Azeret Mono for headings and numbers, Ubuntu for text, the kuning accent for the one primary action. No gradients, blurred shadows or decorative statistics. - **Accessible screens**: keyboard navigation, visible focus, WCAG AA contrast, 360 px wide layouts. ## Larger changes Anything beyond a bug fix or small improvement starts as an [OpenSpec change](https://hr.crow.sg/docs/developers/openspec/) so the requirements are agreed before code is written. Open an issue first to discuss it. ## Reporting bugs and security issues - Bugs and feature requests: the repository's issue tracker, using the templates. - Security vulnerabilities: **not** in a public issue. See [security](https://hr.crow.sg/docs/help/security/). ## Licence By contributing you agree that your contribution is licensed under the MIT licence. Everyone taking part follows the project's Code of Conduct (Contributor Covenant). --- # Troubleshooting > Fixes for common Crow HR problems with sign-in, single sign-on, invitations, people imports and payroll runs. Source: https://hr.crow.sg/docs/help/troubleshooting/ For problems with the server itself (startup errors, setup code, backups, proxies), see [troubleshooting the server](https://hr.crow.sg/docs/self-hosting/troubleshooting/). ## Signing in | Symptom | What to do | | --- | --- | | Sign-in keeps failing or is slow for someone who is sure of their password | After 10 wrong passwords from one network within 15 minutes, each further attempt has to wait (doubling up to 30 seconds), and the message stays the same. Wait a minute and try again, or an owner uses **Clear sign-in lockout** in Settings → Members. | | Everyone in the office is rate-limited at once | The server sees one IP for everyone because it does not trust your proxy. Set `TRUSTED_PROXIES` ([reverse proxy](https://hr.crow.sg/docs/self-hosting/reverse-proxy/)). | | "You were signed out after a period of inactivity" | The idle timeout (default 30 minutes) passed. Owners can change it in Settings → Security. | | Signed out immediately after signing in | `PUBLIC_URL` does not match the address in the browser, or it is `https` while the browser uses `http`. | | Every page says to set up two-step verification | Your role requires it and the 7-day grace period is over. Enrol, or ask an owner to change the [MFA policy](https://hr.crow.sg/docs/admin/mfa/). This also applies when you sign in with Google or another provider that doesn't report MFA. | | "Password sign-in is disabled" | Your organisation uses single sign-on; use the provider's button. Owners can always use their password. | | Asked for the password again before saving | Sensitive actions need a sign-in within the last 10 minutes. This is expected. | | The owner lost their password and authenticator | On the server: `crowhr reset-owner-mfa --email ` ([CLI](https://hr.crow.sg/docs/self-hosting/cli/#reset-owner-mfa)). | ## Single sign-on | Symptom | What to do | | --- | --- | | "Sign-in with Google/Microsoft/… failed" | The reason is in Settings → Audit log, event `auth.sso_failed`: `state_mismatch` (expired or replayed attempt, try again), `hd_mismatch`, `tid_mismatch`, `email_not_verified`, `not_provisioned`. | | "Your account has not been set up in …" | No member with that email. Invite them, or have them use the invitation link. | | The provider's button is missing on the sign-in page | It is switched off, or not fully configured (Singpass without a client ID or keys). Test it and switch it on in Settings → Security. | | Redirect URI mismatch at the provider | Register exactly the URI Crow HR showed; it is built from `PUBLIC_URL`. | ## Invitations and email | Symptom | What to do | | --- | --- | | Invitation emails do not arrive | Without `SMTP_URL`, nothing is emailed: copy the link from Settings → Members. With SMTP, check Settings → Notifications for failures and your provider's SPF/DKIM for `MAIL_FROM`. | | "Invitation expired" | Links last 7 days. Resend from Settings → Members; the old link stops working. | | Imported employees got no invitation link | Without SMTP, import invitations are not shown. Resend them from Settings → Members. | ## People | Symptom | What to do | | --- | --- | | "This NRIC's check letter does not match" | Check the last letter against the card. FINs starting with M are supported. | | `duplicate_id_number` on a new hire | The person worked here before. Use **Rehire** to keep their history. | | Cannot archive a department | Current employees use it; the message links to them. Move them first. | | A foreigner cannot be hired | Add a work pass valid on the start date first. | | A salary change is refused for a past month | That month's payroll is approved or paid. Mark the change retroactive; the next run flags the back pay. | ## Payroll A run's issues are written out in words. The rule ID below (such as `EA_FINAL_PAY_LATE`) is on the issue icon's tooltip, and in the employee drawer under **Rule IDs, for support**. | Issue code or symptom | What to do | | --- | --- | | Run cannot be submitted: company profile | Add UEN, CSN and address in Settings → Company. | | `409` "recompute the run" on submit | Records or items changed after computing. Recompute, review, submit again. | | `OT_NOT_STATUTORY` | The employee is not covered by Part 4 of the Employment Act (basic pay above the limit, or flagged as a manager or executive on the Job tab). Choose **Enter the overtime amount** on the issue and enter the contractual amount. | | `PH_GROSS_RATE_REQUIRED` | A public holiday falls on the employee's off day and is paid as an extra day's gross pay. Classify the allowances it names in **Payroll → Allowance treatment**, or, for hourly or rostered staff, choose **Enter holiday pay** and enter the day's gross pay. | | `ALLOWANCE_GROSS_RATE_UNSET` | A warning: an allowance paid in the run has no answer for the gross rate of pay. Set it in **Payroll → Allowance treatment** before a holiday on an off day or an encashment request needs it. | | `YTD_BEFORE_CROWHR_MISSING` | Import [YTD opening balances](https://hr.crow.sg/docs/people/importing/#year-to-date-opening-balances) for months paid before Crow HR. | | `CPF_LOW_WAGE_CAPPED_AW_UNSUPPORTED` | A case CPF has no rule for. Compute that employee's CPF with CPF Board's guidance and pay outside Crow HR, or adjust the AW timing. | | Scheduled days / days worked missing | The employee has no fixed working week. Add both items for the month. | | Deduction over the limit | Reduce the deduction by the amount shown; the 50% overall limit is only a warning on final pay. | | `CPF_RATES_ASSUMED_CARRIED_FORWARD` | The month is beyond CPF's published tables. Check the rates when CPF publishes them. | | Payslips cannot be released, naming an item | A mandatory payslip item is missing, often the employer's legal name. Fix the record. | | Employee cannot see their payslip | It is not released yet, or the run is not approved. | | An employee is missing from the bank file | They have no bank account current on the pay date; the download lists excluded employees. | | An employee is missing from the EZPay file | Foreign employees with SHG and no S/T number are listed for you to key in EZPay. | ## Still stuck Collect `docker compose exec app crowhr doctor`, the request ID shown with the error (every API error carries one) and the matching lines of `docker compose logs app`, and [open an issue](https://github.com/Crow-Tech-Pte-Ltd/CrowHR/issues). Do not post NRIC numbers, salaries or other personal data in public issues. --- # FAQ > Common questions about Crow HR - cost, hosting, data, compliance claims, modules and support. Source: https://hr.crow.sg/docs/help/faq/ ## Cost and data ### Is it free, and who hosts it? Yes, it is free: the code is MIT-licensed, and you can run it for your company, change it and redistribute it without paying Crow Tech. Crow Tech does not run Crow HR for customers; you host it on a small cloud server, a machine in your office or anything that runs Docker. Your costs are that server and your time. ### Does Crow Tech see our data? No. The app sends nothing to Crow Tech: no analytics, telemetry or crash reports. It only contacts services you configure (your SMTP server, your identity provider and, optionally, your own error-monitoring service). ## Compliance ### Is Crow HR approved by CPF Board, IRAS or MOM? No. Crow HR is not approved, certified or endorsed by any government agency. Its statutory rules come from cited official sources and are tested against official examples and CPF's online calculator ([how we verify](https://hr.crow.sg/docs/payroll/verification/)), but you remain responsible for your payroll and submissions. It is not an IRAS-approved AIS vendor. ### Can it submit CPF, IR8A or salary payments for us? No. It produces the CPF EZPay file, a generic bank file and IR8A rows, and you upload them in CPF EZPay, your bank and myTax Portal. See [integrations](https://hr.crow.sg/docs/integrations/). ### Do we need Singpass? No. Singpass login is optional and requires your company's own Singpass onboarding. It has been tested against Singpass staging, not yet against production. Email and password, Google Workspace, Microsoft Entra ID and other OpenID Connect providers work without it. ## Using it ### Can we use it for leave, claims or attendance? Yes. [Leave](https://hr.crow.sg/docs/leave/leave/), [attendance and overtime](https://hr.crow.sg/docs/attendance/attendance/), [claims](https://hr.crow.sg/docs/claims/claims/) and [shift scheduling](https://hr.crow.sg/docs/scheduling/scheduling/) are built, and approved no-pay leave, overtime and claims flow into payroll. They are new: see each page's limitations, and check the first runs that use them. ### We are moving from another system mid-year. What do we need? Import employees and their compensation, then the [year-to-date opening balances](https://hr.crow.sg/docs/people/importing/#year-to-date-opening-balances) so the CPF AW ceiling is right for the rest of the year. Run one month in parallel with your old system and compare. ### Can several companies share one install? Yes. Each legal entity is its own organisation with its own UEN and CSN, and one person can belong to several. Switch between them with the organisation switcher at the top left: it lists every organisation where you are a member (or a former employee) and moves this browser to the one you choose. An organisation that allows only single sign-on asks you to sign in on its own sign-in page (`/sign-in/`) instead. ### Does it work on phones? The web app works on phone screens, with a bottom tab bar for employees. The native [mobile apps](https://hr.crow.sg/docs/mobile-apps/) are on [Google Play](https://play.google.com/store/apps/details?id=crowtech.crowhr) for Android and the [App Store](https://apps.apple.com/app/id6831992308) for iPhone and iPad. **My profile → Mobile app** shows the code that connects the app to your server. ### Is there a demo? Yes, at [hr.crow.sg](https://hr.crow.sg/): the [in-browser demo](https://hr.crow.sg/docs/demo/) runs the app with a fictional company, entirely in your browser. ## Support ### How do we get support? Through the project's [public issue tracker](https://github.com/Crow-Tech-Pte-Ltd/CrowHR/issues), on a best-effort basis. There is no paid support contract today. Security issues go through the [security policy](https://hr.crow.sg/docs/help/security/), not public issues. --- # Security > How to report a vulnerability in Crow HR, and the security measures operators should know about. Source: https://hr.crow.sg/docs/help/security/ ## Reporting a vulnerability Please **do not open a public issue** for a security problem. - Use GitHub's private vulnerability reporting on the repository ([**Security → Report a vulnerability**](https://github.com/Crow-Tech-Pte-Ltd/CrowHR/security/advisories/new)), or - email **hello@crow.sg**. Include what you found, the version or commit, steps to reproduce and the impact you expect. Do not include real personal data. We aim to acknowledge reports within 5 working days and will tell you when a fix is released. Please give us reasonable time to fix the issue before disclosing it. The same policy is in [`SECURITY.md`](https://github.com/Crow-Tech-Pte-Ltd/CrowHR/blob/main/SECURITY.md) in the repository. Security fixes go into the latest release of the current major version (1.x); upgrade promptly with `docker compose pull && docker compose up -d`. ## Built-in protections | Area | What Crow HR does | | --- | --- | | Passwords | argon2id (19 MiB, 2 iterations), 12 to 128 characters, common-password list, no composition rules. Failures give one generic message; verification runs even for unknown emails. | | Brute force | After 10 wrong passwords per account/IP in 15 minutes, delays double from 1 second to a 30-second maximum. The 50th wrong password across IPs pauses new browsers for at most 30 seconds once per 15-minute window; attempts cannot extend that pause. Previously signed-in browsers with a signed 180-day device cookie can still sign in from other networks, subject to their network delay. Per IP: 30 failed sign-ins per minute (successful sign-ins only count toward a 300-per-minute ceiling, so an office sharing one address is not blocked) and 30 MFA-verification requests per minute; 5 wrong MFA codes pause the account for 15 minutes. | | Two-step verification | TOTP with replay protection, hashed single-use recovery codes, required for owners, HR and payroll admins by default. | | Sessions | 256-bit random tokens stored as SHA-256 hashes; `__Host-` HttpOnly, Secure, SameSite=Lax cookies over HTTPS; idle and absolute timeouts; rotation on sign-in; revocation. | | CSRF | State-changing requests must come from `PUBLIC_URL`'s origin. | | Email | SMTP on port 587 requires STARTTLS by default (`SMTP_REQUIRE_TLS`); `smtps://` uses implicit TLS. Emails never contain amounts, NRIC/FIN, bank or medical details. | | Re-authentication | Sensitive actions need a sign-in within 10 minutes. | | Encryption at rest | NRIC/FIN, passport and work pass numbers, bank numbers, TOTP secrets, SSO secrets and keys: AES-256-GCM under `CROWHR_SECRET_KEY`. Backups can be encrypted with age. | | Authorisation | One permission matrix enforced on the server for every route; other organisations' records answer 404; field-level redaction. | | Audit | Append-only audit log with a SHA-256 hash chain; `crowhr admin verify-audit` checks it. | | Container | Runs as uid 10001 on a read-only root filesystem; the database has no host port. | ## Operator checklist - Serve Crow HR over **HTTPS** ([reverse proxy](https://hr.crow.sg/docs/self-hosting/reverse-proxy/)) and set `TRUSTED_PROXIES` correctly. - Set `BACKUP_PASSPHRASE` and copy backups off the server. An unencrypted backup contains the encryption key. - Keep the server and Docker updated, and [upgrade](https://hr.crow.sg/docs/self-hosting/upgrades/) Crow HR when releases come out. - Keep `PUBLIC_URL` and the encryption key stable; never delete the database to "fix" a key mismatch. - Enforce MFA at your identity provider when staff use SSO, or enrol a Crow HR authenticator. Crow HR requires an explicit IdP MFA assertion to satisfy its role policy. - Review **Settings → Audit log** and **Settings → System** regularly. ## Known gaps There is no row-level security in the database (isolation between organisations is enforced by the application, with tests), the common-password list is curated rather than a breach corpus, and invitation and password-reset emails are not retried. See [limitations](https://hr.crow.sg/docs/payroll/limitations/#platform-and-sign-in). --- # Privacy and PDPA for operators > Guidance for companies that run Crow HR on how the Personal Data Protection Act applies to the employee data they keep in it. Source: https://hr.crow.sg/docs/help/privacy-pdpa/ :::note This is practical guidance, not legal advice. For your obligations under the Personal Data Protection Act 2012 (PDPA), read the PDPC's guidance and get advice where you need it. ::: ## Who is responsible When you self-host Crow HR, **your company** collects, uses and keeps your employees' personal data, so your company is the organisation responsible for it under the PDPA. Crow Tech provides software and does not receive, host or process your data, so it is not your data intermediary. A cloud or hosting provider you use may be one; check your contract with them. ## What Crow HR stores | Data | Why | Protection | | --- | --- | --- | | Names, contact details, emergency contacts | Employment administration | Role-based access | | NRIC/FIN, passport and work pass numbers | CPF, IR8A, work-pass compliance | Encrypted at rest, masked, reveal audited | | Date of birth, residency, PR start date | CPF rates and age bands | Personal-details permission | | Race and religion | Self-help group fund contributions | Personal-details permission | | Bank account | Salary payment | Encrypted at rest, masked to last 4 digits | | Pay, allowances, payslips | Payroll | Owners, payroll admins and the employee only | | Sign-in data (sessions, IP addresses, user agents) | Security | Audit log, session list | | Medical certificates, sick leave and medical claim receipts, medical documents | Leave, claims and records | Only owners, HR admins, the employee and the current approver | | Children's names, dates of birth and citizenship | Parental and childcare leave | Leave permissions | | Clock-in times, IP address and, if you turn it on, location | Attendance | Employee, their manager and HR; location is off by default and needs a [PDPA notice](https://hr.crow.sg/docs/attendance/attendance/#location-and-office-network-optional) | NRIC numbers: the PDPC's advisory guidelines limit collecting, using and disclosing NRIC numbers to cases required by law or where they are necessary to verify identity to a high degree of fidelity. Employment and CPF, tax and work-pass obligations are such cases. Crow HR masks NRIC/FIN by default and logs every reveal; do not put NRIC numbers anywhere else in the app (notes, free-text fields) or in exports you do not need. ## Practical steps - **Purpose and consent**: tell employees what HR data you keep and why (your employee privacy notice). Collect race and religion only for the SHG fund, as the app does. - **Access**: give owner, HR admin and payroll admin roles only to people who need them. Managers see the directory and their team's employment records and emergency contacts, not pay, bank or personal details. Review **Settings → Members** when people change jobs. - **Protection**: run Crow HR over HTTPS, keep two-step verification on for privileged roles, set `BACKUP_PASSPHRASE`, and store backups somewhere access-controlled. Exported CSV, XLSX, bank and IR8A files contain personal data; delete them when done. - **Accuracy and correction**: employees can see their own records and update contact details directly, and request corrections to legal and bank details through change requests. - **Access requests**: an employee's data is on their profile, payslips and the audit log; owners see all of it (HR admins the profile, payroll admins the pay records) and can export the employee list for a PDPA access request. - **Retention**: keep records as long as the law and your purposes need. Crow HR keeps former employees' records and history (rehires depend on it) and does not erase anything automatically; the [document retention review](https://hr.crow.sg/docs/documents/documents/#retention-review) flags ex-employees' documents for HR to keep or delete. Notifications are deleted after 180 days; the audit log is append-only by design. - **Breaches**: if you suspect a data breach, assess it and, where the PDPA requires, notify the PDPC and affected employees within the required time. The audit log (who viewed or changed what, from which IP) helps with the assessment. - **Transfers**: if your server or backups are outside Singapore, the PDPA's transfer limitation obligation applies. ## What Crow HR does not send anywhere The app does not send employee data to Crow Tech or to analytics or advertising services. It contacts only what you configure: your SMTP server (emails contain no salary, NRIC/FIN, bank or medical details), your identity provider during sign-in and, if you set it up, your own error-monitoring service ([what it receives](https://hr.crow.sg/docs/self-hosting/configuration/#optional-error-monitoring)).