setup-gcx

name

setup-gcx

description

Sets up gcx: installation, context creation, authentication, and connection to a Grafana instance. Covers Grafana Cloud and on-premise deployments, environment variable overrides for CI/CD, default datasource configuration, and troubleshooting connection and authentication problems. Use when installing gcx, connecting gcx to a Grafana instance for the first time, or when gcx commands fail with auth or connectivity errors (401, 403, connection refused, missing namespace).

Setup gcx

Three configuration paths: Grafana Cloud (Path A), on-premise (Path B), and environment variables for CI/CD (Path C). For the complete config reference (all config set paths, TLS options, namespace resolution rules, multi-context patterns), see configuration.md.

Step 0: Install gcx

First, check whether gcx is already installed:

gcx --version

If the command is not found, build it from source. Requires git and a recent Go toolchain:

tmp=$(mktemp -d) && git clone --depth 1 https://github.com/grafana/gcx.git "$tmp" && (cd "$tmp" && go install ./cmd/gcx) && rm -rf "$tmp"

After installing, verify the binary is on PATH:

gcx --version

Configuration Model

gcx uses a context-based configuration model inspired by kubectl's kubeconfig. One or more layered YAML files (with the user file at ~/.config/gcx/config.yaml by default) store named stacks (Grafana destination, credentials, provider config), named cloud entries (Grafana Cloud platform credentials and endpoints), and thin contexts that reference a stack and optional Cloud entry. One context is selected at a time; all commands operate against it unless overridden. Single-source legacy configs are migrated automatically after a safe preflight. When several layers participate, gcx converts them in memory and asks the user to migrate each layer explicitly rather than partially persisting the result.

Use gcx config view to inspect the current configuration at any time. Use gcx config check to validate that the active context is correct and can reach the server.

---

Path A: Grafana Cloud

Use this path when connecting to a Grafana Cloud instance (URLs ending in .grafana.net).

Step 1: Create a stack and context

gcx config set stacks.cloud.grafana.server https://myorg.grafana.net
gcx config set contexts.cloud.stack cloud

Replace cloud with any name you prefer (e.g., prod, myorg-cloud). Replace the server URL with your Grafana Cloud URL. The first command creates the stack entry; the second creates a context pointing at it.

Step 2: Authenticate

Option A-1: Browser OAuth (recommended for Grafana Cloud)

gcx login cloud --server https://myorg.grafana.net --oauth

Opens a browser for the user to approve. This works non-interactively and in agent mode — the agent issues the command, the browser opens, and the user approves. No token to create or paste. gcx login also sets the context as current and verifies connectivity, so Steps 1, 3, and 4 are handled for you; skip them when using this option.

Option A-2: Service account token

gcx config set stacks.cloud.grafana.token glsa_XXXXXXXXXXXXXXXX

Obtain a service account token from Administration > Service accounts in your Grafana Cloud instance. The token must have sufficient permissions for the operations you intend to run (Viewer for read-only, Editor or Admin for write operations).

The grafana.token field takes precedence over grafana.user/grafana.password when both are present.

Grafana Cloud product APIs use a separate credential. A Cloud Access Policy token has the widest compatibility and can be supplied during unified login:

gcx login cloud --server https://myorg.grafana.net \
  --token glsa_XXXXXXXXXXXXXXXX --cloud-token glc_XXXXXXXXXXXXXXXX --yes

For interactive use, the Cloud step of gcx login can keep an existing CAP or unexpired OAuth credential, accept a CAP, run the experimental direct Cloud OAuth flow, or skip. gcx cloud login --context cloud runs direct Cloud OAuth separately. OAuth retains expiry, granted scopes, and its coherent OAuth/API endpoint pair, but not every Cloud product command supports it yet; use a CAP for full compatibility.

Step 3: Switch to the context

gcx config use-context cloud

Step 4: Verify the connection

gcx config check

A successful check prints the active context name and server URL without errors. For Grafana Cloud, the stack ID (namespace) is auto-discovered from the server's /bootdata endpoint -- you do not need to set grafana.stack-id manually unless auto-discovery fails.

If the discovered stack ID conflicts with a manually configured grafana.stack-id, gcx raises a validation error - see Namespace resolution issues.

---

Path B: On-Premise Grafana

Use this path when connecting to a self-hosted Grafana instance.

