Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/deploy-app.yml
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,7 @@ jobs:
--add-volume-mount "volume=storage,mount-path=$FOLDER"
)
fi
# Who can reach the app (Google sign-in, or public if approved) was
# Who can reach the app (Google sign-in, or public) was
# set when it was hosted and is left as it is.
gcloud run deploy "$NAME" "${args[@]}"

Expand Down
3 changes: 0 additions & 3 deletions .github/workflows/host-app.yml
Original file line number Diff line number Diff line change
Expand Up @@ -74,9 +74,6 @@ jobs:
env:
REPO: ${{ inputs.repo }}
REQUESTED_BY: ${{ inputs.requested_by }}
# Approved public apps, edited on the bizops portal's Public apps
# page. Only repo admins (and the portal's token) can change it.
PUBLIC_APPS: ${{ vars.PUBLIC_APPS }}
run: scripts/read-platform.sh app

# The page the app shows until its first deploy, built from this repo
Expand Down
38 changes: 13 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Hosts Virtuals' internal apps on Google Cloud Run, so anyone who builds a tool
- **Who can open them:** anyone signed in with a `@virtuals.io` Google account.
Google checks this (Identity-Aware Proxy) before a request reaches the app.
The few apps built for the public, such as the support portal, are open to
everyone instead, once the platform team approves them (see "Public apps").
everyone instead, when their `platform.yaml` says so (see "Public apps").
- **How they deploy:** every push to the app repo's `main` builds and deploys it,
in about 3 minutes.

Expand Down Expand Up @@ -44,7 +44,6 @@ A request is refused unless all of these hold:
| `owner` in the repo's `platform.yaml` is the person asking | Only someone who can push to the repo could have written that |
| The app passes [the checker](actions/check/check.mjs) | It will deploy and run as expected |
| The app name isn't used by another repo | Names are the service's and secrets' names |
| A `public: true` app is approved as public (see "Public apps") | Opening an app to the internet needs a platform engineer's say-so |

Deploys check again that the app was hosted from the same repo, so one repo
can't deploy over another's app.
Expand All @@ -65,32 +64,21 @@ An app is one Node.js container that:
service account

Not available yet, so ask the platform team: Postgres, Redis, scheduled jobs,
custom domains, anything bigger than `medium`. Public (no sign-in) apps need
the platform team's approval (see "Public apps").
custom domains, anything bigger than `medium`.

## Public apps

An app whose `platform.yaml` says `public: true` is open to anyone, with no
Google sign-in. Hosting refuses it unless the app's name and repo are in this
repo's `PUBLIC_APPS` Actions variable (Settings > Secrets and variables >
Actions > Variables), a JSON list:

```json
[{ "name": "acp-ticket-cms", "repo": "acp-ticket-cms", "approvedBy": "someone@virtuals.io", "approvedAt": "2026-11-17T00:00:00Z" }]
```

- **To approve an app:** open **Tech help → Public apps** in the bizops portal (platform
approvers only), add the app's name and repo, then have its owner host it again with the
**Host an app** form. No change to this repo, no deploy. Only list apps built for the
public, such as a customer support page, never an internal tool.
- **Who can change the list:** the approvers the portal names (`PUBLIC_APP_APPROVERS` in its
`lib/access.ts`), through the portal's GitHub token, and this repo's admins directly. GitHub's
organization audit log records every change.
- **Taking approval away** stops the app being hosted as public again, but doesn't close an
app that is already open. The owner closes it by setting `public: false` and hosting it
again, which puts it behind Google sign-in. To shut it at once, a platform engineer runs
`gcloud run services update <app> --iap --invoker-iam-check --region asia-southeast1 --project virtuals-internal-apps`,
which locks everyone out until the owner hosts it again with `public: false`.
An app whose `platform.yaml` says `public: true` is open to anyone on the internet, with
no Google sign-in. It's the owner's call, with no approval: hosting the app with
`public: true` opens it, and hosting it again with `public: false` puts it back behind
sign-in. Deploys leave it as it is. Only make an app public if it's built for people
outside Virtuals, such as a customer support page, and has its own sign-in for anything
private. The checker warns about it, and the hosting result says "anyone, no sign-in".

