Security
This page describes how Colony Cloud is built with respect to authentication, credential storage, infrastructure hosting, and the Worker credential model. Claims here reflect the current implementation — not aspirational targets.
Authentication
Section titled “Authentication”Colony Cloud has three sign-in paths for human users. All of them need an invitation or an existing account.
- GitHub OAuth: Colony Cloud redirects you to GitHub, you authorize the Colony Cloud application on GitHub’s site, and Colony Cloud receives your GitHub identity from GitHub’s OAuth response. Colony Cloud requests the
read:userandread:orgscopes. - Email and password: for people who accept an invitation that way. Passwords are stored only as PBKDF2-SHA256 hashes, never in plaintext. An account created through GitHub has no password until its owner uses Forgot Password.
- Magic link: a sign-in link emailed to an existing account, valid for 15 minutes.
- Sessions are established via httpOnly, Secure,
SameSite=LaxJWT cookies. The JWT is self-contained and verified on each API request. - Sessions can also be revoked server-side. Each user has a session epoch that is checked on every request, and a password change, removal, force sign-out or suspension advances it, which ends the user’s existing sessions.
- A session lasts 7 days and renews for another 7 when it’s used in its last 24 hours. An active session therefore doesn’t expire by itself; it ends through the session epoch or sign-out.
Access comes from Colony Cloud membership, not GitHub organization membership. It is checked against Colony Cloud’s own records on each organization request and each organization switch. Removing someone from a GitHub organization doesn’t remove their Colony Cloud access, so remove them on Account → Members too. Acting on a work item separately checks the person’s write access to the repository on the code host.
Secrets and credential storage
Section titled “Secrets and credential storage”Org secrets entered in Operations → Settings (Secrets) are encrypted at rest using AES-GCM before being written to the database. The database stores only the ciphertext. Colony Cloud decrypts a value when it’s needed: Workers receive the credentials they use when they register, and the API uses them to reach your provider for features you route through your tenant’s model access.
- You cannot retrieve a secret’s plaintext value after saving it — only overwrite it with a new value.
- People’s GitHub OAuth tokens and the cached installation tokens used by
colony-coderandcolony-operationsare also encrypted with the same key material. No credentials are stored in plaintext in the database. - Saving a new value overwrites the old one in the live database. You can’t recover the old value.
See Secrets & keys for how to set, replace and delete the credentials Colony Cloud stores.
Infrastructure and data hosting
Section titled “Infrastructure and data hosting”| Component | Hosting |
|---|---|
| Dashboard (React SPA) | Cloudflare Pages |
| Workers | Managed Workers on Fly.io, or your own hosts for BYO Workers |
| API | Cloudflare Pages Functions, co-deployed with the dashboard at app.runcolony.com/api/* |
| Database | Neon Postgres, accessed via Cloudflare Hyperdrive |
| Pipeline Store | A Postgres database dedicated to your organization. The API reads it and writes to it, for example when you enable a repository or change a setting |
All traffic between your browser, the Colony Cloud API, and the database is over HTTPS/TLS. The dashboard and API share the app.runcolony.com domain — no cross-origin requests are made.
Cloudflare handles DDoS mitigation, TLS termination, and edge caching for static assets.
Worker credential model
Section titled “Worker credential model”Workers don’t hold GitHub App private keys or long-lived GitHub credentials. They do hold other long-lived credentials: when a Worker registers, Colony Cloud returns its organization’s Pipeline Store connection strings and model provider keys, and the Worker keeps them while it runs. Package-feed credentials are written to a file inside the Worker container, readable only by its owner. Treat a BYO Worker’s host accordingly.
On every /api/worker/register and /api/worker/heartbeat call, the Cloud API:
- Validates the Worker’s Bearer token (issued from Operations → Fleet (
/operations/fleet)). - Returns a short-lived GitHub App installation token for the connected organization the Worker is pinned to, reusing a cached token until it nears expiry. A token covers every repository that installation can reach, not only the Worker’s own.
Workers pick up a refreshed token in place, with no restart.
Token revocation takes effect on the Worker’s next heartbeat. Revoking a Worker token in Operations → Fleet refuses that heartbeat, and the Worker shuts down. Revoking does not rotate credentials the Worker already holds, so rotate those separately; if Colony operates your Pipeline Store, contact support for that. See Workers (BYO) for instructions on revoking tokens.
Data retention
Section titled “Data retention”| Data type | Retention |
|---|---|
| Organization records (members, connected repos, secrets) | Kept until the organization is deleted |
| Pipeline data in the Pipeline Store, including repository and tenant config | Not deleted with the organization. Contact support to request deletion |
| Issue history and pipeline events | Kept with no time limit |
| Agent messages and issue trace events | Deleted after 14 days or more |
| Mayor conversations | Deleted 30 days after the last message |
| Overwritten or deleted secret values | Removed from the live database immediately. Encrypted copies can remain in database snapshots and backups |
| Post-cancellation data | Not deleted automatically. Contact support to request deletion |
Overwriting or deleting a value through Operations → Settings (Secrets) removes it from the live database immediately. Encrypted copies can remain in database snapshots and backups after that.
For data deletion requests outside the standard retention schedule, contact support.