Skip to main content

Getting Started

This guide walks you through activating Astra on a site, connecting your GitHub repository, and watching your first PR get opened.

Prerequisites​

Before you begin, make sure you have:

  • A SkySignal site that is already reporting data (see Getting Started with the Agent)
  • A Pro plan subscription on the site
  • Admin or maintain access to the GitHub repository for the site
  • The repository must contain the source code that the agent is reporting from
Pro plan required

Astra is a Pro-plan feature. If your site is on the Free or Starter plan, you will see an Upgrade prompt on the AI DevOps tab instead of the activation flow.

Step 1: Open the AI DevOps Tab​

  1. Log in to your SkySignal dashboard
  2. Open the site you want to activate Astra on
  3. Click the AI DevOps tab (marked with a PRO badge)

If you are on the Pro plan but have not yet added Astra, you will see an Unlock Astra AI banner.

Step 2: Subscribe to the Astra Add-on​

Click Add-on on the Unlock Astra AI banner. This:

  • Adds the Astra add-on to the site's subscription
  • Credits your site with $50 of Astra credits for the current billing period
  • Unlocks the Configuration panel and the job pipeline

Once subscribed, the banner switches to a green AI Add-on Active bar showing your credit usage.

Step 3: Open the Configuration Panel​

Click the Configure button in the top-right of the AI DevOps tab. This opens a collapsible panel with two sections:

  • GitHub Integration — connect the repo Astra should open PRs against
  • Trigger Settings — control when Astra runs automatically

For now, we will focus on GitHub Integration.

Step 4: Install the GitHub App​

In the GitHub Integration section, click Install GitHub App. A new tab opens on GitHub's app installation screen.

  1. Choose the GitHub organization or personal account that owns the repository
  2. Select Only select repositories and pick the repo for this site
    • You can add more repositories later; start with the one you need now
  3. Click Install & Authorize

GitHub redirects you back to SkySignal. The GitHub Integration panel now shows a green Connected badge with your GitHub account name.

Required permissions

The SkySignal GitHub App requests Contents: Read & Write (to push branches), Pull requests: Read & Write (to open PRs), and Metadata: Read (standard). It does not request write access to your default branch — Astra always opens PRs, never commits to main/master directly.

Step 5: Assign the Repository and Branch​

With the GitHub App installed, the panel shows two inputs:

  • Repository — an autocomplete field listing every repo the app has access to
  • Branch — the base branch Astra opens PRs against (defaults to main)
  1. Pick the repository from the dropdown (e.g. your-org/your-meteor-app)
  2. Set the Branch to the branch you want Astra to target (main, develop, etc.)
  3. Click Save

You should see a Repository configured toast. The panel now shows the repo and branch as read-only chips with Change and Disconnect actions.

Step 6: Verify with Your First Job​

The fastest way to confirm the pipeline works end-to-end is to trigger a job manually.

  1. Open the Errors tab on the same site
  2. Find an error you are comfortable seeing a PR for
  3. Click the Fix with Astra button on the error row
  4. Return to the AI DevOps tab

You will see a new row at the top of the Analysis Jobs table with a pulsing status dot. It progresses through:

queued → analyzing → fetching_code → fixing → testing → pr_created

When the status reaches PR Created, click the GitHub icon in the rightmost column of the row to open the pull request. You should see:

  • A fix on a new branch named something like astra/error-fix-<shortid>
  • A commit message describing the root cause
  • A regression test covering the bug
  • The PR body linking back to the SkySignal error

Review, approve, and merge as you normally would.

First-run debugging

If the job stalls at fetching_code, your GitHub App likely does not have access to the repo you configured. Reopen the GitHub App installation from the Configure → GitHub Integration panel and confirm the repo is listed.

Step 7 (Optional): Configure Auto-Triggering​

Once you trust the kind of PRs Astra opens, return to the Configure panel and open Trigger Settings. Useful first settings:

  • Auto-Trigger — turn on to let Astra run automatically on new errors
  • Min Severity — start with High or Critical to avoid noise
  • Min Error Count — require the error to have happened at least N times
  • Cooldown — 60 minutes prevents retrigger storms
  • Allowed Job Types — unselect job types you are not ready for (e.g. leave off general_optimization initially)

See Triggering Astra for the full reference.

Troubleshooting​

Install GitHub App button does nothing​

The SkySignal GitHub App is not configured on your self-hosted or preview environment. On dash.skysignal.app this works out of the box. Contact support if you are running a dedicated deployment.

Jobs stall at queued​

Check your add-on status bar — if you have exhausted your $50 of credits and have not enabled overage billing, new jobs are held at queued. Upgrade your credit budget or wait for the next billing period.

Job fails with "repository not accessible"​

The GitHub App was installed but does not have access to the repo you picked. Go to GitHub → Settings → Applications → SkySignal → Configure, and add the repository to the allowed list.

Astra opened a PR against the wrong branch​

Re-open the Configure panel and update Branch in the GitHub Integration section. Future jobs will target the new branch; existing PRs are unchanged.

Next Steps​

  • Job Types — What the eight Astra job types actually produce
  • Triggering Astra — Manual trigger buttons and auto-trigger rules
  • Overview — How Astra's pipeline works end to end