# Onboarding

This guide walks you through the credentials and environment setup required for local development and testing with Airbyte's connector tooling.

## Setting up GSM (Google Secret Manager) access

Connector integration test credentials are stored in [Google Secret Manager (GSM)](https://cloud.google.com/secret-manager) under the `dataline-integration-testing` GCP project. Many Airbyte tools access these secrets, including:

- **[Airbyte CDK CLI](https://github.com/airbytehq/airbyte-python-cdk)**: `uvx airbyte-cdk[dev] secrets list` and `uvx airbyte-cdk[dev] secrets fetch`
- **[PyAirbyte](https://github.com/airbytehq/PyAirbyte)**: `GoogleGSMSecretManager` reads credentials automatically
- **CI workflows**: Many GitHub Actions workflows across Airbyte repos use these secrets at the org or repo level

There are two ways to authenticate. Choose the one that fits your workflow.

### Option A: Application Default Credentials (recommended for local development)

As of [CDK v7.9.0](https://github.com/airbytehq/airbyte-python-cdk/pull/898), the Airbyte CDK CLI falls back to Application Default Credentials (ADC) when `GCP_GSM_CREDENTIALS` is not set. This means you can authenticate with your own Google account instead of creating a service account.

1. Install the [gcloud CLI](https://cloud.google.com/sdk/docs/install) if you don't have it (`brew install gcloud-cli` on macOS).
2. Log in and set up ADC:

   ```bash
   gcloud auth login
   gcloud auth application-default login
   ```

3. Verify it works:

   ```bash
   uvx airbyte-cdk[dev] secrets list --connector-name source-github
   ```

This approach requires that your Google account has access to the `dataline-integration-testing` GCP project.

### Option B: Service account with `GCP_GSM_CREDENTIALS`

CI workflows use the `GCP_GSM_CREDENTIALS` environment variable with a service account. If you need this approach locally, follow these steps.

#### Step 1: Create a GCP service account

1. Go to the [Service Accounts page for the `dataline-integration-testing` project](https://console.cloud.google.com/iam-admin/serviceaccounts/create?project=dataline-integration-testing).
2. In **Service account details**, set the name to something identifiable like `{your-name}-testing` and add a description.
3. In **Grant this service account access to project**, assign the **Secret Manager Secret Accessor** role (`roles/secretmanager.secretAccessor`).

#### Step 2: Create a JSON key for the service account

1. Go to the [Service Accounts list for the `dataline-integration-testing` project](https://console.cloud.google.com/iam-admin/serviceaccounts?project=dataline-integration-testing).
2. Find your service account and click on it.
3. Go to the **KEYS** tab.
4. Click **ADD KEY > Create new key** and select **JSON**.
5. Save the downloaded JSON file to a secure location on your machine.

#### Step 3: Set the environment variable

Add the following to your shell profile (`~/.zshrc`, `~/.bashrc`, etc.):

```bash
export GCP_GSM_CREDENTIALS=$(cat /path/to/your-service-account-key.json)
```

Then reload your shell or run `source ~/.zshrc`.

### Verifying your setup

You can verify that credentials are working by listing available secrets for a connector:

```bash
uvx airbyte-cdk[dev] secrets list --connector-name source-github
```

If authentication is configured correctly, you should see a list of secret labels available for that connector.

## Setting your GitHub public email

Several Airbyte tools (including [progressive rollouts](./docs/progressive-rollouts.md#appendix-approval-comment-urls)) verify that approval comments come from an `@airbyte.io` team member by checking the commenter's **public email** on GitHub. This email is required in order to map the individual to their internal Airbyte Cloud Admin User ID GUID when performing sensitive operations, such as [progressive rollouts](./docs/progressive-rollouts.md) and version pinning, which require a user ID to be logged. If your public email isn't set, these approval checks will fail.

To configure it:

1. Go to [GitHub Profile Settings](https://github.com/settings/profile).
2. In the **Public email** dropdown, select your `@airbyte.io` email address.
3. Click **Update profile**.

> Example configuration screenshot:
>
> ![GitHub public email settings](./docs/images/github-public-email-settings.png)

If your `@airbyte.io` email doesn't appear in the dropdown, you first need to add and verify it under [Email settings](https://github.com/settings/emails).

## Related resources

- [Local connector development](https://docs.airbyte.com/platform/connector-development/local-connector-development) - Broader guide covering connector testing and secret management
- [CONTRIBUTING.md](./CONTRIBUTING.md) - Additional credentials and permissions required for this repo's tools
