> ## Documentation Index
> Fetch the complete documentation index at: https://superflag.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CI/CD Integration

> Use the Superflag CLI in continuous integration and deployment pipelines

# CI/CD Integration

Use the Superflag CLI in your continuous integration and deployment workflows to automate flag management.

<Info>
  This guide covers production CI/CD usage. For AI-assisted development, see the [Claude Code skill](/cli/claude-code).
</Info>

## Authentication in CI

For CI/CD environments, you'll need to obtain a CLI token and store it as a secret.

### Step 1: Get CLI Token

On your local machine:

```bash theme={null}
superflag login
cat ~/.superflag/credentials.json
```

Copy the `token` value (starts with `cli_`).

### Step 2: Store as Secret

Store the token in your CI platform's secrets:

<Tabs>
  <Tab title="GitHub Actions">
    1. Go to repository Settings → Secrets and variables → Actions
    2. Create new secret: `SUPERFLAG_TOKEN`
    3. Paste your token
  </Tab>

  <Tab title="GitLab CI">
    1. Go to Settings → CI/CD → Variables
    2. Add variable: `SUPERFLAG_TOKEN`
    3. Mark as "Masked" and "Protected"
  </Tab>

  <Tab title="CircleCI">
    1. Go to Project Settings → Environment Variables
    2. Add variable: `SUPERFLAG_TOKEN`
  </Tab>

  <Tab title="Travis CI">
    1. Go to repository Settings → Environment Variables
    2. Add variable: `SUPERFLAG_TOKEN`
    3. Keep "Display value in build log" OFF
  </Tab>
</Tabs>

### Step 3: Set Token in CI

Create the credentials file in your CI workflow:

```bash theme={null}
mkdir -p ~/.superflag
echo "{\"token\":\"$SUPERFLAG_TOKEN\"}" > ~/.superflag/credentials.json
```

## CI/CD Examples

### GitHub Actions

```yaml .github/workflows/deploy.yml theme={null}
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Superflag CLI
        run: |
          npm install -g @superflag-sh/cli
          mkdir -p ~/.superflag
          echo "{\"token\":\"${{ secrets.SUPERFLAG_TOKEN }}\"}" > ~/.superflag/credentials.json

      - name: Update production flags
        run: |
          superflag use my-app production
          superflag set deployment-version ${{ github.sha }}
          superflag set deployed-at $(date -u +%Y-%m-%dT%H:%M:%SZ)

      - name: Deploy
        run: npm run deploy
```

### GitLab CI

```yaml .gitlab-ci.yml theme={null}
deploy:
  stage: deploy
  only:
    - main
  before_script:
    - npm install -g @superflag-sh/cli
    - mkdir -p ~/.superflag
    - echo "{\"token\":\"$SUPERFLAG_TOKEN\"}" > ~/.superflag/credentials.json
  script:
    - superflag use my-app production
    - superflag set deployment-version $CI_COMMIT_SHA
    - superflag set deployed-at $(date -u +%Y-%m-%dT%H:%M:%SZ)
    - npm run deploy
```

### CircleCI

```yaml .circleci/config.yml theme={null}
version: 2.1

jobs:
  deploy:
    docker:
      - image: cimg/node:18.0
    steps:
      - checkout

      - run:
          name: Install Superflag CLI
          command: |
            npm install -g @superflag-sh/cli
            mkdir -p ~/.superflag
            echo "{\"token\":\"$SUPERFLAG_TOKEN\"}" > ~/.superflag/credentials.json

      - run:
          name: Update flags
          command: |
            superflag use my-app production
            superflag set deployment-version $CIRCLE_SHA1

      - run:
          name: Deploy
          command: npm run deploy

workflows:
  version: 2
  deploy:
    jobs:
      - deploy:
          filters:
            branches:
              only: main
```

## Common Patterns

### Feature Flag Deployment

Enable a feature flag after successful deployment:

```yaml theme={null}
- name: Deploy application
  run: npm run deploy

- name: Enable new feature
  run: |
    superflag use my-app production
    superflag set new-feature true
```

### Environment-Specific Configuration

```bash theme={null}
# Staging deployment
if [ "$CI_BRANCH" = "develop" ]; then
  superflag use my-app staging
  superflag set api-url https://api-staging.example.com
fi

# Production deployment
if [ "$CI_BRANCH" = "main" ]; then
  superflag use my-app production
  superflag set api-url https://api.example.com
fi
```

### Bulk Flag Updates

```yaml theme={null}
- name: Update all flags for release
  run: |
    cat > flags.json <<EOF
    {
      "new-ui": true,
      "old-ui": false,
      "api-version": "v2",
      "maintenance-mode": false
    }
    EOF
    superflag use my-app production
    superflag flags bulk-set --file flags.json
```

### Rollback on Failure

```yaml theme={null}
- name: Deploy
  id: deploy
  run: npm run deploy

- name: Rollback flags on failure
  if: failure()
  run: |
    superflag use my-app production
    superflag set new-feature false
    superflag set api-version v1
```

## Best Practices

### 1. Use Context

Set context once per job to avoid repeating `--app` and `--env`:

```bash theme={null}
# ✅ Good
superflag use my-app production
superflag set feature-a true
superflag set feature-b false

# ❌ Verbose
superflag flags set --app my-app --env production --key feature-a --value true
superflag flags set --app my-app --env production --key feature-b --value false
```

### 2. Fail Fast

Check authentication before running other steps:

```yaml theme={null}
- name: Verify Superflag auth
  run: superflag whoami
```

### 3. Log Flag Changes

Keep an audit trail of flag changes:

```yaml theme={null}
- name: Update flags
  run: |
    echo "Updating flags at $(date)"
    superflag set new-feature true | tee -a flag-changes.log
```

### 4. Use Exit Codes

Check command success in scripts:

```bash theme={null}
if superflag set new-feature true; then
  echo "Flag updated successfully"
else
  echo "Failed to update flag"
  exit 1
fi
```

### 5. Separate Deploy and Feature Enable

Deploy code first, enable features second:

```yaml theme={null}
- name: Deploy code
  run: npm run deploy

# Wait for deployment to stabilize
- name: Wait
  run: sleep 30

- name: Enable feature
  run: superflag set new-feature true
```

## Security

### Protect Your Token

* Never commit `~/.superflag/credentials.json` to version control
* Store tokens in CI secrets, not in code
* Use masked/protected variables in your CI platform
* Rotate tokens if compromised

### Audit Trail

All flag changes made via CLI are logged in your Superflag dashboard under "Activity".

## Troubleshooting

### Authentication Fails

```bash theme={null}
Error: Not authenticated
```

**Solution:** Verify your CI secret is set correctly:

```bash theme={null}
# Debug (remove after testing)
echo "Token length: ${#SUPERFLAG_TOKEN}"
```

### Context Not Persisting

The `use` command saves context to `~/.superflag/context.json`. Ensure this persists between steps:

```yaml theme={null}
# Cache context between steps
- name: Set context
  run: superflag use my-app production

- name: Use context
  run: superflag get feature-flag
```

### Commands Timeout

Network issues in CI can cause timeouts. Add retry logic:

```bash theme={null}
for i in {1..3}; do
  superflag set feature-flag true && break
  echo "Retry $i/3"
  sleep 5
done
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Commands Reference" icon="terminal" href="/cli/commands">
    Complete command documentation
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Use the HTTP API directly
  </Card>
</CardGroup>