.github

Shared GitHub configuration for the rasgo-studio organization: the default pull request template (.github/PULL_REQUEST_TEMPLATE.md), the reusable CI workflows (.github/workflows/ci-*.yml) and the reusable deploy workflows (.github/workflows/deploy-*.yml), called from each repository with uses: rasgo-studio/.github/.github/workflows/<file>@main.

Deploy contract: rasgo.deploy.yml

Each repository that deploys keeps a rasgo.deploy.yml at its root: what it is, how it deploys and how a deploy is checked (RINF-54). The reusable deploy workflows read it, and RASGO Core keeps it with each deploy. Version 1 keeps only what exists today: the adapters are the current ways of deploying, behind one contract. Its schema is schemas/deploy-contract.json.

Field	Required	What it says
version	yes	1
component	yes	Its name in the Registry of RASGO Core: the repository, or the site it publishes
stack	yes	laravel, wordpress, static, monorepo or n8n, as the stack property of the repository (DEV-02.2)
adapter	yes	laravel-ploi (Ploi deploy webhook), wordpress (Ploi deploy webhook too), static (Cloudflare Pages), monorepo-ploi (rasgo-core, one Ploi site per environment) or n8n (rasgo-motor)
environments	yes	staging and production, each with ref (a branch, or tag for the published release), url, approval (merge or none) and secrets
migrations	no	The command the deploy runs after the code; the record of the deploy in Core shows it
health	yes	path on the environment url that answers with the deployed version (expect: version), or only its status
rollback	yes	previous-tag (a deploy of the tag before, launched by Sergio, which Core closes as rolled_back) or none (going back is not done by the system)

Rules of the contract:

• Production deploys with Sergio's merge, which is the approval (approval: merge, D-111): the deploy workflow sends Core (deploy-start) the GitHub person who merged or launched the run, and Core stops it before it touches the server unless that person is Sergio (DEV-12). There is no approval in the Hub for a deploy. Staging may be automatic (approval: none, level 2). approval: core, the name before D-111, still reads as merge until rasgo-wp-base and the sites made from it change their contract.
• Names, never values (DEV-07): secrets lists the names of the environment secrets the adapter reads, such as the Ploi deploy webhook. No host, path with a secret, token or key goes in the contract.
• This repository is public (DEV-02.2): the examples here carry no client names; each repository writes its own.

Laravel app of a client, deployed by its Ploi sites:

version: 1
component: acme-portal
stack: laravel
adapter: laravel-ploi
environments:
  staging:
    ref: main
    url: https://staging.example.com
    approval: none
    secrets: [PLOI_DEPLOY_WEBHOOK]
  production:
    ref: tag
    url: https://example.com
    approval: merge
    secrets: [PLOI_DEPLOY_WEBHOOK]
migrations: php artisan migrate --force
health:
  path: /version
  timeout_s: 300
rollback: none

WordPress site, deployed by its Ploi site (WPR-08):

version: 1
component: example.com
stack: wordpress
adapter: wordpress
environments:
  production:
    ref: tag
    url: https://example.com
    approval: merge
    secrets: [PLOI_DEPLOY_WEBHOOK]
health:
  path: /
  expect: status
  timeout_s: 120
rollback: none

Static site (Cloudflare Pages):

version: 1
component: example.org
stack: static
adapter: static
environments:
  staging:
    ref: main
    url: https://staging.example.org
    approval: none
    secrets: [CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID]
  production:
    ref: tag
    url: https://example.org
    approval: merge
    secrets: [CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID]
health:
  path: /version.json
rollback: previous-tag

Deploy workflows

Three reusable workflows deploy what a contract describes, one per way of deploying (RINF-54). Each repository calls the one of its adapter from its own .github/workflows/deploy.yml; the header of each file has the call to copy.

Workflow	Adapters	How the code reaches the server
deploy-laravel.yml	laravel-ploi, monorepo-ploi	Calls the Ploi deploy webhook of the site; its deploy script pulls and builds
deploy-wordpress.yml	wordpress	The same: the Ploi site pulls the repository and builds the theme
deploy-static.yml	static	Builds this commit in the Action and uploads it to Cloudflare Pages with wrangler (Direct Upload)

Every deploy follows the same order, and stops at the first step that fails:

1. Contract. Reads rasgo.deploy.yml and checks it against the run: the adapter is the one of the workflow, the environment exists, production has approval: merge and a GitHub person who merged or launched the run, and the run comes from what the environment deploys (its branch, or a tag when ref: tag).
2. Secrets. The secrets the adapter reads come from Bitwarden Secrets Manager only (see Secrets below). In deploy-static.yml this step runs after the build.
3. deploy-start. Asks RASGO Core with the repository, app, environment, commit and the GitHub person (deployed_by: github.triggering_actor). Core answers with a deployment_id, or with 403 and the reason (not_allowed when that person is not Sergio), and then nothing touches the server (D-111, DEV-12). If Core does not answer, nothing deploys: there is no emergency exit.
4. Deploy. The adapter: the Ploi webhook, or the upload to Cloudflare Pages.
5. Health. Asks url + health.path until it answers with this commit (full or short) or this version, up to health.timeout_s. A JSON answer with a commit field, such as a version.json, counts only by that commit: the release before may carry the same version number. With expect: status it only checks that the site answers, which does not prove the new code is live.
6. deploy-finish. Closes the deploy in Core with success, failure or, for a healthy rollback, rolled_back. It runs even when an earlier step failed, so failed deploys are recorded too.

Calling them:

• Inputs. environment (required), rollback_of (the deployment_id of the failed deploy that this one undoes) and task (the Plane code, so Core can report on it), plus app, version and, for a monorepo, versions (a JSON object with the version of each app). deploy-static.yml also takes pages-project, build-command, output-dir, production-branch and staging-branch. approval_id is only for a Core older than RCOR-87, which still asks for an approval; it goes once that Core is no longer live.
• Tying a deploy to its run. deploy-laravel.yml takes run_id, the number of the RASGO Core run the deploy belongs to. With it, deploy-start and deploy-finish carry the header X-Rasgo-Run: <run_id> and Core keeps the deploy in deployments.run_id, as an artifact of that run (RCOR-45). Only digits are accepted, and the Contract step stops on anything else. Without it, neither request carries the header and the deploy works as before. Core ignores a number that is not one of its runs.
• Secrets have the names the contract lists (DEV-07): RASGO_CORE_DEPLOY_TOKEN always (the Core token of the deploy actor, ops 1), then PLOI_DEPLOY_WEBHOOK, or CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID. They live in Bitwarden Secrets Manager, project actions, EU region (D-109). The staging and production environments of the calling repository keep only BWS_ACCESS_TOKEN, the token of the read-only machine account of that project.
  • Keys. One project holds every repository, so the Secrets step looks for the most specific key first: NAME__<COMPONENT>__<ENVIRONMENT>, then NAME__<COMPONENT>, then NAME. The component of the contract and the environment go in capitals, with anything else as _: the production webhook of acme-portal is PLOI_DEPLOY_WEBHOOK__ACME_PORTAL__PRODUCTION; a token shared by all, such as RASGO_CORE_DEPLOY_TOKEN, keeps its plain name.
  • Only Bitwarden. No GitHub secret takes the place of a name: a name not found in Bitwarden, or whose first key found is empty or still says PLACEHOLDER, stops the deploy and the run names its key. Without BWS_ACCESS_TOKEN the deploy stops too.
  • How. bws (bitwarden/sdk-sm 2.1.0, checked against the sha256 pinned in core.sh, the same as rasgo-motor) reads the project with the machine account. Each value is masked and left for the next steps of the job, and the run names the keys it used, never a value. If Bitwarden does not answer, nothing deploys. Optional repository variables: BWS_PROJECT_ID (read only that project) and BWS_SERVER_URL (another region).
  • Calling. With secrets: inherit, or passing BWS_ACCESS_TOKEN explicitly under secrets:.
• The repository variable RASGO_CORE_URL points to another Core, for tests.
• Production runs on Sergio's merge: the push to the branch the contract deploys, or the tag that the merge of the version PR publishes (DEV-12 12.3). To relaunch or go back, Sergio runs workflow_dispatch on what he wants live: gh workflow run deploy.yml --ref acme-v1.4.0 -f environment=production. Staging with approval: none can deploy on each push to its branch.
• Ploi deploys the head of its branch, not a given commit. So both Ploi workflows stop before deploy-start when that head (ref, or ploi-branch for a tag, main by default) is not the commit of the run: with release-please, deploy the tag right after merging the release. For the same reason a Ploi rollback to an older tag cannot pass; going back there is a revert merged into the branch, which deploys like any merge, or the rollback of the Ploi panel (Sergio); their contracts say rollback: none. deploy-static.yml builds the commit it runs on, so rollback: previous-tag works there.
• Static sites get version.json (component, version, commit) in the published folder unless the build writes one, so health.path: /version.json checks the deployed commit.

The steps live in actions/deploy-core (core.sh, with its tests in tests/). The workflows call it at @main, like the repositories call the workflows: a change here reaches every deploy at once, so it comes with its tests and the test workflow green.