Step 1: Create a stack and context

gcx config set stacks.onprem.grafana.server https://grafana.example.com
gcx config set contexts.onprem.stack onprem

Replace onprem with a name that identifies this environment (e.g., production, staging, local).

Step 2: Set authentication

Option B-1: API token (recommended)

gcx config set stacks.onprem.grafana.token glsa_XXXXXXXXXXXXXXXX

Option B-2: Username and password

gcx config set stacks.onprem.grafana.user admin
gcx config set stacks.onprem.grafana.password mysecretpassword

Use Option B-1 when service accounts are available. Use Option B-2 for development or when service accounts are not configured.

Step 3: Set the org ID

On-premise Grafana uses an org ID to identify the namespace for API calls. Set it to the numeric ID of the organization (default org is 1):

gcx config set stacks.onprem.grafana.org-id 1

To find the org ID: in Grafana, go to Administration > Organizations and note the numeric ID shown in the URL when you select an org.

Step 4: Switch to the context

gcx config use-context onprem

Step 5: Verify the connection

gcx config check

TLS options (optional): If your Grafana instance uses a self-signed certificate or a custom CA, configure TLS:

# Skip TLS verification (development only -- do not use in production)
gcx config set stacks.onprem.grafana.tls.insecure-skip-verify true

# Supply a custom CA certificate (base64-encoded PEM)
gcx config set stacks.onprem.grafana.tls.ca-data <base64-encoded-pem>

---

Path C: Environment Variables (CI/CD)

Use this path when gcx runs in a CI/CD pipeline or another automated environment where writing a config file is impractical. Environment variables override the selected context's fields at runtime without modifying the config file.

Environment Variable	Runtime override	Description
GRAFANA_SERVER	selected stack's grafana.server	Server URL
GRAFANA_TOKEN	selected stack's grafana.token	API token (takes precedence over user/pass)
GRAFANA_USER	selected stack's grafana.user	Username for basic auth
GRAFANA_PASSWORD	selected stack's grafana.password	Password for basic auth
GRAFANA_ORG_ID	selected stack's grafana.org-id	Org ID (on-premise namespace)
GRAFANA_STACK_ID	selected stack's grafana.stack-id	Stack ID (Grafana Cloud namespace)
GRAFANA_PROXY_ENDPOINT	selected stack's OAuth proxy	Assistant proxy endpoint
GRAFANA_TLS_CERT_FILE	selected stack's TLS cert file	mTLS client certificate
GRAFANA_TLS_KEY_FILE	selected stack's TLS key file	mTLS client key
GRAFANA_TLS_CA_FILE	selected stack's TLS CA file	Custom CA bundle
GRAFANA_CLOUD_TOKEN	ephemeral Cloud entry	Cloud Access Policy token
GRAFANA_CLOUD_API_URL	ephemeral Cloud entry	Cloud API endpoint
GRAFANA_CLOUD_OAUTH_URL	ephemeral Cloud entry	Cloud OAuth endpoint
GRAFANA_CLOUD_STACK	selected stack's slug	Cloud stack slug

When an endpoint override changes a credential destination, supply the corresponding credential variable in the same invocation. Login commands turn one supplied endpoint into a coherent OAuth/API pair; set both endpoint variables when a custom environment deliberately uses distinct origins.

An auto-discovered repository .gcx.yaml cannot attach runtime or freshly prompted credentials, or external mTLS client key files, to destinations and transport settings supplied by that file. Review it and select it explicitly with --config .gcx.yaml or GCX_CONFIG=.gcx.yaml before login or direct provider authentication. Provider endpoint environment overrides also require their matching runtime credential and still do not authorize repository TLS or proxy settings.

Example: GitHub Actions

- name: Run gcx
  env:
    GRAFANA_SERVER: ${{ secrets.GRAFANA_SERVER }}
    GRAFANA_TOKEN: ${{ secrets.GRAFANA_TOKEN }}
    GRAFANA_ORG_ID: "1"
  run: gcx resources get dashboards -o json

Environment variables apply to the selected context only and do not modify the config file on disk. --context selection happens before these overrides, and write-back paths never serialize the env-mutated runtime object.

Config file location

To supply a config file path explicitly:

gcx --config /path/to/config.yaml resources get dashboards
# or
export GCX_CONFIG=/path/to/config.yaml

