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 Register App in the sidebar or /apps/new. The wizard:

Selects a connected source provider and repository. Connect one from Admin → Providers → Source if none is available.
Selects the owning project and captures the app name and slug.
Fetches the configured manifest path (normally astrolift.toml) from the selected branch. You can edit a seeded manifest or register first and add the manifest later.
Chooses a deploy strategy, trigger behavior, and any approval settings.
Registers the app and, when requested and supported by the source provider, writes the managed CI workflow.

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 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

astro app init [path] creates a starter manifest. Use astro app register --help for the flags shipped by your installed CLI.

The app header groups its pages into Build, Run, Observe, Control, and Secure. Common pages include:

Overview — current status and useful actions.
Config / Manifest — edit and synchronize the TOML source.
Deployments / Environments / Workloads — runtime state.
Topology — rendered relationships between workloads and resources.
Observability / Logs — live and historical signals.
Shell / Commands — interactive and one-shot access to a running container.
Managed Services / Domains — attached platform resources.
Secrets / Tokens / Security — credentials and security posture.

Edit and synchronize the manifest¶

/apps/<slug>/config supports source and form views. 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;
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.

Deploy¶

The global /deployments page and an app's Deployments page 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. Building and publishing the image normally happens in the managed source workflow before this command. 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. Do not infer success from a CI job alone; confirm the Astrolift deployment reached a terminal success state.

Secrets and secret bundles¶

/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;
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 and organization secret-bundle CLI groups are placeholders in the current release and contain no CRUD subcommands. Use the dashboard or GraphQL API for these operations today.

Environments, workloads, and logs¶

/apps/<slug>/environments lists deploy targets, cluster placement, rollout controls, URLs, and approval configuration. /apps/<slug>/workloads and the workload detail pages show the manifest definition and live status.

Use Observe → Logs for pod output. Use Control → Shell for an interactive terminal and Control → Commands for one-shot commands. These operations are permission-gated and audited. The former /console route redirects to Logs; shell access has its own route.

CLI equivalents include:

astro app logs --app <app-slug>
astro app exec --app <app-slug> -- <command>

Run each command with --help because workload/container selection flags depend on the operation.

Managed services¶

/apps/<slug>/managed-services provisions and binds 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.

Domains¶

/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.

The global /domains page gives operators an organization-wide view.

Webhooks¶

/apps/<slug>/webhooks manages outbound event subscriptions scoped to the app. Organization-wide subscriptions live under Admin → 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 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.

Members and deletion¶

/apps/<slug>/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.

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 confirmation carefully:

astro app deregister --help

Do not delete the Kubernetes namespace by hand first; doing so bypasses ordered cleanup and makes the teardown report less reliable.