nitrictech · tjholm · Oct 28, 2025 · Oct 28, 2025
diff --git a/docs/cli/access-token.mdx b/docs/cli/access-token.mdx
diff --git a/docs/docs.json b/docs/docs.json
@@ -30,6 +30,8 @@
             "pages": [
               "guides",
               "guides/add-suga",
+              "guides/personal-access-tokens",
+              "guides/cicd-authentication",
               "guides/mcp-integration",
               "guides/build-platform",
               "guides/database-migration",
@@ -55,7 +57,6 @@
           {
             "group": "Commands",
             "pages": [
-              "cli/access-token",
               "cli/build",
               "cli/completion",
               "cli/config",

diff --git a/docs/guides/cicd-authentication.mdx b/docs/guides/cicd-authentication.mdx
@@ -0,0 +1,355 @@
+---
+title: 'CI/CD Authentication'
+description: 'Authenticate Suga CLI in CI/CD pipelines using Personal Access Tokens'
+---
+
+## Overview
+
+To use the Suga CLI in automated CI/CD environments, you need to authenticate without interactive login prompts. Personal Access Tokens provide a secure way to authenticate the CLI in:
+
+- GitHub Actions
+- GitLab CI
+- CircleCI
+- Jenkins
+- BitBucket Pipelines
+- Any CI/CD platform
+
+## Quick Start
+
+Set the `SUGA_ACCESS_TOKEN` environment variable with your Personal Access Token:
+
+```bash
+export SUGA_ACCESS_TOKEN="your-token-here"
+```
+
+Once set, all Suga CLI commands will automatically authenticate using the token.
+
+## Prerequisites
+
+Before setting up CI/CD authentication, you need to:
+
+1. [Create a Personal Access Token](/guides/personal-access-tokens)
+2. Securely store the token in your CI/CD platform's secrets management system
+
+<Note>
+Never commit tokens directly to your repository. Always use your CI/CD platform's encrypted secrets or environment variable features.
+</Note>
+
+## Platform-Specific Setup
+
+<Tabs>
+<Tab title="GitHub Actions">
+
+### GitHub Actions
+
+<Steps>
+  <Step title="Add Token to Repository Secrets">
+    1. Navigate to your GitHub repository
+    2. Go to **Settings** > **Secrets and variables** > **Actions**
+    3. Click **New repository secret**
+    4. Name: `SUGA_ACCESS_TOKEN`
+    5. Value: Your Personal Access Token
+    6. Click **Add secret**
+  </Step>
+
+  <Step title="Use in Workflow">
+
+    ```yaml
+    name: Deploy with Suga
+
+    on:
+      push:
+        branches: [main]
+
+    jobs:
+      deploy:
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v4
+
+          - name: Install Suga CLI
+            run: |
+              curl -sSL https://addsuga.com/install | sh
+              echo "$HOME/.suga/bin" >> $GITHUB_PATH
+
+          - name: Build and Deploy
+            env:
+              SUGA_ACCESS_TOKEN: ${{ secrets.SUGA_ACCESS_TOKEN }}
+            run: |
+              suga build
+              # Additional deployment commands
+    ```
+
+    **Documentation**: [GitHub Actions Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets)
+  </Step>
+</Steps>
+
+</Tab>
+
+<Tab title="GitLab CI">
+
+### GitLab CI
+
+<Steps>
+  <Step title="Add Token to CI/CD Variables">
+    1. Navigate to your GitLab project
+    2. Go to **Settings** > **CI/CD** > **Variables**
+    3. Click **Add variable**
+    4. Key: `SUGA_ACCESS_TOKEN`
+    5. Value: Your Personal Access Token
+    6. Check **Mask variable** and **Protect variable** (recommended)
+    7. Click **Add variable**
+  </Step>
+
+  <Step title="Use in Pipeline">
+
+    ```yaml
+    stages:
+      - build
+      - deploy
+
+    variables:
+      SUGA_VERSION: "latest"
+
+    before_script:
+      - curl -sSL https://addsuga.com/install | sh
+      - export PATH="$HOME/.suga/bin:$PATH"
+
+    build:
+      stage: build
+      script:
+        - suga build
+      only:
+        - main
+
+    deploy:
+      stage: deploy
+      script:
+        - suga build
+        # Additional deployment commands
+      only:
+        - main
+    ```
+
+    **Documentation**: [GitLab CI/CD Variables](https://docs.gitlab.com/ee/ci/variables/)
+  </Step>
+</Steps>
+
+</Tab>
+
+<Tab title="CircleCI">
+
+### CircleCI
+
+<Steps>
+  <Step title="Add Token to Environment Variables">
+    1. Navigate to your CircleCI project
+    2. Click **Project Settings**
+    3. Go to **Environment Variables**
+    4. Click **Add Environment Variable**
+    5. Name: `SUGA_ACCESS_TOKEN`
+    6. Value: Your Personal Access Token
+    7. Click **Add Variable**
+  </Step>
+
+  <Step title="Use in Config">
+
+    ```yaml
+    version: 2.1
+
+    jobs:
+      build-and-deploy:
+        docker:
+          - image: cimg/base:stable
+        steps:
+          - checkout
+
+          - run:
+              name: Install Suga CLI
+              command: |
+                curl -sSL https://addsuga.com/install | sh
+                echo 'export PATH=$HOME/.suga/bin:$PATH' >> $BASH_ENV
+
+          - run:
+              name: Build with Suga
+              command: suga build
+
+          - run:
+              name: Deploy
+              command: |
+                # Additional deployment commands
+
+    workflows:
+      version: 2
+      build-deploy:
+        jobs:
+          - build-and-deploy:
+              filters:
+                branches:
+                  only: main
+    ```
+
+    **Documentation**: [CircleCI Environment Variables](https://circleci.com/docs/env-vars/)
+  </Step>
+</Steps>
+
+</Tab>
+
+<Tab title="Jenkins">
+
+### Jenkins
+
+<Steps>
+  <Step title="Add Token to Jenkins Credentials">
+    1. Navigate to **Manage Jenkins** > **Manage Credentials**
+    2. Select the appropriate domain
+    3. Click **Add Credentials**
+    4. Kind: **Secret text**
+    5. Secret: Your Personal Access Token
+    6. ID: `suga-access-token`
+    7. Description: "Suga Personal Access Token"
+    8. Click **OK**
+  </Step>
+
+  <Step title="Use in Pipeline">
+
+    ```groovy
+    pipeline {
+        agent any
+
+        environment {
+            SUGA_ACCESS_TOKEN = credentials('suga-access-token')
+        }
+
+        stages {
+            stage('Install Suga') {
+                steps {
+                    sh '''
+                        curl -sSL https://addsuga.com/install | sh
+                        export PATH=$HOME/.suga/bin:$PATH
+                    '''
+                }
+            }
+
+            stage('Build') {
+                steps {
+                    sh '''
+                        export PATH=$HOME/.suga/bin:$PATH
+                        suga build
+                    '''
+                }
+            }
+
+            stage('Deploy') {
+                steps {
+                    sh '''
+                        export PATH=$HOME/.suga/bin:$PATH
+                        # Additional deployment commands
+                    '''
+                }
+            }
+        }
+    }
+    ```
+
+    **Documentation**: [Jenkins Credentials](https://www.jenkins.io/doc/book/using/using-credentials/)
+  </Step>
+</Steps>
+
+</Tab>
+</Tabs>
+
+## Using Tokens with Docker
+
+When running Suga CLI in Docker containers, pass the token as an environment variable:
+
+```dockerfile
+FROM ubuntu:22.04
+
+# Install Suga CLI
+RUN curl -sSL https://addsuga.com/install | sh
+
+# Add Suga to PATH
+ENV PATH="$HOME/.suga/bin:${PATH}"
+
+# Token will be provided at runtime
+ENV SUGA_ACCESS_TOKEN=""
+
+WORKDIR /app
+COPY . .
+
+CMD ["suga", "build"]
+```
+
+Run the container:
+
+```bash
+docker run -e SUGA_ACCESS_TOKEN="your-token-here" your-image
+```
+
+## Common CI/CD Workflows
+
+### Basic Build and Deploy
+
+```bash
+# Set token (typically done by CI platform)
+export SUGA_ACCESS_TOKEN="your-token-here"
+
+# Build infrastructure
+suga build
+
+# Deploy or additional commands
+# ...
+```
+
+### Conditional Deployment
+
+```yaml
+# GitLab CI example
+deploy:
+  stage: deploy
+  script:
+    - suga build
+  only:
+    - main
+    - tags
+  except:
+    - schedules
+```
+
+## Using Tokens with Suga API
+
+Personal Access Tokens can also be used directly with the Suga API as Bearer tokens:
+
+```bash
+curl -H "Authorization: Bearer your-token-here" \
+     https://app.addsuga.com/api/teams/{your_team}/platforms
+```
+
+```javascript
+// Node.js example
+const response = await fetch('https://app.addsuga.com/api/teams/{your_team}/platforms', {
+  headers: {
+    'Authorization': `Bearer ${process.env.SUGA_ACCESS_TOKEN}`
+  }
+});
+```
+
+```python
+# Python example
+import os
+import requests
+
+headers = {
+    'Authorization': f'Bearer {os.environ["SUGA_ACCESS_TOKEN"]}'
+}
+
+response = requests.get('https://app.addsuga.com/api/teams/{your_team}/platforms', headers=headers)
+```
+
+## Next Steps
+
+- [Personal Access Tokens Guide](/guides/personal-access-tokens)
+- [Suga CLI Reference](/cli)
+- [Environment Configuration](/cli/config)
+- [Build Command Reference](/cli/build)