Prerequisites

Every platform guide assumes you have done the three things on this page: created a deploy-scoped API key, decided where to store it, and pinned the CLI version. Do these once, then follow your platform guide.

Create a deploy-scoped API key

CI authenticates to Aether with an API key. Create one in the dashboard, under API Keys, scoped to deploy.

Keys are created there rather than from the CLI on purpose: a credential able to mint credentials renews itself past any revocation, so issuing one takes a dashboard login session. You can still list and revoke from the terminal with aether api-key ls and aether api-key rm <id>.

The dashboard shows the key, starting with aether_sk_live_, exactly once. Copy it now, because you cannot read it again later. Give each pipeline its own key with a recognizable name, such as github-actions-myapp, so you can revoke one without disturbing the others.

Scoping it to deploy limits the key to publishing releases. If it leaks, it cannot manage apps or change account settings.

Do not use a session access key

The dashboard can also create session access keys, under Account → CLI access keys; aether access-key add no longer works from the terminal. Those keys are tied to your user account, expire after 60 days and stop working when you reset your password, which makes them a bad fit for CI. Use an API key instead.

Plain aether login is no help here either: it opens a browser and waits for a person to approve the machine. Where the runner sets CI=true (GitHub Actions, GitLab CI, CircleCI, and Bitrise all do), the CLI notices and refuses browser sign-in outright, so the job fails immediately instead of waiting on a browser nobody will open. Jenkins does not set it, so its template sets CI itself; the Bitrise template sets it too, which keeps the behavior the same under a local bitrise run, where the Bitrise CLI sets CI=false. You can also pass --ci, or just always pass --accessKey as the guides do.

Store the key as a secret

Treat the key like a password. Never commit it to the repository or echo it in build logs. Each CI system has its own secret store, and the platform guides cover the specifics:

• GitHub Actions: a repository or environment secret.
• GitLab CI: a masked and protected CI/CD variable.
• CircleCI: an organization context.
• Jenkins: a Secret text credential.
• Bitrise: a Secret in the Workflow Editor, left unexposed to pull requests.

The Aether server URL is configuration, not a secret. Leave it unset to use the CLI’s built-in production endpoint. Set it only when you target another server, such as Aether staging at https://api-staging.aetherpush.com.

Pin the CLI version

Install an exact version of the CLI and check it before releasing:

npm install -g "@aetherpush/cli@0.6.0"

INSTALLED=$(aether --version | tr -d ' \r\n')
if [ "$INSTALLED" != "0.6.0" ]; then
  echo "Installed Aether CLI '$INSTALLED' does not match pinned '0.6.0'."
  exit 1
fi

Pinning keeps builds reproducible: the same commit produces the same bundle, regardless of what the latest published CLI happens to be. The GitLab, CircleCI, Jenkins, and Bitrise templates all pin 0.6.0 and fail the build on a mismatch. The GitHub Action pins the CLI for you through its version tag, so the GitHub Actions guide pins the action instead.

What the pipeline releases

With the key stored and the CLI pinned, each guide wires up the same flow:

• Staging releases automatically on merge to your main branch, at 100% rollout.
• Production releases at 25% rollout, behind a manual approval inside the pipeline on GitHub Actions, GitLab CI, CircleCI and Jenkins, and as a separately started workflow on Bitrise.

Both are deployment channels on the same app. See the overview for how the release command works, then continue to your platform guide.