Headless/CI Authentication

Run gws in CI/CD environments and headless servers

Use this approach to run gws commands in environments without a browser, such as:

• GitHub Actions, GitLab CI, CircleCI
• Docker containers
• SSH sessions on remote servers
• Automated scripts and cron jobs

Overview

The headless authentication flow:

1. Authenticate interactively on a machine with a browser
2. Export the encrypted credentials to a file
3. Transfer the file to your CI/headless environment
4. Set GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE to point to the file
5. Run gws commands — they’ll “just work” with no login prompt

Export Credentials from Interactive Machine

1. Authenticate interactively

   On your local development machine:

   gws auth setup
   # or
   gws auth login
   
2. Export credentials

   Export the decrypted credentials to a file:

   gws auth export --unmasked > credentials.json
   

   The exported file contains your OAuth client secret and refresh token in plaintext. Handle it carefully:

   • Do not commit to version control
   • Use encrypted CI secrets storage
   • Delete after uploading to CI
3. Verify the export

   Check the exported file format:

   cat credentials.json | jq
   

   Expected format:

   {
     "type": "authorized_user",
     "client_id": "123456789.apps.googleusercontent.com",
     "client_secret": "GOCSPX-...",
     "refresh_token": "1//..."
   }
   

Configure CI Environment

Using Environment Variable

Set the path to your credentials file:

export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json
gws drive files list

Using CI Secrets

Most CI platforms support encrypted secrets. Store the credentials file content as a secret:

GitHub Actions

name: Workspace Automation

on: [push]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install gws
        run: npm install -g @googleworkspace/cli
      
      - name: Set up credentials
        run: |
          mkdir -p ~/.config/gws
          echo '${{ secrets.GWS_CREDENTIALS }}' > ~/.config/gws/credentials.json
        
      - name: List Drive files
        env:
          GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE: /home/runner/.config/gws/credentials.json
        run: |
          gws drive files list --params '{"pageSize": 10}'

To set the secret:

1. Go to your repo → Settings → Secrets and variables → Actions
2. Click New repository secret
3. Name: GWS_CREDENTIALS
4. Value: Paste the contents of credentials.json

GitLab CI

workspace-sync:
  image: node:20
  before_script:
    - npm install -g @googleworkspace/cli
    - mkdir -p ~/.config/gws
    - echo "$GWS_CREDENTIALS" > ~/.config/gws/credentials.json
  script:
    - export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=~/.config/gws/credentials.json
    - gws drive files list --params '{"pageSize": 10}'

To set the variable:

1. Go to Settings → CI/CD → Variables
2. Add variable GWS_CREDENTIALS (masked)
3. Paste the contents of credentials.json

CircleCI

version: 2.1

jobs:
  workspace-sync:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Install gws
          command: npm install -g @googleworkspace/cli
      - run:
          name: Set up credentials
          command: |
            mkdir -p ~/.config/gws
            echo "$GWS_CREDENTIALS" > ~/.config/gws/credentials.json
      - run:
          name: List Drive files
          command: |
            export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=~/.config/gws/credentials.json
            gws drive files list --params '{"pageSize": 10}'

workflows:
  main:
    jobs:
      - workspace-sync

To set the environment variable:

1. Go to Project Settings → Environment Variables
2. Add GWS_CREDENTIALS
3. Paste the contents of credentials.json

Docker

FROM node:20-alpine

RUN npm install -g @googleworkspace/cli

# Copy credentials at build time (not recommended for production)
# COPY credentials.json /app/credentials.json

# Better: mount as volume or pass as secret at runtime
ENV GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/app/credentials.json

CMD ["gws", "drive", "files", "list"]

Run with mounted credentials:

docker run -v $(pwd)/credentials.json:/app/credentials.json my-gws-image

Using .env Files

gws automatically loads environment variables from a .env file in the current directory:

# .env
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json

Never commit .env files containing credentials to version control. Add .env to your .gitignore.

Credential Precedence

When running gws commands, credentials are resolved in this order:

Priority	Source	Set via
1	Pre-obtained access token	GOOGLE_WORKSPACE_CLI_TOKEN
2	Credentials file (env var)	GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE
3	Encrypted credentials	~/.config/gws/credentials.enc (from gws auth login)
4	Plaintext credentials	~/.config/gws/credentials.json

Environment variables can also be loaded from a .env file in the working directory.

Using Pre-Obtained Access Tokens

If another tool (e.g., gcloud, Application Default Credentials) already provides access tokens, you can bypass credential files entirely:

export GOOGLE_WORKSPACE_CLI_TOKEN=$(gcloud auth print-access-token)
gws drive files list

Access tokens expire quickly (typically 1 hour). This approach only works for short-lived scripts. For long-running CI jobs, use the refresh token method above.

Security Best Practices

Use CI-native secrets management

• Store credentials in GitHub Secrets, GitLab Variables, or CircleCI Environment Variables
• Never hardcode credentials in workflow files
• Use masked/protected variables when available

Restrict credential scope

• Create credentials with read-only scopes when possible:
  gws auth login --readonly
  gws auth export --unmasked > ci-credentials.json
  
• Use different credentials for different CI jobs

Rotate credentials regularly

• Re-run gws auth login and export new credentials monthly
• Update CI secrets after rotation
• Run gws auth logout on the source machine after export

Audit credential usage

• Monitor OAuth token usage in Google Cloud Console
• Set up alerts for unusual API activity
• Use service accounts for production workloads (see next section)

Debugging

Check which credentials are being used

gws auth status

Look for the credential_source field:

{
  "credential_source": "GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE",
  "plain_credentials": "/path/to/credentials.json",
  "plain_credentials_exists": true
}

Test authentication

# Minimal test
gws drive about get

# Test with verbose output
GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=/path/to/credentials.json \
  gws drive files list --params '{"pageSize": 1}'

Limitations

• Exported credentials are tied to the OAuth client used during gws auth login
• If the original OAuth client is deleted in GCP Console, the credentials will stop working
• Refresh tokens can be revoked by the user at https://myaccount.google.com/permissions

When to Use Service Accounts Instead

Consider using service accounts if:

• You need credentials that never expire
• You’re running automated workflows in a Google Workspace domain with Domain-Wide Delegation
• You want credentials that aren’t tied to a specific user account
• You need to access resources across multiple user accounts

Next Steps

Service Accounts

Use service accounts for server-to-server authentication

Interactive Auth

Return to local development setup