Working with Apps

An Astrolift app is a registered source-repository slice plus its manifest, environments, workloads, and operational resources. The app slug is its stable URL identifier.

Register an app

Open Apps › New app (/apps/new), or run Register new app from the command palette. The page has three numbered steps:

1. Source: the connected source provider, the repository, and the astrolift.toml manifest it fetches from the selected branch (normally astrolift.toml; a monorepo app names its own path). Connect a provider from Admin › Providers (/providers#source) if none is available. The step shows the detected build context and Dockerfile.
2. Run: the app's name and project, then how and when it deploys: build mode, deploy strategy, trigger behavior, and any approval settings (an approver team or named approvers, who cannot approve their own push).
3. Review: what will be created and what will deploy. Nothing happens until you create it; when requested and supported by the source provider, the managed CI workflow is written at that point.

A repository may contain multiple independently registered apps or agents. Give each registration its own manifest path. Registering an app requires at least one managed tenant cluster in the organization; the refusal reads No managed cluster connected. Visit /clusters and finish bringing a cluster into management before adding apps.

The CLI path is explicit and scriptable:

astro app register \
  --project-id <project-guid> \
  --source-repo owner/repository \
  --manifest-path path/to/astrolift.toml \
  --file path/to/astrolift.toml \
  --yes

<project-guid> is the id of a project in astro project list --json. Without --yes, register shows the detected build context and asks Use this? [Y/n/edit]. On success it prints Registered app: <name> (<slug>). --build-mode platform_build hands the build to the platform; --manifest-raw sends the local manifest when the platform cannot read the repository yet; --ttl 7d or --expires-at <RFC 3339> registers a temporary app. astro app init [path] creates a starter manifest. Use astro app register --help for the flags shipped by your installed CLI.

App navigation

The app page is one row of tabs under /apps/<slug>; each tab holds sections selected by ?section=:

• Overview: current status, topology, and useful actions.
• Deployments: rollout history, plus Previews.
• Workloads: manifest definition and live status, plus Scheduled jobs and Managed services.
• Logs & metrics: Logs, Metrics, Console (an interactive shell), and Commands (one-shot).
• Domains: custom hostnames and their validation state.
• Secrets: literal secrets and Attached bundles.
• Access: Members, Deploy tokens, Security scans, and Edge access.
• Settings: General, Configuration, Manifest, Webhooks, Environments, and Danger zone.

Older routes such as /apps/<slug>/config or /apps/<slug>/console redirect into the tab that absorbed them.

Edit and synchronize the manifest

Settings › Configuration supports a form view and Settings › Manifest the TOML source. TOML remains the source of truth; the form view is a controlled projection and refuses unsafe round trips for shapes it cannot preserve.

The page distinguishes the repository manifest, the saved platform draft, and unsaved browser edits. The available actions let you:

• save the current draft to Astrolift;
• fetch the source version from the configured repository and branch;
• push a platform draft back through the connected source provider as a pull request;
• render and inspect the Kubernetes resource projection.

Review a conflict before replacing either side. A repo sync can discard an unsaved browser edit, while a source push changes the repository. App secrets survive a repo sync and are left out of the pull request.

The CLI round-trips the same draft:

astro app manifest pull --app <app-slug>
astro app manifest push --app <app-slug>

pull replaces the staged draft with the manifest in the repository; push opens a pull request carrying the staged draft and prints its URL. Both prompt for confirmation unless --yes is given. Validate a manifest against the installation with astro ci render (see CLI › CI).

Deploy

The global /deployments page and an app's Deployments tab show rollout state and history. A deployment detail page includes trigger metadata, timing, rendered resources, workflow events, and failure information available for that run.

To deploy a prebuilt image from the CLI:

astro app deploy \
  --app <app-slug> \
  --env production \
  --image-tag <tag> \
  --wait

--image-tag is required for ci_pushed apps, where building and publishing the image happens in the managed source workflow before this command; a platform_build app omits it and builds the registered branch. The command prints Deployment started: <id> and, with --wait, each status until Final status: running. failed, superseded and rolled_back end the command with exit 1. Approval and concurrency policy can keep a deployment pending or supersede an older in-flight deployment.

Use the deployment detail page to approve, cancel, retry, promote, or roll back when the current state and your permission allow it. The CLI equivalents are astro app promote --from <env> --to <env> and astro app rollback [deployment-id], which rolls forward to the prior superseded deployment's exact image. Do not infer success from a CI job alone; confirm the Astrolift deployment reached a terminal success state.

Deployed is not the same as reachable. The app header, the Apps list row and the URL card read Live only while every public host has its Ingress, a Ready certificate and a hostname claim behind it; otherwise they read Provisioning, Needs reprovision or No managed domain, and the Apps list can filter on the last two. Needs reprovision means the workload runs but something behind its host is missing or drifted, which is what an app registered while the organization had no managed zone looks like after the zone comes back. The URL card's Reprovision button, and astro app reprovision --app <slug> --wait, re-render and re-apply those resources against the running image with no build, no restart unless the rendered workload changed, and nothing deleted. No managed domain means no zone resolves for the organization; an operator fixes the zone first, under Running an organization. Force redeploy is a different action: it tears the environment down and recreates it, and drops traffic while it does.

Secrets and secret bundles

The Secrets tab (/apps/<slug>/secrets) is backed by the configured provider secret store. Secret values are not written into astrolift.toml or the staged manifest.

The page supports:

• set, edit, rotate, and delete for literal app secrets;
• bulk import from .env text;
• reveal when the backend supports disclosure and the viewer has secret.read;
• value history and provenance metadata;
• production, preview, or preview-branch scope;
• reusable Secret Bundle attachments and detach operations, under Attached bundles;
• expiry metadata and rotation warnings.

Bundle and managed-service values are owned by their source. Detach the bundle or operate on the managed service instead of trying to overwrite a derived row. Reveal is audited and intentionally unavailable for write-only backends such as GitHub Actions secrets.

The app-secret CLI supports metadata listing and literal value writes:

astro app secrets list <app-slug> --environment production --json
astro app secrets create API_KEY <app-slug> --stdin --scope production < /secure/path/api-key
astro app secrets delete UNUSED_KEY <app-slug> --yes

create also updates an existing key. Without --stdin, it uses a hidden terminal prompt; file input uses shell redirection, not a --file flag. Omitting --scope preserves an existing key's scope and defaults to all for a new key. A successful write prints Created secret API_KEY on app <app-slug>. (or Updated ...). When policy requires review, the command prints ... requires approval; queued as proposal <id>. and nothing changes until an approver acts in the console. A write refused with api token scope does not allow this permission needs a credential carrying secret:write, whatever your role allows. The organization secret-bundle CLI group remains a placeholder; use the dashboard, the GraphQL API, or astro api graphql for bundle CRUD.

Environments, workloads, and logs

Settings › Environments lists deploy targets, cluster placement, rollout controls, URLs, and approval configuration; the organization-wide list is at /environments. /apps/<slug>/workloads and the workload detail pages show the manifest definition and live status.

Use Logs & metrics › Logs for pod output, Logs & metrics › Console for an interactive terminal, and Logs & metrics › Commands for one-shot commands. These operations are permission-gated and audited; opening a console asks for a fresh sign-in. The former /console and /shell routes redirect into this tab.

CLI equivalents include:

astro app logs --app <app-slug> -f
astro app exec --app <app-slug> -- <command>
astro app events --app <app-slug>
astro app environments list --app <app-slug>

Run each command with --help because workload/container selection flags depend on the operation. Restarting or scaling one exact environment goes through astro app workload review, restart, and scale; see Reviewed environment controls.

Managed services

Workloads › Managed services shows the services bound to the app, and Settings › General › Managed services administers them. A service is a supported (kind, variant) offered by the cluster's provider plugin. Availability is provider-specific; do not assume every cloud offers every kind.

Provisioning is asynchronous. Wait for the service to become available before depending on its binding. Deprovisioning defaults should preserve data and safety guards; destructive data deletion and force-destroy are separate operator choices.

Bindings expose literals, secret references, identity grants, or volume mounts depending on the service. Secret material stays in the configured secret backend.

astro app services list and show are read-only views of one app's bindings. Services shared across a project's apps and agents are provisioned and attached with astro project resources; see Shared services.

Domains

The Domains tab (/apps/<slug>/domains) manages custom hostname bindings and their validation/certificate state. The exact challenge is provider-specific. Follow the DNS records shown by the page and wait for validation before treating the hostname as live. astro app domains list prints the same bindings.

The global /domains page gives operators an organization-wide view, including the managed zones apps and previews are routed under. Domains and DNS diagnostics covers connecting a zone and reading the checks.

Webhooks

Settings › Webhooks manages outbound event subscriptions scoped to the app. Organization-wide subscriptions live under Admin › Webhooks (/webhooks).

The intended generic-delivery signature contract is documented in Webhook Signature Verification. The current control plane has a signing-key defect, so do not rely on its dashboard test or production outbound delivery until the installed release includes the fix. The page still shows recorded delivery attempts.

Source webhooks are different: GitHub, GitLab, Bitbucket, or Gitea sends those inbound events to Astrolift to trigger source synchronization and workflows.

API and deploy tokens

App deploy tokens live under Access › Deploy tokens and are intended for CI. Their plaintext is shown only when created or rotated; Astrolift stores a verifier rather than returning the token again. Rotation supports an overlap window, while revoke is an immediate cutoff.

Organization API keys are managed separately at /tokens. Their bearer scopes form a ceiling over the user's or service account's RBAC grants, so both layers must permit an operation.

Edge access

Access › Edge access restricts an app behind the cluster's central login to named identity-provider groups or user emails. Without a rule, every signed-in user may enter. The rule is enforced at the Envoy edge and takes effect on the running app without a deploy; a user outside the list gets a no-access page.

astro app access show <app-slug>
astro app access allow <app-slug> --group <idp-group>
astro app access allow <app-slug> --user <email>
astro app access deny <app-slug> --user <email>
astro app access clear <app-slug>

Group names are the identity provider's; astro auth-users list shows them. allow asks before a change would remove someone's access; pass --yes in automation.

Temporary apps

An app registered with --ttl or --expires-at, or whose manifest sets [app] expires_in, is torn down when its expiry fires. The minimum is 15 minutes; organization policy sets the maximum and whether retained data is kept for a grace period.

astro app list --temporary
astro app extend <app-slug> --by 2d
astro app expiry <app-slug> --clear --yes

The apps list and the app header show the expiry. Temporary apps covers deadlines, extensions, policy, and warnings.

Members and deletion

Access › Members shows access associated with the app. Organization, team, and project grants can also apply even when they are managed from Admin rather than this page.

Settings › Danger zone archives, deletes, or deregisters an app. Normal application removal is soft-delete plus an asynchronous teardown workflow. For permanent deregistration and cloud-resource teardown, use the dedicated deregister flow and read its inventory carefully:

astro app deregister <app-slug>
astro app deregister <app-slug> --yes

Without --yes, the command prints only the inventory of what the teardown would destroy and changes nothing. With --yes, it prints Deregister workflow started: <workflow-id>; a grace window of about five minutes precedes the first destructive activity, and the printed workflow id cancels the run within it. Do not delete the Kubernetes namespace by hand first; doing so bypasses ordered cleanup and makes the teardown report less reliable.