Skip to content

Getting started

By the end of this you will have detected Application Default Credentials once and used them to build a service client that you own.

go get gitlab.com/phpboyscout/go/gcpclient

1. Build a source

package main

import (
    "context"
    "fmt"

    "gitlab.com/phpboyscout/go/gcpclient"
)

func main() {
    src := gcpclient.Ambient(
        gcpclient.WithScopes("https://www.googleapis.com/auth/cloud-platform"),
    )

    fmt.Println("source built; nothing detected yet")

    opts, err := src.GCPClientOptions(context.Background())
    if err != nil {
        panic(err)
    }

    fmt.Println("client options:", len(opts))
}

Ambient returns immediately. Detection happens on the first GCPClientOptions call.

2. Forget the scopes

    src := gcpclient.Ambient()          // no scopes
    _, err := src.GCPClientOptions(ctx)
    fmt.Println(err)

no OAuth scopes configured; pass WithScopes with the scope the service needs

It refuses rather than choosing. There is no scope that is safe by default — cloud-platform over-grants, and anything narrower under-grants in a way that surfaces only when a later call needs more.

3. Build a client and own it

The options are yours to hand to whichever service client you need:

    opts, err := src.GCPClientOptions(ctx)
    if err != nil {
        return err
    }

    client, err := secretmanager.NewClient(ctx, opts...)
    if err != nil {
        return err
    }
    defer client.Close()          // yours to close — you built it

The slice you receive is a copy. Every Google service constructor invites appending to what it is given, so a shared source hands out a fresh slice each time rather than one every caller can disturb.

4. Use an explicit credentials file instead

When you are not using ADC — an emulator, a service-account key, a credential resolved elsewhere — inject the options:

    src, err := gcpclient.FromOptions([]option.ClientOption{
        option.WithCredentialsFile("/etc/creds.json"),
    })

Nothing is detected on that rung, so it has no build policy and returns any error immediately.

Next