Skip to main content

Connect Amazon Q Developer to LinearB

Connect Amazon Q Developer to LinearB through AWS to collect adoption and accepted-lines data from Amazon Q usage reports.

Steven Silverstone
Updated by Steven Silverstone

Before You Begin

Verify that you have:

  • Access to AI Tools settings in LinearB.
  • AWS administrative access to IAM, S3, and IAM Identity Center.
  • An active Amazon Q Developer environment.
  • Amazon Q Developer user activity reports enabled.
  • The S3 bucket and path where Amazon Q Developer reports are exported.
  • The IAM Identity Center instance used by Amazon Q Developer.

Prepare Amazon Q Developer Reporting in AWS

Before connecting Amazon Q Developer to LinearB, enable user activity reports and configure an S3 bucket as the report destination.

  1. Open the Amazon Q Developer administration environment.
  2. Enable user activity reports.
  3. Configure the S3 bucket and prefix where Amazon Q Developer reports will be exported.
  4. Optionally enable prompt logging.
  5. Confirm that Amazon Q Developer usage reports are being generated in the configured S3 location.
Keep the S3 report location available. You will enter its S3 URI in LinearB during the connection process.

Create the IAM Role for LinearB

Create a cross-account IAM role that LinearB can use to access the Amazon Q Developer reports and resolve users.

  1. In the AWS console, go to IAM → Roles.
  2. Click Create role.
  3. For Trusted entity type, select AWS account.
  4. Select Another AWS account.
  5. Enter the LinearB AWS account ID: 
    841492816024
  6. Continue without attaching permissions to the role.
  7. Enter a role name that starts with LinearB.
  8. Create the role.
Important: The IAM role name must start with LinearB. LinearB can only assume roles that use this prefix.

Do not manually configure the final permissions or External ID yet. LinearB generates the required policies after you enter the AWS settings in the connection wizard.

Start the Connection in LinearB

  1. Go to Settings → Company Settings → AI Tools → Integrations.
  2. Click Add New.
  3. Select AWS.
  4. Click Continue.
  5. Select Amazon Q Developer.
  6. Click Continue.
Unfinished setup: If LinearB finds an unfinished Amazon Q Developer setup, the Main Settings fields are prefilled. Continuing resumes that setup instead of creating another one.

Enter the AWS Main Settings

Enter the five AWS values requested by the LinearB connection wizard.

IAM Role ARN

Use the ARN of the IAM role you created for LinearB.

  1. In AWS, go to IAM → Roles.
  2. Open the LinearB role you created.
  3. Find the ARN in the Summary at the top of the page.
  4. Copy the ARN and paste it into IAM Role ARN in LinearB.

Usage Data S3 Path

Use the S3 location where Amazon Q Developer exports its usage reports.

  1. In AWS, go to S3 → Buckets.
  2. Open the reporting bucket.
  3. Open the folder or prefix containing the Amazon Q Developer reports.
  4. Use Copy S3 URI.
  5. Paste the URI into Usage Data S3 Path in LinearB. The value should look similar to: 
    s3://bucket-name/report-prefix

Identity Store ID

Use the Identity Store ID for the IAM Identity Center whose users sign in to Amazon Q Developer.

  1. In the AWS console, switch to the region where your IAM Identity Center is configured.
  2. Go to IAM Identity Center → Settings.
  3. Open Identity source.
  4. Copy the Identity store ID.
  5. Paste it into Identity Store ID in LinearB.
The Identity Store ID typically starts with d-. In multi-account AWS organizations, IAM Identity Center may be configured in a different AWS account from the IAM role or S3 bucket.

S3 Bucket Region

In S3 → Buckets, locate the reporting bucket and copy its AWS region into S3 Bucket Region.

Identity Center Region

Enter the AWS region where the IAM Identity Center used by Amazon Q Developer is enabled.

Regions can differ: The Identity Center region does not need to match the S3 bucket region.

After entering all five values, click Continue. LinearB generates the permissions and trust policies required for the IAM role.

Apply the Generated AWS Policies

LinearB generates two policies. Apply each policy to the IAM role in the location specified below.

Apply the Permissions Policy

The Permissions Policy grants read-only access to the required Amazon Q Developer reporting and Identity Store resources.

  1. In LinearB, expand Permissions Policy.
  2. Copy the generated policy.
  3. In AWS, go to IAM → Roles.
  4. Open the LinearB role you created.
  5. Open the Permissions tab.
  6. Select Add permissions → Create inline policy.
  7. Select JSON.
  8. Replace the existing JSON with the policy copied from LinearB.
  9. Save the inline policy.

Apply the Trust Policy

The Trust Policy allows the LinearB AWS account to assume the role and adds the External ID generated for this integration.

  1. In LinearB, expand Trust Policy.
  2. Copy the generated policy.
  3. In AWS, open the same IAM role.
  4. Open the Trust relationships tab.
  5. Click Edit trust policy.
  6. Replace the existing trust policy with the policy copied from LinearB.
  7. Save the trust policy.
Important: Apply the generated policy exactly as shown. The External ID in AWS must match the current External ID generated by LinearB or LinearB cannot assume the role.

Connect Amazon Q Developer

  1. Return to the Amazon Q Developer connection wizard in LinearB.
  2. Complete the remaining wizard steps and click Add Integration.
  3. LinearB validates the IAM role, S3 access, Identity Store access, and configured regions.

When validation succeeds, AWS — Amazon Q Developer appears in the Connected list.

Duplicate integrations: Only one active Amazon Q Developer integration can be connected at a time. Disconnect an existing active integration before connecting another one.

Verify the Connection

  1. Open Settings → Company Settings → AI Tools → Integrations.
  2. Select Connected.
  3. Select AWS — Amazon Q Developer.
  4. Confirm that the integration status is Connected.
  5. Confirm that the displayed AWS settings match the reporting environment.
  6. Allow time for Amazon Q reports to be generated and processed.
  7. Open AI Analytics and confirm that Amazon Q data appears.

Edit the Amazon Q Developer Integration

Use Edit mode to update the AWS resources and regions used by the integration.

The following fields can be edited:

  • IAM Role ARN
  • Usage Data S3 Path
  • Identity Store ID
  • S3 Bucket Region
  • Identity Center Region
  1. Open Settings → Company Settings → AI Tools → Integrations.
  2. Select Connected.
  3. Select AWS — Amazon Q Developer.
  4. Under Main Settings, click Edit.
  5. Update the required AWS settings.
  6. Click Save changes to apply the update or Cancel to discard it.
Permissions: Anyone who has access to AI Tools settings can edit the integration. The user must also be able to update the corresponding IAM role in AWS.
Important: Saving any change regenerates the External ID. The existing IAM trust policy stops matching immediately. Copy the newly generated Trust Policy and apply it to the IAM role in AWS.

Apply the updated Trust Policy

  1. After saving the edit, expand Trust Policy.
  2. Copy the newly generated policy.
  3. Open the integration’s IAM role in AWS.
  4. Replace the existing Trust Policy with the newly generated policy.
  5. Save the role in AWS.
  6. Return to LinearB and verify the integration.

What happens to historical data?

Editing the integration does not delete previously collected Amazon Q metrics.

  • Saving an edit triggers a new collection.
  • LinearB recollects up to 90 days of recent Amazon Q data.
  • Recollected records are updated in place and are not counted twice.
  • Data older than the recollection window remains unchanged.
Collection interruption: LinearB cannot assume the IAM role until the updated Trust Policy is applied. A collection gap accumulates while the old External ID remains in AWS.

Disconnect or Reconnect

Disconnecting Amazon Q Developer stops new report collection and moves the integration to the Disconnected list. Previously collected data is preserved.

Disconnect the integration

  1. Open Settings → Company Settings → AI Tools → Integrations.
  2. Select Connected.
  3. Select AWS — Amazon Q Developer.
  4. Click Disconnect.
  5. Confirm the action.

Reconnect the integration

  1. Open Settings → Company Settings → AI Tools → Integrations.
  2. Select Disconnected.
  3. Select AWS — Amazon Q Developer.
  4. Click Reconnect.
  5. Review the saved AWS configuration.
  6. Complete validation to restore the integration.

LinearB validates the saved IAM role and AWS resources before restoring the integration.

Duplicate integrations: If another active Amazon Q Developer integration exists, disconnect it before reconnecting the previous one.

Troubleshooting

Invalid IAM Role ARN

Verify that the complete ARN was copied from AWS. It should use this format: 

arn:aws:iam::<account-id>:role/<role-name>

Invalid S3 URI

Verify that the path uses a valid S3 URI and contains the correct bucket and prefix: 

s3://<bucket-name>/<report-prefix>/

Could Not Assume the IAM Role

  • Confirm that the Trust Policy allows the LinearB AWS account as a principal.
  • Verify that sts:ExternalId exactly matches the current External ID shown in LinearB.
  • Confirm that the IAM Role ARN is correct.
  • Verify that the Trust Policy was applied to the intended role.
  • If the integration was edited, confirm that the newly generated Trust Policy was applied in AWS.

IAM Role Not Found

Confirm that the role exists in the AWS account identified by the ARN and that the complete ARN was entered in LinearB.

Temporary AWS Error

AWS STS throttling or temporary service unavailability can prevent validation. Wait a few minutes and try again.

S3 Bucket Not Found

  • Confirm that the bucket name is correct.
  • Verify that the configured S3 region matches the bucket’s actual region.
  • Confirm that the bucket exists in the expected AWS account.

No Permission to List the S3 Bucket

Confirm that the IAM role permits s3:ListBucket for the configured bucket and prefix.

No Permission to Read S3 Objects

Confirm that the IAM role permits s3:GetObject for the Amazon Q report objects under the configured prefix.

Incorrect S3 Region

Update the configured S3 region so that it matches the bucket’s actual region.

IAM Identity Center Not Found

  • Verify the Identity Store ID.
  • Confirm the IAM Identity Center home region.
  • Remember that the Identity Center and S3 bucket can use different regions.

Access Denied to Identity Store

Confirm that the IAM role has the required read-only Identity Store permissions, including access to retrieve and describe users.

No Amazon Q Data Appears

  • Confirm that Amazon Q Developer user activity reports are enabled.
  • Verify that reports exist under the configured S3 path.
  • Confirm that the S3 path matches the Amazon Q report location.
  • Allow time for the daily report and LinearB processing cycle.
  • Verify that users can be resolved through the configured Identity Store.
  • Confirm that the integration appears under Connected without an error indicator.

Known Limitations

  • Data availability depends on the Amazon Q Developer reports present in the configured S3 path.
  • Amazon Q reporting is updated daily, not in real time.
  • Available metrics depend on the data returned through the AWS reports.
  • Model, token, and estimated-consumption data is not currently available.
  • Saving any edit regenerates the External ID and requires an updated IAM Trust Policy.

How did we do?

Choose a GitHub Copilot connection

Connect Claude Code using OpenTelemetry

Contact