> ## Documentation Index
> Fetch the complete documentation index at: https://docs.backline.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS CodeArtifact Integration

> Connect to your AWS CodeArtifact to access private NPM, PyPI, Go, and NuGet packages

## Overview

The AWS CodeArtifact integration allows Backline to access packages from your AWS CodeArtifact repositories. This is required for Backline to build and analyze projects that depend on private packages hosted in AWS CodeArtifact.

## What You Can Do

With the AWS CodeArtifact integration, Backline can:

* Resolve NPM packages from your AWS CodeArtifact
* Resolve Python packages from your AWS CodeArtifact
* Resolve Go modules from your AWS CodeArtifact
* Resolve NuGet packages for .NET / C# projects from your AWS CodeArtifact
* Build and analyze projects that depend on packages in your CodeArtifact registry
* Provide remediation for vulnerabilities in projects using CodeArtifact as their package source

## Supported Package Types

| Package Type | CodeArtifact Format | Example URL                                                                                         |
| ------------ | ------------------- | --------------------------------------------------------------------------------------------------- |
| **NPM**      | npm                 | `https://my-domain-111122223333.d.codeartifact.us-east-1.amazonaws.com/npm/my-repo/`                |
| **PyPI**     | pypi                | `https://my-domain-111122223333.d.codeartifact.us-east-1.amazonaws.com/pypi/my-repo/simple/`        |
| **Go**       | go                  | `https://my-domain-111122223333.d.codeartifact.us-east-1.amazonaws.com/go/my-repo/`                 |
| **NuGet**    | nuget               | `https://my-domain-111122223333.d.codeartifact.us-east-1.amazonaws.com/nuget/my-repo/v3/index.json` |

<Note>
  NuGet repository URLs must point to the **v3** feed and end with `/v3/index.json`.
</Note>

## Prerequisites

Before connecting AWS CodeArtifact, ensure you have:

* An AWS account with CodeArtifact domains and repositories
* Permissions to deploy CloudFormation stacks (requires IAM role creation)
* Your 12-digit AWS Account ID
* Repository URLs for the package types you want to use

## Connecting AWS CodeArtifact

<Steps>
  <Step title="Go to Integration Hub">
    Navigate to Integrations from the main menu.
  </Step>

  <Step title="Select AWS CodeArtifact">
    Find and click on the AWS CodeArtifact integration card.
  </Step>

  <Step title="Deploy CloudFormation Stack">
    Click the CloudFormation link in Backline or use the direct link below to deploy the integration role in your AWS account:

    [Deploy CloudFormation Stack](https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/create/review?templateURL=https://backline-integration-templates.s3.amazonaws.com/backline-codeartifact-integration-role.yaml\&stackName=BacklineCodeArtifactIntegration)

    Enter a unique **External ID** when prompted. This value secures the cross-account trust relationship.
  </Step>

  <Step title="Get Stack Outputs">
    After the stack completes, go to the **Outputs** tab and copy the **Role ARN** and **External ID**.
  </Step>

  <Step title="Enter Integration Details">
    In Backline, enter:

    * **Account ID**: Your 12-digit AWS account ID
    * **External ID**: The value you provided during stack creation
    * **Role ARN**: The ARN from the CloudFormation outputs
  </Step>

  <Step title="Configure Repository URLs">
    Enter the URLs for the package types you want to use:

    * **NPM Repository URL**: Your CodeArtifact npm repository URL
      * Example: `https://my-domain-111122223333.d.codeartifact.us-east-1.amazonaws.com/npm/my-repo/`

    * **PyPI Repository URL**: Your CodeArtifact PyPI repository URL (must end with `/simple/`)
      * Example: `https://my-domain-111122223333.d.codeartifact.us-east-1.amazonaws.com/pypi/my-repo/simple/`

    * **Go Repository URL**: Your CodeArtifact Go repository URL
      * Example: `https://my-domain-111122223333.d.codeartifact.us-east-1.amazonaws.com/go/my-repo/`

    * **NuGet Repository URL**: Your CodeArtifact NuGet v3 repository URL (must end with `/v3/index.json`)
      * Example: `https://my-domain-111122223333.d.codeartifact.us-east-1.amazonaws.com/nuget/my-repo/v3/index.json`

    <Note>
      You only need to configure URLs for the package types your repositories use. At least one URL is required.
    </Note>
  </Step>

  <Step title="Test Connection">
    Click **Test Connection** to verify the role can be assumed.
  </Step>

  <Step title="Save">
    Click **Save** to complete the integration.
  </Step>
</Steps>

## Finding Your Repository URLs

To find the correct URL for each repository in AWS CodeArtifact:

<Steps>
  <Step title="Navigate to CodeArtifact">
    In the AWS Console, go to **CodeArtifact** → **Repositories**.
  </Step>

  <Step title="Select Your Repository">
    Click on the repository you want to use.
  </Step>

  <Step title="Get Repository URL">
    Click **View connection instructions** and select your package manager (npm, pip, Go, or NuGet).

    The dialog will show the repository endpoint URL.

    For PyPI repositories, ensure the URL ends with `/simple/`.
  </Step>
</Steps>

## Alternative: Manual Role Creation

If you cannot use CloudFormation or prefer to create IAM resources manually, follow these steps:

<Tip>
  We recommend using the CloudFormation template for easier setup and maintenance. Use manual creation only if CloudFormation is not an option in your environment.
</Tip>

<Steps>
  <Step title="Create the IAM Role">
    In the AWS IAM Console, create a new role named `BacklineCodeArtifactIntegrationRole` with the following trust policy:

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "AWS": "arn:aws:iam::198331734661:role/BacklineIntegrationReadOnlyCodeArtifact"
          },
          "Action": "sts:AssumeRole",
          "Condition": {
            "StringEquals": {
              "sts:ExternalId": "<YOUR_EXTERNAL_ID>"
            }
          }
        }
      ]
    }
    ```

    Replace `<YOUR_EXTERNAL_ID>` with a unique, secure string of at least 8 characters. Save this value—you'll need it when configuring Backline.
  </Step>

  <Step title="Attach the Permissions Policy">
    Create and attach an inline policy named `CustomerCodeArtifactReadPolicy` with the following permissions:

    ```json theme={null}
    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "codeartifact:GetAuthorizationToken",
          "Resource": "arn:aws:codeartifact:*:<YOUR_ACCOUNT_ID>:domain/*"
        },
        {
          "Effect": "Allow",
          "Action": [
            "codeartifact:GetRepositoryEndpoint",
            "codeartifact:ReadFromRepository"
          ],
          "Resource": "arn:aws:codeartifact:*:<YOUR_ACCOUNT_ID>:repository/*/*"
        },
        {
          "Effect": "Allow",
          "Action": "sts:GetServiceBearerToken",
          "Resource": "*",
          "Condition": {
            "StringEquals": {
              "sts:AWSServiceName": "codeartifact.amazonaws.com"
            }
          }
        }
      ]
    }
    ```

    Replace `<YOUR_ACCOUNT_ID>` with your 12-digit AWS account ID.
  </Step>

  <Step title="Copy the Role ARN">
    After creating the role, copy its ARN from the role summary page. It will look like:

    `arn:aws:iam::<YOUR_ACCOUNT_ID>:role/BacklineCodeArtifactIntegrationRole`
  </Step>

  <Step title="Complete Integration in Backline">
    Return to the [Enter Integration Details](#enter-integration-details) step above and enter your Account ID, External ID, and Role ARN.
  </Step>
</Steps>

## Required IAM Permissions

The CloudFormation template creates a role with the following permissions:

```
codeartifact:GetAuthorizationToken    (Resource: arn:aws:codeartifact:*:${AccountId}:domain/*)
codeartifact:GetRepositoryEndpoint    (Resource: arn:aws:codeartifact:*:${AccountId}:repository/*/*)
codeartifact:ReadFromRepository       (Resource: arn:aws:codeartifact:*:${AccountId}:repository/*/*)
sts:GetServiceBearerToken             (Resource: * with condition sts:AWSServiceName=codeartifact.amazonaws.com)
```

<Tip>
  The CloudFormation template follows the principle of least privilege, granting read-only access scoped to CodeArtifact resources in your account.
</Tip>

## Security Model

Backline uses secure cross-account role assumption to access your CodeArtifact:

1. Backline assumes its own integration role
2. That role then assumes the `BacklineCodeArtifactIntegrationRole` in your account
3. The External ID prevents unauthorized access (confused deputy protection)

Backline never stores long-term AWS credentials. All access uses temporary STS tokens that automatically expire.

## After Connection

Once AWS CodeArtifact is configured, Backline will:

1. Use the provided role to authenticate with your CodeArtifact domains
2. Access packages from your CodeArtifact repositories during dependency analysis
3. Provide remediation for projects that depend on packages in your CodeArtifact registry

## Managing the Integration

### Updating Configuration

To update the integration settings:

1. Open the **Integration Hub**
2. Click on the **AWS CodeArtifact** integration
3. Update the Account ID, External ID, Role ARN, or repository URLs as needed
4. Test and save

### Adding Package Types

To add support for additional package types:

1. Open the AWS CodeArtifact integration settings
2. Add the repository URL for the new package type
3. Save the changes

## Troubleshooting

### Authentication Failed

If Backline cannot authenticate with AWS:

* Verify the Role ARN is correct
* Check that the External ID matches what was used during role creation
* Ensure the CloudFormation stack completed successfully

### Permission Denied

If Backline cannot access repositories:

* Verify the IAM role has the required CodeArtifact permissions
* Check that the `sts:GetServiceBearerToken` permission is included
* Ensure the role trust policy references the correct Backline principal

### Package Resolution Issues

If specific packages cannot be resolved:

* Verify the package exists in your CodeArtifact repository
* Check that the repository URL is correct and matches the package type
* For PyPI repositories, ensure the URL ends with `/simple/`

### PyPI URL Format

PyPI repository URLs must end with `/simple/` for pip compatibility:

* Correct: `https://my-domain-111122223333.d.codeartifact.us-east-1.amazonaws.com/pypi/my-repo/simple/`
* Incorrect: `https://my-domain-111122223333.d.codeartifact.us-east-1.amazonaws.com/pypi/my-repo/`