216 lines
8.9 KiB
Markdown
216 lines
8.9 KiB
Markdown
# Decap CMS: Gitea settings
|
|
|
|
Status: the preview-only pilot was accepted for promotion on 2026-09-04. The
|
|
repository now targets the permanent `cms` staging branch. Update the exact
|
|
CORS origin and PKCE OAuth redirect only after its first preview deployment
|
|
confirms the predicted alias. Nothing has been merged to `main`.
|
|
|
|
The repository implementation targets these fixed public values:
|
|
|
|
| Setting | Value |
|
|
| --- | --- |
|
|
| Gitea repository | `SloanOps/3031023-xyz` |
|
|
| Decap write branch | `cms` |
|
|
| Gitea base URL | `https://git.sloanops.com` |
|
|
| Gitea API root | `https://git.sloanops.com/api/v1` |
|
|
| Stable CMS origin | `https://cms-3031023-xyz-www.ksloan90.workers.dev` |
|
|
| Exact OAuth redirect URI | `https://cms-3031023-xyz-www.ksloan90.workers.dev/admin/` |
|
|
| Required status context | `CMS content validation / cms-content-validation (pull_request)` |
|
|
|
|
The pilot and permanent branch names are intentionally slash-free. Decap
|
|
CMS 3.15.1 inserts the configured Gitea branch directly into its tree-API URL;
|
|
a slash-named branch such as `cms/pilot` is split as an API path and its 404 is
|
|
presented as an empty collection. The permanent `cms` branch is still a
|
|
non-production staging branch: changes reach `main` only through the protected
|
|
pull-request flow.
|
|
|
|
The Workers alias was confirmed after the first approved preview deployment.
|
|
If Cloudflare later assigns a different stable origin,
|
|
update the repository configuration, CORS origin, and OAuth redirect URI
|
|
together through review before enabling login.
|
|
|
|
## Runner cache settings
|
|
|
|
The Dockerized runner uses a persistent `/data` volume and the same dedicated
|
|
Docker network as its job containers. Its non-confidential cache settings are:
|
|
|
|
```yaml
|
|
cache:
|
|
enabled: true
|
|
dir: /data/cache
|
|
host: sloanops-gitea-runner
|
|
port: 8088
|
|
offline_mode: true
|
|
container:
|
|
network: sloanops-actions
|
|
```
|
|
|
|
`offline_mode` is safe here because every external `uses:` reference is pinned
|
|
to a reviewed full commit SHA. It prevents the runner from refreshing mutable
|
|
action branches on every job; npm packages remain keyed separately by
|
|
`package-lock.json` through setup-node's cache integration.
|
|
|
|
## Applied CORS policy
|
|
|
|
The tracked Gitea service in
|
|
`/home/sloan/gitRepos/SloanOps/infrastructure/docker-compose.yml` contains
|
|
these entries in the existing `gitea.environment` list and was deployed
|
|
through the normal infrastructure change process:
|
|
|
|
```yaml
|
|
- GITEA__cors__ENABLED=true
|
|
- GITEA__cors__ALLOW_DOMAIN=https://cms-3031023-xyz-www.ksloan90.workers.dev
|
|
- GITEA__cors__METHODS=GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS
|
|
- GITEA__cors__MAX_AGE=10m
|
|
- GITEA__cors__ALLOW_CREDENTIALS=false
|
|
- GITEA__cors__HEADERS=Authorization,Content-Type
|
|
```
|
|
|
|
This is one exact origin, no wildcard, no cookie-bearing cross-origin request,
|
|
and only the API methods and non-safelisted request headers used by the Gitea
|
|
backend. Do not add the production domains, the journal preview, arbitrary
|
|
Workers preview hosts, or localhost. Gitea's same-origin login page continues
|
|
to use its own session cookie; Decap API calls use the OAuth bearer token.
|
|
|
|
After an approved Gitea deployment, verify a preflight without including a
|
|
token or cookie:
|
|
|
|
```bash
|
|
curl --request OPTIONS 'https://git.sloanops.com/api/v1/version' \
|
|
--header 'Origin: https://cms-3031023-xyz-www.ksloan90.workers.dev' \
|
|
--header 'Access-Control-Request-Method: GET' \
|
|
--header 'Access-Control-Request-Headers: authorization,content-type'
|
|
```
|
|
|
|
The response must allow only the configured origin, requested method, and
|
|
headers. Repeat with an unrelated origin and confirm that Gitea does not grant
|
|
it cross-origin access. Also verify normal Git, web UI, API, and Actions
|
|
behavior before continuing.
|
|
|
|
## OAuth application
|
|
|
|
The Gitea OAuth2 application was created after the stable preview origin and
|
|
CORS response were verified:
|
|
|
|
- Application name: `3031023.xyz Decap CMS`.
|
|
- Confidential client: **unchecked**. The browser client must use PKCE.
|
|
- Redirect URI: exactly
|
|
`https://cms-3031023-xyz-www.ksloan90.workers.dev/admin/`, including the
|
|
trailing slash.
|
|
- Do not add wildcards, localhost, either production hostname, or the journal
|
|
preview as additional redirects.
|
|
- Copy only the public client ID into `backend.app_id` in
|
|
`public/admin/config.yml` through a reviewed commit.
|
|
- Do not store or use a client secret in the repository, Actions, Cloudflare,
|
|
or Decap configuration.
|
|
|
|
The CMS account still needs repository write access; the branch rules below
|
|
are the security boundary that reduces that write access to pilot content and
|
|
media paths.
|
|
|
|
## Applied branch protection rules
|
|
|
|
Create both rules before granting a CMS/client account write access or testing
|
|
login. Gitea uses only the first matching rule, so the order is material.
|
|
|
|
### Priority 1: production `main`
|
|
|
|
| Gitea control | Required value |
|
|
| --- | --- |
|
|
| Protected branch pattern | `main` |
|
|
| Priority | `1` (first/highest) |
|
|
| Push | Disabled for everyone; no push allowlist |
|
|
| Force push | Disabled |
|
|
| Required approvals | `1` |
|
|
| Approval allowlist | Enabled; only the named SloanOps operator user/team |
|
|
| Dismiss stale approvals | Enabled |
|
|
| Ignore stale approvals | Disabled |
|
|
| Block rejected reviews | Enabled |
|
|
| Block outstanding official review requests | Enabled |
|
|
| Block outdated pull requests | Enabled |
|
|
| Status checks | Enabled |
|
|
| Status check pattern | `CMS content validation / cms-content-validation (pull_request)` |
|
|
| Merge allowlist | Enabled; only the named SloanOps operator user/team |
|
|
| Administrators must follow protection | Enabled |
|
|
| Protection bypass allowlist | Disabled |
|
|
|
|
Leave both file-pattern fields empty on this rule. Direct pushes are already
|
|
disabled, and executable or configuration changes must remain possible only in
|
|
a separate operator-authored, reviewed pull request. The fallback rule prevents
|
|
CMS users from placing those files on any source branch.
|
|
|
|
This rule means every `main` change arrives through a current pull request,
|
|
passes the one secret-free job that validates the CMS contract and builds and
|
|
verifies both sites, receives a current SloanOps approval, and is merged by a
|
|
SloanOps operator. A CMS/client account must not be added to the approval,
|
|
merge, administrator, or bypass allowlists.
|
|
|
|
### Priority 2: all-branch fallback
|
|
|
|
| Gitea control | Required value |
|
|
| --- | --- |
|
|
| Protected branch pattern | `*` |
|
|
| Priority | `2` (after `main`) |
|
|
| Push | Disabled, except the unprotected file patterns below |
|
|
| Force push | Disabled |
|
|
| Unprotected file patterns | Exact semicolon-separated value below |
|
|
| Protected file patterns | Empty; every path omitted from the unprotected list remains protected |
|
|
| Protection bypass allowlist | Enabled only for the named SloanOps operator user/team |
|
|
| CMS/client account | Write access, but absent from every allowlist |
|
|
|
|
Enter this exact single value in **Unprotected file patterns**:
|
|
|
|
```text
|
|
sites/www/content/**;sites/blog/content/**;public/images/uploads/*.jpg;public/images/uploads/*.jpeg;public/images/uploads/*.png;public/images/uploads/*.webp;public/images/uploads/*.avif
|
|
```
|
|
|
|
Do not add a nested upload glob. The current Decap configuration writes media
|
|
directly into the flat uploads directory, and the local verifier rejects nested
|
|
media paths. Gitea file patterns are case-insensitive; CI verifies actual file
|
|
signatures and a 25 MiB source safety ceiling before deployment. The build
|
|
re-encodes the deployed copy to at most 1920 pixels and 500 KiB and strips
|
|
embedded metadata.
|
|
|
|
Everything not listed is protected from CMS/client pushes on `cms` and
|
|
on every differently named branch, including:
|
|
|
|
```text
|
|
.gitea/**
|
|
astro.config.mjs
|
|
package.json
|
|
package-lock.json
|
|
schemas/**
|
|
scripts/**
|
|
src/**
|
|
wrangler/**
|
|
sites.json
|
|
sites/*/site.json
|
|
public/admin/**
|
|
public/_headers
|
|
public/images/*
|
|
```
|
|
|
|
The final `public/images/*` line describes the effect of omission, not an
|
|
additional Gitea field value: existing approved images stay protected while
|
|
the explicitly listed `public/images/uploads/*.<raster>` paths remain writable.
|
|
Workflows, source, scripts, package files, schemas, manifests, Wrangler
|
|
configuration, `site.json` files, and the CMS application therefore cannot be
|
|
altered by choosing another branch name.
|
|
|
|
## Verification before an editor invitation
|
|
|
|
1. Run `npm ci`, `npm run verify:cms`, and both site build/verifier pairs.
|
|
2. Create `cms` from the reviewed baseline only after approval.
|
|
3. Apply both protection rules together and confirm `main` is priority 1 and
|
|
`*` is priority 2.
|
|
4. Use the same non-operator account intended for Decap to prove allowed
|
|
Markdown edits succeed and every protected-path/direct-`main` attempt fails.
|
|
5. Open, but do not merge, a pull request into `main`. Confirm Gitea reports
|
|
the exact required status context above and blocks merge without both its
|
|
successful result and a current SloanOps approval.
|
|
6. Confirm both branch previews remain no-index and production is unchanged.
|
|
|
|
Do not treat a Decap UI restriction as authorization. Gitea's first-match
|
|
branch rules are the enforcement boundary, and the pull-request build is the
|
|
content/media integrity boundary.
|