Skip to content

About

To auto deploy projects

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

23 Commits

Folders and files

Repository files navigation

projects-autodeploy

Hosts Virtuals' internal apps on Google Cloud Run, so anyone who builds a tool (usually with Claude) can put it online without touching Google Cloud.

  • Where apps run: Cloud Run in asia-southeast1, project virtuals-internal-apps.
  • 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, 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.

How an app goes live

  1. Build it to the rules below. Claude's virtuals-platform plugin (plugin/, see "The Claude plugin") does this, and adds the files from templates/app/. The bizops portal's Tech requests → Build an app page walks a builder through it.
  2. Get a repo, with its secrets. When the app is ready, the platform team creates a private repo in Virtual-Protocol, adds the builder (who pushes the code), and adds its secrets (Settings > Secrets and variables > Actions), named as in its .env.example. Only repo admins can set secrets, so the builder sends the values through a password manager share. Public values (NEXT_PUBLIC_*, VITE_*) go under Variables instead.
  3. Host it. Use the Host an app form in the bizops portal. It runs host-app.yml, which checks the request and creates the app's Cloud Run service, its own service account and, if asked for, a storage bucket. Until its first deploy, the app's address shows a page (placeholder/) listing what's left to do, with links.
  4. Deploy: run the repo's Deploy workflow, or merge to main. The app repo's deploy.yml calls deploy-app.yml, which builds the image, copies the secrets into Secret Manager and deploys. A deploy before hosting fails ("isn't hosted yet"): hosting creates the app's place to run.

What hosting checks

A request is refused unless all of these hold:

Check Why
The repo is in Virtual-Protocol The company controls who can change it
The repo is private Internal tools' code isn't public
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 It will deploy and run as expected
The app name isn't used by another repo Names are the service's and secrets' names

Deploys check again that the app was hosted from the same repo, so one repo can't deploy over another's app.

The rules

An app is one Node.js container that:

  • builds with npm ci && npm run build and starts with npm start
  • listens on process.env.PORT
  • answers its health check (/api/health by default) with 200, without login or database calls
  • keeps no state on local disk: files go to Cloud Storage (needs.storage). An app that already saves files to a folder can have its bucket appear as that folder (needs.storage_folder)
  • lists every env var it reads in .env.example, with fake values
  • commits no secrets and no cloud keys: it gets Google access from its own service account

Not available yet, so ask the platform team: Postgres, Redis, scheduled jobs, custom domains, anything bigger than medium.

Public apps

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

Builders work with Claude Code and the virtuals-platform plugin in plugin/. It teaches Claude the rules above, carries the templates and the checker, and loads by itself when someone builds or hosts an app. Its guide is plugin/skills/internal-app/SKILL.md.

  • This repo is public, so anyone can install the plugin without being given access. Nothing here is secret, and nothing secret may ever be committed here: app secrets live in each app repo's GitHub secrets, and the platform's in this repo's GitHub secrets.

  • For everyone at once: an Owner of the claude.ai organization adds this under Organization settings → Claude Code → Managed settings:

    {
      "extraKnownMarketplaces": {
        "virtuals": {
          "source": { "source": "github", "repo": "Virtual-Protocol/projects-autodeploy" },
          "autoUpdate": true
        }
      },
      "enabledPlugins": { "virtuals-platform@virtuals": true }
    }
  • One person: claude plugin marketplace add Virtual-Protocol/projects-autodeploy, then claude plugin install virtuals-platform@virtuals.

  • Per app repo: the plugin commits .claude/settings.json, so anyone who opens the repo in Claude Code is offered the plugin.

To change the rules, edit SKILL.md and bump version in plugin/.claude-plugin/plugin.json. The checker and templates live in actions/check/ and templates/app/; the plugin keeps copies, and the Plugin in sync check fails a change that updates only one.

Security

  • No keys anywhere. GitHub Actions gets short-lived Google credentials through Workload Identity Federation. Only deploy-app.yml and host-app.yml on this repo's main can get them (see bootstrap/setup.sh), so changes to main here need a reviewer.
  • Each app is fenced in. It runs as its own service account, which can read only secrets named <app>--* and its own bucket.
  • The deployer can write secrets but not read them, and the image is built before any credentials exist on the runner.

One-time setup

Done once by someone who owns the Google Cloud project and administers this repo:

./bootstrap/setup.sh

Then create the ORG_READ_TOKEN secret it asks for.

Running it

  • Logs: Google Cloud console > Cloud Run > the app > Logs.
  • Roll back: Cloud Run > the app > Revisions > send traffic to an earlier one, or re-run an earlier Deploy in the app repo.
  • Turn an app off: gcloud run services delete <app> --region asia-southeast1 --project virtuals-internal-apps.

About

To auto deploy projects

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages