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 Identity & Access Management > 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 Identity & Access Management > 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 Identity & Access Management > Service Accounts and click on the "Create API Token" button.
  2. You can either use an existing service account or create a new one specifically for the agent. If you create a new service account, make sure to assign it the appropriate role bindings as described in Step 2.
  3. Enter a descriptive name for the token
  4. Click Create Token
  5. Copy the token immediately — it is only shown once

Create Token modal

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​