Skip to main content

Migrate Debuginfo Uploads to Service Accounts

This guide walks you through migrating your CI/CD debuginfo and source upload pipelines from project tokens to the new IAM system using service accounts with minimal role bindings.

What's Changing​

Previously, debuginfo uploads authenticated using project-scoped JWT tokens. The new IAM system replaces these with:

  • Service accounts — named identities with granular, role-based permissions
  • Service account tokens — API tokens (format: psc_v1_<64-hex-characters>) tied to a service account
  • Role bindings — assignments that grant only the permissions needed

The project to upload to is now specified separately via a projectID gRPC metadata header, rather than being embedded in the token.

Steps​

1. Create a Service Account​

  1. Go to your organization settings
  2. Navigate to IAM > Service Accounts
  3. Click Create Service Account
  4. Enter a descriptive name (e.g., ci-debuginfo-uploader)

Create Service Account modal

2. Create a Role Binding​

  1. Go to IAM > Role Bindings
  2. Click Create Role Binding
  3. Select your new service account as the subject
  4. Select the Debug Info Writer role
  5. Optionally, scope the binding to a specific project

Create Role Binding modal

The Debug Info Writer role grants debuginfo.write, which covers both debuginfo and source uploads.

3. Generate a Token​

  1. Go to IAM > Service Accounts and click on your service account
  2. In the Tokens section, click Create Token
  3. Copy the token immediately — it is only shown once

Token generated successfully

4. Store the Token in Your CI System​

Store the new service account token and project ID as secrets in your CI platform (e.g., GitHub Actions secrets, GitLab CI variables, etc.).

5. Update Your Upload Commands​

Replace the old token with the new service account token and add the projectID header. The two key flags are:

  • Token: --bearer-token
  • Project ID: --grpc-headers=projectID=<your-project-id>

For example:

parca-debuginfo upload \
  --store-address=grpc.polarsignals.com:443 \
  --bearer-token=$POLARSIGNALS_TOKEN \
  --grpc-headers=projectID=$POLARSIGNALS_PROJECT_ID \
  /path/to/your/binary

Find your project ID in your project settings in the Polar Signals Cloud UI.

6. Verify and Revoke​

Run your CI pipeline and verify the upload succeeds. Then revoke the old project token to complete the migration.

See Also​