For the full config file search order, see configuration.md.

---

Default Datasource Configuration

To avoid passing -d <uid> on every query command, configure default datasource UIDs for the active context.

Find your datasource UIDs

gcx datasources list -o json

Locate the uid field for each datasource. Example output:

{
  "datasources": [
    { "uid": "prometheus-uid-abc123", "name": "Prometheus", "type": "prometheus" },
    { "uid": "loki-uid-def456",       "name": "Loki",       "type": "loki"       }
  ]
}

Set defaults

# Set the default Prometheus datasource
gcx config set contexts.cloud.datasources.prometheus prometheus-uid-abc123

# Set the default Loki datasource
gcx config set contexts.cloud.datasources.loki loki-uid-def456

Replace cloud with your context name and the UID values with those from the output above. After setting these, query commands that support a -d flag will use the configured defaults automatically.

---

Multi-Context Management

To work with multiple Grafana environments, repeat Path A or B once per environment with a distinct context name, then:

# Switch between contexts
gcx config use-context staging

# Use a context for a single command without switching
gcx --context staging resources get dashboards

# List all contexts (secrets redacted; add --raw to reveal)
gcx config view

For create/update/remove patterns, see configuration.md.

---

Troubleshooting

config check fails

Run gcx config check to diagnose configuration problems. It prints the active context and performs a live health check against the server.

If it reports a missing server or empty context:

# Verify current context is set
gcx config view

# Ensure the current-context field is not empty
gcx config set current-context <your-context-name>

If it reports a missing namespace (stack ID or org ID):

• Grafana Cloud: either let auto-discovery resolve it (no manual action needed for .grafana.net URLs) or set grafana.stack-id explicitly.
• On-premise: set grafana.org-id to the numeric org ID (usually 1).

401 Unauthorized

The token or credentials are invalid or expired.

# Replace with a fresh token
gcx config set stacks.<name>.grafana.token glsa_NEW_TOKEN

Verify the token has not expired and has the correct permissions for the operations you intend to run.

403 Forbidden

The token is valid but lacks permissions for the requested operation. In Grafana, navigate to Administration > Service accounts, select the service account, and assign an appropriate role (Viewer, Editor, or Admin).

Connection refused or timeout

The server URL is unreachable.

1. Confirm the URL is correct:

   gcx config view
   

2. Test connectivity from the machine running gcx:

   curl -I https://grafana.example.com/api/health
   

3. Check for proxy requirements or VPN. If the instance uses a self-signed certificate:

   gcx config set stacks.<name>.grafana.tls.insecure-skip-verify true
   

   Use insecure-skip-verify only for development; supply a CA certificate in production environments instead.

Namespace resolution issues

gcx resolves the API namespace (Kubernetes namespace for all calls) in this order:

1. Attempt auto-discovery via /bootdata HTTP call to the server
2. If discovery fails and org-id is non-zero: use org-<id> namespace
3. If discovery fails and org-id is zero: use configured stack-id

If you see a "mismatched stack ID" error, a configured grafana.stack-id differs from the auto-discovered value. Resolve by unsetting the manual value:

gcx config unset stacks.<name>.grafana.stack-id

If you see a "missing namespace" error and auto-discovery is failing (e.g., the server does not expose /bootdata), set the namespace manually:

# On-premise
gcx config set stacks.<name>.grafana.org-id 1

# Grafana Cloud (if auto-discovery is unavailable)
gcx config set stacks.<name>.grafana.stack-id 12345

---

Complete Example: Grafana Cloud with a Service Account Token

# 1. Set server and token on a stack, and bind a context to it
gcx config set stacks.mycloud.grafana.server https://myorg.grafana.net
gcx config set stacks.mycloud.grafana.token glsa_XXXXXXXXXXXXXXXX
gcx config set contexts.mycloud.stack mycloud

# 2. Activate the context
gcx config use-context mycloud

# 3. Verify
gcx config check

# 4. Set default datasources (after listing available ones)
gcx datasources list -o json
gcx config set contexts.mycloud.datasources.prometheus <prometheus-uid>
gcx config set contexts.mycloud.datasources.loki <loki-uid>

# 5. Test a resource listing
gcx resources get dashboards -o json

---

Reference

For all config set paths, TLS fields, environment variables, namespace resolution rules, and multi-context patterns, see configuration.md.