From fd4e2956363d5919a3378f1464fac978f41c8db3 Mon Sep 17 00:00:00 2001 From: Mac Carrithers Date: Fri, 20 Mar 2026 10:29:46 -0600 Subject: [PATCH 1/6] feat: Update documentation surrounding CI and API keys --- src/content/docs/account/api-keys.mdx | 89 +++++++++++++++++++ .../docs/code-push/ci/_authentication.mdx | 56 +++++------- src/content/docs/code-push/faq.mdx | 7 +- 3 files changed, 117 insertions(+), 35 deletions(-) create mode 100644 src/content/docs/account/api-keys.mdx diff --git a/src/content/docs/account/api-keys.mdx b/src/content/docs/account/api-keys.mdx new file mode 100644 index 00000000..32f5d9b0 --- /dev/null +++ b/src/content/docs/account/api-keys.mdx @@ -0,0 +1,89 @@ +--- +title: API Keys +description: Create and manage API keys for CI and programmatic access +sidebar: + order: 3 +--- + +API keys let you authenticate with Shorebird from CI systems and other +automated environments. You can create, view, and revoke API keys from the +[Shorebird Console](https://console.shorebird.dev). + +## Creating an API Key + +1. Open **Account → API Keys** in the console. +2. Click **Create API Key**. +3. Enter a descriptive name (e.g., "GitHub Actions — my-app"). +4. Choose an expiration period. +5. Select a permission level. +6. Click **Create**. + +The full key value is shown exactly once after creation. Copy it and store it +securely — it cannot be retrieved again. + +## Using an API Key + +Set the key as the `SHOREBIRD_TOKEN` environment variable in your CI platform. +Shorebird CLI commands will authenticate automatically when this variable is +present. + +```sh +export SHOREBIRD_TOKEN="" +shorebird patch android +``` + +For platform-specific setup, see our CI guides for +[GitHub Actions](/code-push/ci/github/), +[Codemagic](/code-push/ci/codemagic/), or the +[generic CI guide](/code-push/ci/generic/). + +## Expiration + +API keys default to a one-year expiration. During creation you can choose from: + +- 30 days +- 90 days +- 1 year (default) +- No expiration + +All expiration options are available on every plan. + +## Permissions + +API keys support two permission levels: + +- **Full access** — the key has the same permissions as your account. Available + on all plans. +- **Release & Patch only** — the key can create releases and patches, but cannot + manage apps, organizations, members, or billing. Available on Pro and Business plans. + +## Revoking an API Key + +To revoke a key, find it in the API Keys list and click **Delete**. Revocation +is immediate — any CI pipeline using that key will fail on its next run. This +action cannot be undone. + +## Migrating from `shorebird login:ci` + +The `shorebird login:ci` command is deprecated. Existing tokens generated by +`login:ci` will continue to work until March 2027, but we recommend replacing +them with API keys created from the console. + +To migrate: + +1. Create a new API key in the console. +2. Replace the `SHOREBIRD_TOKEN` value in your CI secrets with the new key. +3. Verify your CI pipeline runs successfully. + +The `SHOREBIRD_TOKEN` environment variable name has not changed, so no workflow +file edits are needed beyond updating the secret value. + +## Security + +- API keys use the `sb_api_` prefix. This prefix is registered with + [GitHub secret scanning](https://docs.github.com/en/code-security/secret-scanning/introduction/about-secret-scanning), + so leaked keys in public repositories are flagged automatically. +- Keys are stored as irreversible hashes. Shorebird cannot retrieve a key value + after creation. +- Treat API keys like passwords. Store them in your CI platform's secrets + manager and do not commit them to source control. diff --git a/src/content/docs/code-push/ci/_authentication.mdx b/src/content/docs/code-push/ci/_authentication.mdx index adc253bf..4d6bfa23 100644 --- a/src/content/docs/code-push/ci/_authentication.mdx +++ b/src/content/docs/code-push/ci/_authentication.mdx @@ -1,44 +1,36 @@ -Most Shorebird functionality, like creating releases and patches, requires being -authenticated. In order to authenticate with Shorebird in CI, you will need to -generate a CI token. +Most Shorebird functionality, like creating releases and patches, requires +authentication. To authenticate in CI, create an API key from the +[Shorebird Console](https://console.shorebird.dev): -```sh -shorebird login:ci -``` +1. Go to **Account → API Keys**. +2. Click **Create API Key**. +3. Give the key a name (e.g., "GitHub Actions — my-app"), choose an expiration, + and select a permission level. +4. Copy the key value — it is only shown once. -You will be prompted to go through a similar OAuth Flow as when using -`shorebird login`, however, `shorebird login:ci` will not store any credentials -on your device. Instead, it will output a base-64 encoded auth token that you -will use in your CI environment. +Use this key as your `SHOREBIRD_TOKEN` in CI. The environment variable name is +unchanged from previous versions. -The output of this command should look something like: - -{/* cSpell:disable */} - -``` -$ shorebird login:ci -The Shorebird CLI needs your authorization to manage apps, releases, and patches on your behalf. - -In a browser, visit this URL to log in: - -https://auth.shorebird.dev/login... - -Waiting for your authorization... +:::caution -🎉 Success! Use the following token to login on a CI server: +`SHOREBIRD_TOKEN` is a secret. Do not check it into source control or share it +publicly. Store it in your CI platform's secrets manager. -qwerasdf1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqwer1234asdfqw== +::: -Example: +:::note -export SHOREBIRD_TOKEN="$SHOREBIRD_TOKEN" && shorebird patch android -``` +On Pro and Business plans, you can restrict an API key to **Release & Patch +only** permissions — the key can create releases and patches but cannot manage +apps, organizations, members, or billing. -{/* cSpell:enable */} +::: -:::caution +:::tip[Migrating from `shorebird login:ci`] -The `SHOREBIRD_TOKEN` is a secret and should not be checked in to your source -control or shared publicly. +The `shorebird login:ci` command is deprecated. Existing tokens generated by +`login:ci` will continue to work until March 2027, but new tokens should be +created from the console. The `SHOREBIRD_TOKEN` environment variable name has +not changed, so your CI workflow files need only a new key value. ::: diff --git a/src/content/docs/code-push/faq.mdx b/src/content/docs/code-push/faq.mdx index 85824ddf..d54804e0 100644 --- a/src/content/docs/code-push/faq.mdx +++ b/src/content/docs/code-push/faq.mdx @@ -69,9 +69,10 @@ for distribution. ### Can I use Shorebird from my CI system? -Yes. Shorebird is intended to be used from CI systems. We've published a -[generic guide for CI setup](/code-push/ci/generic/) as well as other CI -systems. +Yes. Create an API key in the [Shorebird Console](https://console.shorebird.dev) +under **Account → API Keys**, then add it to your CI environment as +`SHOREBIRD_TOKEN`. See our [CI setup guide](/code-push/ci/generic/) for detailed +instructions. ### Can I use Dart defines with Shorebird? From 096676ecb6246adfcdb2b25fc35ff5694c101a0c Mon Sep 17 00:00:00 2001 From: Mac Carrithers Date: Fri, 20 Mar 2026 10:52:39 -0600 Subject: [PATCH 2/6] fix: npm run format --- src/content/docs/account/api-keys.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/content/docs/account/api-keys.mdx b/src/content/docs/account/api-keys.mdx index 32f5d9b0..06c222fb 100644 --- a/src/content/docs/account/api-keys.mdx +++ b/src/content/docs/account/api-keys.mdx @@ -5,8 +5,8 @@ sidebar: order: 3 --- -API keys let you authenticate with Shorebird from CI systems and other -automated environments. You can create, view, and revoke API keys from the +API keys let you authenticate with Shorebird from CI systems and other automated +environments. You can create, view, and revoke API keys from the [Shorebird Console](https://console.shorebird.dev). ## Creating an API Key @@ -33,9 +33,8 @@ shorebird patch android ``` For platform-specific setup, see our CI guides for -[GitHub Actions](/code-push/ci/github/), -[Codemagic](/code-push/ci/codemagic/), or the -[generic CI guide](/code-push/ci/generic/). +[GitHub Actions](/code-push/ci/github/), [Codemagic](/code-push/ci/codemagic/), +or the [generic CI guide](/code-push/ci/generic/). ## Expiration @@ -55,7 +54,8 @@ API keys support two permission levels: - **Full access** — the key has the same permissions as your account. Available on all plans. - **Release & Patch only** — the key can create releases and patches, but cannot - manage apps, organizations, members, or billing. Available on Pro and Business plans. + manage apps, organizations, members, or billing. Available on Pro and Business + plans. ## Revoking an API Key From 904ad8da96d4d7e83889833c359b3baf5891315f Mon Sep 17 00:00:00 2001 From: Mac Date: Tue, 24 Mar 2026 09:38:58 -0600 Subject: [PATCH 3/6] Update src/content/docs/code-push/ci/_authentication.mdx Co-authored-by: Tom Arra --- src/content/docs/code-push/ci/_authentication.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/code-push/ci/_authentication.mdx b/src/content/docs/code-push/ci/_authentication.mdx index 4d6bfa23..b6347bae 100644 --- a/src/content/docs/code-push/ci/_authentication.mdx +++ b/src/content/docs/code-push/ci/_authentication.mdx @@ -1,5 +1,5 @@ Most Shorebird functionality, like creating releases and patches, requires -authentication. To authenticate in CI, create an API key from the +authentication. To authenticate in your CI, create an API key from the [Shorebird Console](https://console.shorebird.dev): 1. Go to **Account → API Keys**. From 8068298aca024554460b266091d436c92f3802fc Mon Sep 17 00:00:00 2001 From: Mac Date: Tue, 24 Mar 2026 09:41:09 -0600 Subject: [PATCH 4/6] Update src/content/docs/code-push/ci/_authentication.mdx Co-authored-by: Eric Seidel --- src/content/docs/code-push/ci/_authentication.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/code-push/ci/_authentication.mdx b/src/content/docs/code-push/ci/_authentication.mdx index b6347bae..62a04109 100644 --- a/src/content/docs/code-push/ci/_authentication.mdx +++ b/src/content/docs/code-push/ci/_authentication.mdx @@ -29,7 +29,7 @@ apps, organizations, members, or billing. :::tip[Migrating from `shorebird login:ci`] The `shorebird login:ci` command is deprecated. Existing tokens generated by -`login:ci` will continue to work until March 2027, but new tokens should be +`login:ci` will continue to work until September 2026, but new tokens should be created from the console. The `SHOREBIRD_TOKEN` environment variable name has not changed, so your CI workflow files need only a new key value. From ac27979878ab0c7b18f3f3e01d06cbd2ccab5bfe Mon Sep 17 00:00:00 2001 From: Mac Carrithers Date: Tue, 24 Mar 2026 10:25:41 -0600 Subject: [PATCH 5/6] Remove three consecutive callouts --- src/content/docs/code-push/ci/_authentication.mdx | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/src/content/docs/code-push/ci/_authentication.mdx b/src/content/docs/code-push/ci/_authentication.mdx index 62a04109..7fb9e669 100644 --- a/src/content/docs/code-push/ci/_authentication.mdx +++ b/src/content/docs/code-push/ci/_authentication.mdx @@ -18,13 +18,8 @@ publicly. Store it in your CI platform's secrets manager. ::: -:::note - -On Pro and Business plans, you can restrict an API key to **Release & Patch -only** permissions — the key can create releases and patches but cannot manage -apps, organizations, members, or billing. - -::: +See [API Keys](/account/api-keys/#permissions) for details on permission levels +and other key management options. :::tip[Migrating from `shorebird login:ci`] From b5e2186796d4ec935601c61daa5cd1a7311e383f Mon Sep 17 00:00:00 2001 From: Mac Carrithers Date: Tue, 24 Mar 2026 10:45:30 -0600 Subject: [PATCH 6/6] Update deprecation timeline --- src/content/docs/account/api-keys.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/account/api-keys.mdx b/src/content/docs/account/api-keys.mdx index 06c222fb..b510955d 100644 --- a/src/content/docs/account/api-keys.mdx +++ b/src/content/docs/account/api-keys.mdx @@ -66,8 +66,8 @@ action cannot be undone. ## Migrating from `shorebird login:ci` The `shorebird login:ci` command is deprecated. Existing tokens generated by -`login:ci` will continue to work until March 2027, but we recommend replacing -them with API keys created from the console. +`login:ci` will continue to work until September 2026, but we recommend +replacing them with API keys created from the console. To migrate: