Deploy from GitHub Actions (v0)

GitHub Actions v0 is APCO's workflow-based alternative to the recommended GitHub App integration. It can deploy an existing project without giving the workflow access to your other projects, environment-variable API, database tools, lifecycle controls, rollback, or promotion. Existing workflows and ci:deploy credentials remain supported.

• A push to your production branch deploys to Production.
• A pull request from the same repository deploys to the existing Preview channel.
• The Actions summary links to the live URL and the exact deployment in APCO.
• A pull request gets one APCO comment that is updated on later commits.

CLI package is live

The generated workflow installs the public apco-cli@0.1 package from npm and invokes its apco executable.

Set it up

Open Dashboard → Project → Settings → GitHub Actions v0.

1. Configure the source

Choose the repository label and production branch. A linked GitHub repository prefills both fields, but linking is optional: the existing OAuth connection is never used to commit a workflow, manage GitHub secrets, download deployment source, or authenticate a deploy.

Choose whether to generate pull-request previews. Production-only setup omits the PR trigger and comment permission.

2. Create the deployment credential

Create the CI credential and copy it immediately. APCO shows the value only once.

The credential carries the setup-only ci:deploy capability:

• exactly one APCO project;
• create Production or Preview deployments;
• poll and read the build log only for deployments created with that same key;
• no project listing, settings, environment-variable API, runtime logs, metrics, database operations, lifecycle operations, rollback, promotion, or account access.

In GitHub, create an Actions repository secret named APCO_TOKEN and paste the value.

Same-repository PR trust

Fork PRs are skipped and do not receive APCO_TOKEN. Same-repository PR workflows do receive repository secrets. Because this v0 credential can select Production or Preview, every collaborator who can run a same-repository PR workflow is effectively trusted to deploy Production and to run code with the project's injected build/runtime environment.

If that is not your trust model, generate a Production-only workflow. Channel-bound App credentials and maintainer-approved PR previews belong to the GitHub App release.

3. Add the workflow

The dashboard offers two outputs:

• New workflow downloads a complete .github/workflows/apco.yml.
• Existing CI gives you explicit trigger, permission, and deploy-job blocks to merge into one existing workflow. Its needs jobs must be in that same workflow and must run on both push and pull-request events. The generated job also checks the exact event and configured branch, so broader triggers already present in that workflow cannot deploy another branch to APCO.

The dashboard's downloaded workflow is the canonical complete template and uses the same contract as the existing-CI blocks shown beside it.

4. Push or open a PR

The CLI automatically detects these GitHub values:

• GITHUB_SHA — the exact checked-out commit (normally the merge commit for a pull_request workflow);
• GITHUB_REF;
• GITHUB_REPOSITORY;
• APCO_GITHUB_PR_NUMBER, with the pull-request ref as fallback.

It records them on the deployment, streams the build log, and writes these step outputs when GITHUB_OUTPUT is available:

Output	Meaning
deployment_id	APCO deployment id
channel	production or preview
status	Terminal deployment result
release_status	Release-command result when the manifest configures one
dashboard_url	Deep link to this deployment
url	Live URL; omitted on failure/timeout

The job summary contains the same result, configured release outcome, source SHA/ref, and dashboard link. A failed deploy remains failed in Actions after the reporting/comment steps finish.

Preview behavior in v0

Each APCO project currently has one active Preview slot. If PR #12 deploys and PR #18 deploys afterward, #18 becomes the active Preview and #12's deployment-specific URL is retired. The comment says this explicitly.

The workflow does not run on PR close. The current Preview remains until a newer Preview succeeds or a platform lifecycle operation removes it. Use the GitHub App for simultaneous per-PR Previews, automatic close cleanup, GitHub Checks, and exact-SHA maintainer approval for fork PRs.

Managed databases

CI credentials cannot provision databases. If apco.yml sets database.enabled: true, prepare the exact target first with a full-access session: apco db branch production for pushes and apco db branch preview for PRs, then migrate each independently. Direct CI fails with channel-specific DATABASE_NOT_READY before queueing a build and never falls back to Production.

When release.command is configured, the Actions deploy uses the same one-shot pre-traffic release phase as CLI/GitHub App deploys. It receives the exact push/PR channel environment and database; redacted output is in build logs, and release failure keeps the prior channel deployment live.

Rotate or revoke the credential

To rotate without downtime:

1. Create a replacement from the same project settings card.
2. Replace APCO_TOKEN in GitHub.
3. run the workflow once;
4. revoke the old token after the replacement's Last used timestamp changes.

If you closed setup before copying the value, revoke that credential and create another. APCO cannot recover its plaintext.

Troubleshooting

Result	What to do
CLOUD_NOT_LOGGED_IN	Add the APCO_TOKEN Actions secret.
CLOUD_UNAUTHORIZED	Rotate an invalid or expired credential.
CLOUD_NOT_FOUND	Regenerate the workflow/credential from the correct APCO project.
CLOUD_FORBIDDEN_SCOPE	Replace a manually constructed token with the setup-generated CI credential.
DATABASE_NOT_READY	Run `apco db status --channel <production
Preview-plan error	Disable PR previews or use a plan that includes Preview deployments.
DEPLOY_FAILED	Open the deployment deep link from the summary/comment and inspect its build log.
No PR comment	Confirm the workflow grants pull-requests: write; the deployment result remains authoritative.

Do not retry authentication, project-grant, plan, or database-readiness errors unchanged. Fix the configuration first.