Skip to content

Working with Apps

This guide walks through the dashboard's app-management surfaces in the order you typically use them: register an app, deploy it, edit its manifest, manage its secrets and sub-resources, and run ad-hoc commands.

Every app sub-resource lives under /apps/<slug>/.... The slug is the app's stable identifier — set at registration, immutable afterwards.

Registering an app

/apps/new is the registration wizard.

  1. Pick a project. Apps live inside a team's project; create one on /projects first if you don't have one.
  2. Give the app a display name and slug. Slug is auto-generated from the name (lowercase, hyphens) but editable.
  3. Pick a source. Either:
  4. Connected host — pick a stored SCM connection (GitHub / GitLab / Bitbucket / Gitea) and choose a repo from the list. The form auto-fills the source URL, kind, and default branch.
  5. Manual — paste a clone URL and pick the source kind.
  6. Confirm manifest_path (defaults to astrolift.toml) and deploy_branch.

On submit, the platform fires OnboardAppWorkflow: provisions a Kubernetes namespace, registry repo, and workload identity. The app's status moves through pending → provisioning → ready (or failed with an error you can read on the overview page).

App overview

/apps/<slug> is the operational landing page.

The hero shows the app's name, description, and a row of quick actions: Open (the primary public URL), Deploy, Config (the manifest editor), Source (the source repo in your SCM), and Delete (soft-delete only). When the screenshot service has captured the app's homepage, a thumbnail sits to the left of the name.

Below the hero, a four-card status row: provisioning state, workload count + replicas, source repo + manifest path, and trigger mode + Kubernetes namespace.

The Topology card maps the app's live shape: ingress → services → workloads, plus any managed services and external dependencies. Each node is colour-coded by status (running / provisioning / failed / unknown) and clickable — click a workload to drill into its detail page. Public workloads carry their hostname as a chip.

Below the topology: Recent deployments (last 5), Recent events (filtered to this app), and the Workloads table.

Editing the manifest

/apps/<slug>/config is a side-by-side TOML editor.

The left pane is the source astrolift.toml. The right pane re-renders the platform's view of the manifest as Kubernetes resources — the same render the deploy activity will apply.

A sync state badge in the header tells you where things stand:

  • In sync — the database snapshot matches the repo.
  • Unsaved drafts in DB — you've edited via the dashboard but haven't pushed to the source repo yet.
  • Repo ahead — the repo has new commits the platform hasn't pulled.
  • Diverged — both sides have changed independently.

Three actions:

  • Save draft — stages your edit in the platform. The next deploy uses the staged version.
  • Sync from repo — pulls the source astrolift.toml and discards any unsaved draft. Use this when you've edited the file in your editor and committed.
  • Push to repo — opens a PR with your staged changes against the source repo. Available once the platform has a connected SCM with write access.

The render preview surfaces validation errors with file path + line number when the renderer rejects the TOML.

Deployments

/deployments lists every rollout across every app. Filter by app slug or status; the list polls + listens to a live subscription so in-flight rollouts update without refresh.

Click a row to open /deployments/<id>:

  • Header — status badge, trigger kind (push / manual / CI / scheduled / rollback / promotion), approval state when required.
  • Metadata grid — image tag and digest, cluster revision, workload, timestamps for created / started / succeeded / failed, duration, and CI context (commit, branch, run URL) when known.
  • Lifecycle log — every state transition the workflow recorded, with detail expansion for failed steps.
  • Rendered manifests — the Kubernetes resources for this exact deploy (or the renderer's error path).
  • Recent events — platform events tied to this app.

Per-row actions in the list and per-page actions on the detail page (gated by your permissions): Approve when waiting on approval, Abort while in flight, Rollback while running, Redeploy to push the same image again.

Secrets

/apps/<slug>/secrets is the env-table editor.

The page lists keys from three sources:

  • Literal — values written directly into the manifest's [env] table.
  • Bundle — keys exposed by an attached Secret Bundle.
  • Managed service — connection envelope keys (e.g. DATABASE_URL) injected by an attached managed service.

The platform never returns plaintext values. Only the user-supplied value at submit time leaves the browser; reads always show as masked.

Filter by environment with the dropdown above the table. Use New secret to set a literal, Bulk import to paste a .env file (each KEY=value line gets staged), or remove a literal with the per-row trash button. Set/delete writes to manifest_raw_staged — push to repo from the Config page to land it.

Environments and workloads

/apps/<slug>/environments lists deploy targets (staging, prod, etc.) with their cluster, public URL, replica count, paused state, and required-approval count. Pause an environment to halt CI/push triggers; resume to re-enable.

/apps/<slug>/workloads/<workloadSlug> is the per-workload detail. The general card shows kind, replicas, HPA bounds, CPU/memory requests + limits, storage class. The containers card lists each declared container with image ref, port, healthcheck, command/args, and any env that's pinned in the manifest. For cronjob workloads, an additional Recent runs card lists the last 10 scheduled invocations with status and exit codes.

Managed services

/apps/<slug>/managed-services lists databases, caches, queues, object stores attached to the app, scoped per environment.

Provision opens a sheet to pick environment, kind (postgres, redis, s3, sqs, mysql, kafka, etc.), and an optional name + variant (e.g. db.t4g.medium). The platform writes a row in pending, the workflow loop creates the upstream resource, and the row moves to active.

Deprovision soft-deletes; the workflow loop tears down upstream before the row leaves visibility entirely.

The connection envelope keys (DATABASE_URL, REDIS_URL, etc.) appear automatically on the Secrets page once the service is active.

Custom domains

/apps/<slug>/domains lists hostnames bound to the app, with cert state, validation method, validation token, and last-checked timestamp.

Add domain captures a hostname; the platform issues a DNS validation challenge. Copy the validation token into your DNS provider as a TXT record, then click Recheck — once propagation completes, the cert state moves from pending to validated.

Remove soft-deletes the binding so the hostname can be re-bound elsewhere.

Webhooks

/apps/<slug>/webhooks lists outbound webhook subscriptions for this app's event stream — separate from the org-wide webhooks at /webhooks.

Create a subscription with a URL and a list of event types. The platform mints a signing secret (HMAC-SHA256) shown once on the next screen — copy it into your receiving system. Every delivery includes that signature so you can verify authenticity.

The page surfaces the last delivery timestamp + response status per subscription. Failed-delivery counts roll up on the row.

Deploy tokens

/apps/<slug>/tokens lists API tokens that CI runners use to push deployments to this app.

Create a token with a name, optional comma-separated scopes (defaults to all), and an expiry (default 365d). The plaintext secret is shown once in a copy-to-clipboard dialog — paste it into your CI secret store immediately. The platform stores only a hash + the last 4 characters.

Per-row actions:

  • Rotate — issues a new secret. The previous one stays valid for a 24h grace window so a CI rotation doesn't break in flight.
  • Revoke — invalidates immediately. CI flows using this token break right away; use Rotate when you want a graceful handoff.

Members

/apps/<slug>/members shows role bindings scoped to this app — users granted an APP-level role on this specific app. Org and team-level bindings apply automatically and aren't shown here; manage those on /members and /teams respectively.

The card at the top lists the APP-scope roles available for grant. The table below lists active bindings with the role slug, grant time, and expiry.

To grant an app-level role, go to /members, click Grant role, pick a role with scopeLevel=APP, and pick this app from the scope dropdown.

Running commands

/apps/<slug>/commands opens a one-shot exec session against a container.

  1. Pick a workload (defaults to the first public workload).
  2. Pick a container (defaults to the primary container).
  3. Type a command. The platform runs sh -c "<your command>" in the container.
  4. Click Run.

Output streams live. stdout in default colour, stderr tinted destructive, system messages (exit codes, connection events) muted-italic. Stop closes the session cleanly.

The dashboard remembers your last 20 commands per app — chips above the input let you re-run with one click.

Soft delete

Every business object on the dashboard supports soft delete only. Apps, workloads, environments, managed services, domains, webhooks, tokens, and role bindings — deletion marks them inactive and reclaims the slug after a grace window. Recovery is a backend operation; ask your operator if you deleted something by mistake.