Repository navigation
docs operations deploy agent
Goal: every commit on main whose required checks pass reaches https://teste.abastevo.com.br automatically, with no secret, host detail or private configuration in this public repository or its public Actions logs.
Scope limits:
automatic deployment targets staging only. Production stays a manual,
approved release behind G09; nothing here deploys production or tags a
release. One app (Abastevo, namespace abastevo-temp) on a shared VPS: the
agent never touches another namespace, nginx site or host service.
| Push (Actions SSH into the VPS) | Pull (chosen) | |
|---|---|---|
| Secrets in GitHub | SSH key/host in environment secrets |
none beyond the automatic GITHUB_TOKEN and OIDC |
| Inbound access to VPS | GitHub runners need SSH | none; the VPS only makes outbound HTTPS |
| Public log exposure | host/IP/commands risk | Actions logs only show build/sign steps |
| Fork/PR abuse | must guard pull_request_target
|
builds run only on push to main
|
| Trust anchor | whoever holds the key | Sigstore keyless signature bound to this repo, this workflow and refs/heads/main
|
Flow: main push → required checks green → release workflow builds
immutable images (api, worker, migrate) and the landing bundle, publishes
them by digest to GHCR, attaches SBOM + build provenance, writes a signed
release manifest → a deploy agent on the VPS (systemd timer) polls,
verifies signature and identity, then runs the staged rollout with
automatic rollback.
Images contain only public source and no secrets, so GHCR packages can be public: the VPS pulls without any token. Runtime secrets stay in the existing k8s Secret on the VPS.
- Migrate before rolling app images; refuse a rollout when the target image needs a schema newer than the database.
- Keep one surge pod (or a readiness gate) so a bad image never takes the only pod down; roll back automatically on failed readiness.
- An old image must tolerate an additive newer schema for the rollback window (expand/contract), or rollback is impossible after migrating.
- Back up (verified
pg_dump -Fc+ TOC check) before every migration.
Deliverables (one PR):
-
.github/workflows/release-staging.yml:- Trigger
workflow_runon the required workflows (quick,CI,backend) formain, proceeding only when all concludedsuccessfor the samehead_sha(a small gate job queries the check runs viaGITHUB_TOKEN); alsoworkflow_dispatchwith an explicitshainput restricted to commits reachable frommain. -
permissions:minimal per job:contents: read; build job addspackages: write,id-token: write,attestations: write. Nopull_request_target, no secrets, noenvironmentsecrets. - Every third-party action pinned by full commit SHA with a version
comment;
concurrency: release-staging(cancel-in-progress false). - Build
infra/docker/Dockerfiletargetsapi,worker,migratewithREVISION=<sha>; push toghcr.io/<owner>/abastevo-<role>:sha-<sha>; record digests. Buildlandingwith--origin https://teste.abastevo.com.brand uploadlanding-dist.tar.gz. - SBOM (syft or
docker buildx --sbom) andactions/attest-build-provenanceper image digest. -
release-manifest.json(schemaabastevo-release-manifest-v1):sha,created_at, per-roleimage@digest,landing_sha256,migrations_max(highest file inbackend/db/migrations),schema_min_supported(see Phase 3),workflow_run_url. Signed withcosign sign-blobkeyless; publish manifest +.sig/bundle as a workflow artifact and as an OCI artifactghcr.io/<owner>/abastevo-release:sha-<sha>plus moving tagstaging. - A final step prints the exact verification command
(
cosign verify-blob --certificate-identity-regexp 'https://github.com/<owner>/Abastevo/.github/workflows/release-staging.yml@refs/heads/main' --certificate-oidc-issuer https://token.actions.githubusercontent.com).
- Trigger
-
scripts/check-release-workflow.sh(run in Quick): fails if the release workflow uses unpinned actions,pull_request_target,secrets.other thanGITHUB_TOKEN,set -x,envdumps, or echoes of variables. -
.github/CODEOWNERSentry requiring owner review for.github/workflows/andinfra/deploy/.
Checks: actionlint (pinned), the new script, a dry run on a branch with
workflow_dispatch disabled for non-main refs, then one real run on main
producing verifiable artifacts. STOP if GHCR publishing needs a personal
token (it must not), if any step would need a secret, or if the required
check names differ from the ones above (record and ask).
Done when: for a main SHA, cosign verify-blob and
gh attestation verify pass for every image and the manifest; images are
pullable anonymously; Actions logs contain no host, IP, path under /opt,
or variable dump.
-
infra/deploy/agent/abastevo-deploy-agent(bash or Go, no secrets in source) +infra/deploy/agent/README.md; host config only in/etc/abastevo-deploy/agent.env(mode 600, never committed): namespace, deployment names, landing root, backup dir, receipt dir. - systemd
abastevo-deploy-agent.timer(every 2 min) + service withflock,ProtectSystem=strict,NoNewPrivileges=yes. - Each run: fetch
stagingmanifest, verify signature + certificate identity +shareachable frommain(GitHub API, anonymous), compare with/var/lib/abastevo-deploy/current.json, and write a plan receipt (what would change) without mutating anything.
Done when: the agent detects a new main release, verifies it, refuses a
tampered/unsigned/foreign-identity manifest (tested), and changes nothing.
Order per release (any failure stops and rolls back what changed):
- Schema gate: refuse if
schema_min_supportedof the running image is above the DB, or if the new image needs migrations not yet applied and the previous image cannot tolerate them (expand/contract rule). - Verified backup (
pg_dump -Fc, TOC check, retention N=7). - Migration Job with the
migratedigest; waitcomplete; record versions. - Roll api/worker by digest with
maxSurge: 1(raise the namespace quota only if the owner approves; otherwisemaxUnavailable: 0with a pre-pull) and readiness gate; on failurerollout undo. - Landing: unpack to
releases/<sha>, switchcurrentatomically. Per the ZD-08 amendment below, the worker uses an operator-configured stable path throughcurrentand its existing deduplicated 15-minute portal-refresh schedule; the deploy agent neither patches worker env nor enqueues jobs. - Smoke:
/health/ready,/,/consultar/, one nearby/list call, one search shard; on failure roll back images and landing pointer. - Write the receipt (no secrets) and keep the previous release for rollback.
Code change required first: the API/worker schema check accepts a newer
additive schema within a declared window (schema_min_supported ..
current), so rollback after a migration works.
Done when: two consecutive main merges deploy without a human, a
deliberately broken image is rolled back automatically with the site
staying up, and a rollback drill is recorded.
Status page/receipt endpoint (static JSON with release SHA and time),
failure notification to the owner (email/Telegram via a VPS-local token),
disk retention for images/releases/backups, and a runbook for pausing the
agent (systemctl stop abastevo-deploy-agent.timer).
Same artifacts, a manual workflow_dispatch approval with GitHub
environment production reviewers, and the G09 gates. Out of scope until
the owner opens it.
- Secrets, tokens, SSH keys, host names/IPs,
/optpaths or kubeconfig in the repository, workflow files, Actions logs or release manifests. -
pull_request_target, workflows triggered by forks with write tokens, unpinned actions,curl | bashinstallers,latesttags. - Deploying a SHA whose required checks did not all pass, or any commit not
on
main. - Touching other namespaces, the shared nginx config beyond the Abastevo vhost, or host packages from the agent.
Phase 3 step 5 no longer requires an extra env patch and queue write on each
release. The existing worker owns enterprise-portal-refresh on a 15-minute
schedule with dedupe/lease fencing; deployment remains storage/queue agnostic.
The operator must configure PORTAL_SEARCH_JS to the stable search script
through the landing current link and verify one scheduled refresh after a
switch. This permits up to one schedule interval before portal regeneration;
it does not claim immediate refreshed portal content. The existing source
scheduler is evidence for the mechanism, not for the live path or refresh.
Live path/refresh proof remains OWED to ZD-08. No RBAC, DB credential or
additional env rollout is granted to the agent by this amendment.
- Home
- Roadmap
- docs-README
- docs-android-build
- docs-android-design-system
- docs-android-forum
- docs-android-games
- docs-android-map-engine
- docs-android-navigation
- docs-android-ocr-image
- docs-android-ocr-live-framing
- docs-android-premium-area
- docs-android-premium-integration
- docs-android-release
- docs-android-ui-containers
- docs-architecture-android-stack
- docs-architecture-android
- docs-architecture-backend
- docs-architecture-data-sources
- docs-architecture-overview
- docs-architecture-sources-ev-research
- docs-architecture-sources-national-limits
- docs-architecture-sources-national-stations
- docs-architecture-sources-register
- docs-assets-app-tutorial-CAPTURE_CONTRACT
- docs-assets-app-tutorial-FABLE_LANDING_POLISH_PROMPT
- docs-assets-app-tutorial-README
- docs-assets-attribution
- docs-assets-brand-README
- docs-assets-flags-ATTRIBUTION
- docs-assets-fuel-icons-README
- docs-assets-games-fuel-v1-README
- docs-assets-home-icons-README
- docs-assets-landing-fleet-android-20261012-BRIEF
- docs-assets-landing-hero-20261011-BRIEF
- docs-assets-landing-illustrated-20261012-BRIEF
- docs-assets-landing-illustrated-20261012-README
- docs-assets-landing-minimal-20261012-BRIEF
- docs-assets-landing-open-data-20261026-BRIEF
- docs-assets-landing-redesign-20261011-PREPARATION_EVIDENCE
- docs-assets-landing-redesign-20261011-README
- docs-assets-landing-redesign-20261011-REFERENCE_BRIEF
- docs-assets-landing-sync-20261012-BRIEF
- docs-assets-map-icons-README
- docs-backend-anp-ingestion
- docs-backend-api
- docs-backend-community-pricing
- docs-backend-data-model
- docs-backend-domain-model
- docs-backend-driver-private-data
- docs-backend-forum-architecture
- docs-backend-forum-bulletins
- docs-backend-forum-sources
- docs-backend-payments-provider-admission
- docs-backend-payments-provider-register
- docs-backend-photos-capture
- docs-backend-photos-subset-submission
- docs-backend-premium-api
- docs-backend-premium-cloud-protocol
- docs-backend-testing
- docs-backend-toolchain
- docs-brand-app-icons
- docs-brand-identity
- docs-decisions-001-kotlin-compose-stack
- docs-decisions-002-price-import-immutability
- docs-decisions-003-nominatim-reverse-geocode
- docs-decisions-005-modular-monolith-and-postgresql
- docs-decisions-006-official-catalog-and-exact-contracts
- docs-decisions-007-anonymous-proof-of-possession
- docs-decisions-008-privacy-and-retention
- docs-decisions-009-community-consensus-and-projections
- docs-decisions-010-private-object-evidence
- docs-decisions-012-licensing-and-hosted-business
- docs-decisions-015-kotlin-multiplatform-shared-domain
- docs-decisions-016-android-commercial-community-ios-deferred
- docs-decisions-017-station-profile-and-verified-representation
- docs-decisions-021-community-first-contribution
- docs-decisions-022-comaps-derived-native-map-engine
- docs-decisions-023-admin-suite-granted-tiers-contributors
- docs-decisions-025-private-abastevo-empresas-organization-boundary
- docs-decisions-026-multilingual-public-site
- docs-decisions-README
- docs-enterprise-README
- docs-enterprise-architecture
- docs-enterprise-backlog-INDEX
- docs-enterprise-backlog-ep00-governance
- docs-enterprise-backlog-ep01-platform
- docs-enterprise-backlog-ep02-organizations
- docs-enterprise-backlog-ep03-identity-access
- docs-enterprise-backlog-ep04-sync
- docs-enterprise-backlog-ep05-fleet-meters
- docs-enterprise-backlog-ep06-trips
- docs-enterprise-backlog-ep07-gps-navigation
- docs-enterprise-backlog-ep08-fuelings
- docs-enterprise-backlog-ep09-documents
- docs-enterprise-backlog-ep10-expenses-finance
- docs-enterprise-backlog-ep11-maintenance
- docs-enterprise-backlog-ep12-fuel-stock
- docs-enterprise-backlog-ep13-intelligence
- docs-enterprise-backlog-ep14-station-claims
- docs-enterprise-backlog-ep15-station-commerce
- docs-enterprise-backlog-ep16-subscriptions
- docs-enterprise-backlog-ep17-data
- docs-enterprise-backlog-ep18-imports-notifications-integrations
- docs-enterprise-backlog-ep19-back-office
- docs-enterprise-backlog-ep20-release
- docs-enterprise-business-rules
- docs-enterprise-contract
- docs-enterprise-conventions
- docs-enterprise-data-offering
- docs-enterprise-decisions
- docs-enterprise-domain-model
- docs-enterprise-glossary
- docs-enterprise-journeys
- docs-enterprise-modules-back-office
- docs-enterprise-modules-data
- docs-enterprise-modules-documents
- docs-enterprise-modules-expenses-finance
- docs-enterprise-modules-fleet
- docs-enterprise-modules-fuel-stock
- docs-enterprise-modules-fuelings
- docs-enterprise-modules-gps-navigation
- docs-enterprise-modules-identity
- docs-enterprise-modules-imports-notifications-integrations
- docs-enterprise-modules-intelligence
- docs-enterprise-modules-maintenance
- docs-enterprise-modules-organizations
- docs-enterprise-modules-station-claims
- docs-enterprise-modules-station-commerce
- docs-enterprise-modules-subscriptions
- docs-enterprise-modules-trips
- docs-enterprise-offline-sync
- docs-enterprise-permissions
- docs-enterprise-portal-routes
- docs-enterprise-privacy-security
- docs-enterprise-product-vision
- docs-enterprise-source-admission
- docs-enterprise-state-model
- docs-enterprise-testing
- docs-enterprise-ux-app
- docs-enterprise-ux-web
- docs-operations-README
- docs-operations-backup
- docs-operations-deploy-agent
- docs-operations-dou-editions
- docs-operations-edge-cache
- docs-operations-enterprise-activation
- docs-operations-map-static-overlay
- docs-operations-moderation-feedback
- docs-operations-moderation-profiles
- docs-operations-monitoring
- docs-operations-operator-access
- docs-operations-payments
- docs-operations-premium-billing
- docs-operations-recovery
- docs-operations-registry-daily-sync
- docs-operations-registry-runs
- docs-product-README
- docs-product-admin-tiers
- docs-product-community-community-first
- docs-product-community-experience
- docs-product-community-metrics
- docs-product-community-moderation
- docs-product-community-safety
- docs-product-community-terms-pt-br
- docs-product-driver-suite-README
- docs-product-driver-suite-android-state
- docs-product-driver-suite-cloud-sync
- docs-product-driver-suite-cost-profiles-and-maintenance
- docs-product-driver-suite-driver-model-and-earnings
- docs-product-driver-suite-foundation-decisions
- docs-product-driver-suite-gps-lifecycle
- docs-product-driver-suite-mobile-hub
- docs-product-driver-suite-odometer-review
- docs-product-driver-suite-outbox-wire
- docs-product-driver-suite-quick-refuel
- docs-product-driver-suite-reports
- docs-product-driver-suite-shifts-and-distance
- docs-product-driver-suite-signed-commands
- docs-product-ev-README
- docs-product-ev-charging-stop-planner
- docs-product-ev-energy-model
- docs-product-ev-financial-method
- docs-product-ev-journey-ui
- docs-product-ev-preparation
- docs-product-ev-typed-data
- docs-product-exploration
- docs-product-forum-contract
- docs-product-forum-policies
- docs-product-glossary
- docs-product-landing-content
- docs-product-landing-guides
- docs-product-landing-organic-growth-i18n-plan
- docs-product-licensing
- docs-product-map-discovery
- docs-product-map-favorites-and-trips
- docs-product-map-reports-routing-guidance
- docs-product-notification-content
- docs-product-official-prices
- docs-product-open-source-business
- docs-product-overview
- docs-product-payments-README
- docs-product-payments-offer-policy
- docs-product-premium-README
- docs-product-premium-financial-method
- docs-product-premium-source-policy
- docs-product-stations-catalog
- docs-product-stations-fuel-feedback
- docs-product-stations-fuel-quality
- docs-product-stations-identity-and-ev-catalog
- docs-product-stations-profile-contract
- docs-product-stations-profile-representation
- docs-product-stations-registry-sources
- docs-product-vehicle-registration
- docs-product-vehicles-and-occurrences
- docs-security-android-terms-acceptance
- docs-security-free-account-access
- docs-security-identity-profile
- docs-security-media-location-policy
- docs-security-privacy-notice
- docs-security-privacy-policy
- docs-security-retention
- docs-security-risks
- docs-security-security-privacy
- docs-store-README
- docs-store-play-readiness
- docs-store-play-store-listing
- docs-store-ugc-safety
Source: AlexandreZanata/Abastevo @ e4a67580fc368a59bc1c0f1e0466fc011313f330