The `access` label on each Cloud Run service (`public` or `company`) shows which apps are
open. To shut one at once, a platform engineer runs
`gcloud run services update <app> --iap --invoker-iam-check --region asia-southeast1 --project virtuals-internal-apps`,
which locks everyone out until the owner hosts it again with `public: false`.

## The Claude plugin

Expand Down
4 changes: 2 additions & 2 deletions actions/check/check.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ if (!yamlText) {
if (cfg) {
const known = new Set(["name", "owner", "port", "healthcheck", "size", "max_copies", "public", "needs"]);
for (const k of Object.keys(cfg)) {
if (k === "audience") warn("platform.yaml: audience isn't used. Apps are behind Google sign-in unless public: true, which needs the platform team's approval");
if (k === "audience") warn("platform.yaml: audience isn't used. Apps are behind Google sign-in unless public: true");
else if (!known.has(k)) warn(`platform.yaml: unknown key "${k}" (ignored)`);
}

Expand Down Expand Up @@ -150,7 +150,7 @@ if (cfg) {

cfg.public ??= false;
if (typeof cfg.public !== "boolean") err("platform.yaml: public must be true or false");
else if (cfg.public) warn("platform.yaml: public: true opens the app to anyone, with no sign-in. Hosting refuses it until the platform team approves the app (bizops portal: Tech help → Public apps)");
else if (cfg.public) warn("platform.yaml: public: true opens the app to anyone, with no sign-in. Only for apps built for people outside Virtuals, with their own sign-in for anything private");

cfg.needs ??= {};
if (typeof cfg.needs !== "object") err("platform.yaml: needs must be a section (storage: true/false)");
Expand Down
2 changes: 1 addition & 1 deletion plugin/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "virtuals-platform",
"description": "How to build internal apps that host on the Virtuals platform (Google Cloud Run, through projects-autodeploy): rules, templates and a checker",
"version": "1.1.1",
"version": "1.2.0",
"author": { "name": "Virtuals Protocol" },
"repository": "https://github.com/Virtual-Protocol/projects-autodeploy"
}
8 changes: 4 additions & 4 deletions plugin/skills/internal-app/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,9 +78,9 @@ key, `GOOGLE_APPLICATION_CREDENTIALS`, or AWS keys.
Roles (who is an admin and so on) are the app's own business: store them in its database,
keyed by that email.
- **Public apps** (customers outside Virtuals, like the support portal) are the exception:
`public: true` in `platform.yaml` only works once the platform team approves the app. Then
anyone can open it, so the app needs its own sign-in for anything private. Flag it in the
hand-off.
`public: true` in `platform.yaml` lets anyone open the app, with no sign-in. Set it only when
the user asks for an app outside Virtuals can use; the app then needs its own sign-in for
anything private. Flag it in the hand-off.

### Settings and secrets
- Every env var the code reads goes in `.env.example`. At each deploy, the platform copies
Expand Down Expand Up @@ -199,6 +199,6 @@ applies:
2–3 minutes and gives the app's address.
4. **Deploy:** "Open Actions → Deploy → Run workflow in the repo, or merge to `main`. It's live
about 5 minutes later." After the first time, every merge deploys by itself.
5. **Needs the platform team:** a database, a public app, a schedule, a custom domain, or a
5. **Needs the platform team:** a database, a schedule, a custom domain, or a
migration that drops or renames data.
6. **Problems found:** a tracked `.env` file, secrets in code, or anything you couldn't fix.
4 changes: 2 additions & 2 deletions plugin/skills/internal-app/scripts/check.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ if (!yamlText) {
if (cfg) {
const known = new Set(["name", "owner", "port", "healthcheck", "size", "max_copies", "public", "needs"]);
for (const k of Object.keys(cfg)) {
if (k === "audience") warn("platform.yaml: audience isn't used. Apps are behind Google sign-in unless public: true, which needs the platform team's approval");
if (k === "audience") warn("platform.yaml: audience isn't used. Apps are behind Google sign-in unless public: true");
else if (!known.has(k)) warn(`platform.yaml: unknown key "${k}" (ignored)`);
}

Expand Down Expand Up @@ -150,7 +150,7 @@ if (cfg) {

cfg.public ??= false;
if (typeof cfg.public !== "boolean") err("platform.yaml: public must be true or false");
else if (cfg.public) warn("platform.yaml: public: true opens the app to anyone, with no sign-in. Hosting refuses it until the platform team approves the app (bizops portal: Tech help → Public apps)");
else if (cfg.public) warn("platform.yaml: public: true opens the app to anyone, with no sign-in. Only for apps built for people outside Virtuals, with their own sign-in for anything private");

cfg.needs ??= {};
if (typeof cfg.needs !== "object") err("platform.yaml: needs must be a section (storage: true/false)");
Expand Down
2 changes: 1 addition & 1 deletion plugin/skills/internal-app/templates/platform.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ size: small # small = 1 vCPU / 1 GB, up to 3 copies | medium = 2 vCP
# max_copies: 1 # optional: fewer copies than the size allows, e.g. 1 for an app
# whose copies would clash over files in its storage folder
# public: true # optional: anyone on the internet can open it, with no sign-in.
# Only for apps the platform team approves in the bizops portal.
# Only for apps built for people outside Virtuals.

needs:
storage: false # true -> a private Cloud Storage bucket, its name in STORAGE_BUCKET
Expand Down
4 changes: 2 additions & 2 deletions scripts/provision.sh
Original file line number Diff line number Diff line change
Expand Up @@ -76,8 +76,8 @@ if [[ "$STORAGE" == true ]]; then
fi

if [[ "$PUBLIC" == true ]]; then
# Approved in PUBLIC_APPS (read-platform.sh checked). Turning off
# Cloud Run's invoker check opens it without granting anything to allUsers.
# platform.yaml says public: true. Turning off Cloud Run's invoker check
# opens it without granting anything to allUsers.
step "The Cloud Run service, open to everyone"
access=public
access_flags=(--no-iap --no-invoker-iam-check)
Expand Down
20 changes: 3 additions & 17 deletions scripts/read-platform.sh
Original file line number Diff line number Diff line change
@@ -1,12 +1,8 @@
#!/usr/bin/env bash
# Reads the app's platform.yaml and checks it against the request: the person
# asking must be the owner the repo names, which only someone who can push to
# the repo could have written there, and a public app must be approved.
# the repo could have written there.
# scripts/read-platform.sh <app dir>
# Needs: REPO REQUESTED_BY GITHUB_OUTPUT GITHUB_STEP_SUMMARY
# Optional: PUBLIC_APPS, the approved public apps (this repo's PUBLIC_APPS
# Actions variable, which the bizops portal's Public apps page edits):
# [{"name": "<app name>", "repo": "<repo in Virtual-Protocol>", ...}]
set -euo pipefail

dir="$1"
Expand Down Expand Up @@ -41,19 +37,9 @@ done
storage=$(field .needs.storage)
[[ "$storage" == true ]] || storage=false

# The owner decides: public: true opens the app to anyone, with no sign-in.
public=$(field .public)
if [[ "$public" == true ]]; then
# Both the name and the repo must match, so approving one app doesn't let
# another repo take its name and be public too. A missing or broken list
# approves nothing.
jq -e --arg name "$name" --arg repo "$REPO" '
type == "array" and
any(.[]; type == "object" and .name == $name and ((.repo // "") | ascii_downcase) == ($repo | ascii_downcase))
' <<<"${PUBLIC_APPS:-[]}" >/dev/null 2>&1 ||
fail "platform.yaml says public: true, but \"$name\" from $REPO isn't an approved public app. Public apps need the platform team's approval: ask them to approve it under Tech help → Public apps in the bizops portal, then host it again."
else
public=false
fi
[[ "$public" == true ]] || public=false

# What the owner sets on GitHub before the first deploy, named as deploy-app.yml
# reads them from .env.example: public values are variables, the rest secrets.
Expand Down
2 changes: 1 addition & 1 deletion templates/app/platform.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ size: small # small = 1 vCPU / 1 GB, up to 3 copies | medium = 2 vCP
# max_copies: 1 # optional: fewer copies than the size allows, e.g. 1 for an app
# whose copies would clash over files in its storage folder
# public: true # optional: anyone on the internet can open it, with no sign-in.
# Only for apps the platform team approves in the bizops portal.
# Only for apps built for people outside Virtuals.

needs:
storage: false # true -> a private Cloud Storage bucket, its name in STORAGE_BUCKET
Expand Down
Loading