Skip to main content
Personal access tokens (PATs) authenticate programmatic access to Ona via the CLI or SDK.

​
Create a token

  1. Go to Personal access tokens
  2. Click “New Token”
  3. Enter a description and select expiration (30, 60, or 90 days)
  4. Click “Create” and copy the token immediately - you won’t see it again

​
Use a token

gitpod login --token <your-token>
Or set the environment variable: 
export GITPOD_TOKEN=<your-token>
gitpod login

​
Permissions

Tokens have the same permissions as your user account. They cannot be scoped to specific actions or resources.

​
Security

  • Treat tokens like passwords - don’t share or store insecurely
  • Use the shortest expiration that meets your needs
  • Revoke unused tokens
  • Actions are logged in audit logs with the token ID

​
Examples

​
CI/CD integration

Authenticate your CI/CD pipeline to create and manage environments automatically. 
name: Gitpod Integration
on: [push]
jobs:
  create-environment:
    runs-on: ubuntu-latest
    steps:
      - name: Create Environment
        env:
          GITPOD_TOKEN: ${{ secrets.GITPOD_PAT }}
          GITPOD_CLASS: some-class-id
        run: |
          gitpod login --token $GITPOD_TOKEN
          gitpod environment create --class-id $GITPOD_CLASS https://github.com/your-repo

​
Scripted environment management

Manage environments programmatically for bulk operations or scheduled maintenance. 
import subprocess
import json

GITPOD_PAT = "your_personal_access_token"

def run_gitpod_command(*args):
    result = subprocess.run(
        ["gitpod"] + list(args),
        capture_output=True,
        text=True,
        check=True
    )
    return result.stdout.strip()

# Login using PAT
run_gitpod_command("login", "--token", GITPOD_PAT)

# List all environments
environments_json = run_gitpod_command("environment", "list", "-o", "json")
environments = json.loads(environments_json)

# Stop all running environments
for env in environments:
    if env['status']['phase'] == 'ENVIRONMENT_PHASE_RUNNING':
        print(f"Stopping environment {env['id']}")
        run_gitpod_command("environment", "stop", env['id'])

print("All running environments have been stopped.")

​
Third-party tool integration

Integrate with external tools that need to create environments on your behalf. 
import subprocess
import json

GITPOD_PAT = "your_gitpod_pat"

def create_environment_for_review(repo_url):
    # Login using PAT
    subprocess.run(["gitpod", "login", "--token", GITPOD_PAT], check=True)

    # Create an environment
    result = subprocess.run(
        ["gitpod", "environment", "create", repo_url, "--dont-wait"],
        capture_output=True,
        text=True,
        check=True
    )
    env_id = result.stdout.strip()

    # Get the environment details
    result = subprocess.run(
        ["gitpod", "environment", "get", env_id, "-o", "json"],
        capture_output=True,
        text=True,
        check=True
    )
    return json.loads(result.stdout)