Working with continuous modernization

Source management

Use atx ct source commands to connect repositories. Supported providers: GitHub, GitLab, Bitbucket, local.

GitHub organizations

Token: personal access token (classic) with repo scope. Read-only for analysis, full repo for remediation.

atx ct source add --name name --provider github --org org --token pat

GitLab groups and users

Token: personal access token with api scope.

atx ct source add --name name --provider gitlab --org group-or-user --token pat
# Self-hosted:
atx ct source add --name name --provider gitlab --org group-or-user --token pat --url https://gitlab.example.com

Bitbucket workspaces and projects

Bitbucket Cloud — scopes: read:repository:bitbucket, write:repository:bitbucket, read:pullrequest:bitbucket, write:pullrequest:bitbucket. Also needs --email and --username.

atx ct source add --name name --provider bitbucket --org workspace --token api-token --email email --username username

Bitbucket Data Center:

atx ct source add --name name --provider bitbucket --org project-key --token http-access-token --url https://bitbucket.example.com

Local repositories

atx ct source add --name name --provider local --path parent-directory

Managing sources

atx ct source list
atx ct source remove --name name

Repository discovery and management

atx ct discovery scan --source name
atx ct discovery status --source name
atx ct discovery scan --source name --path new-directory

After discovery:

atx ct repository list
atx ct repository list --source name
atx ct repository list --labels "team:frontend,priority:high"
atx ct repository update --source name --repo "source::repo" --labels "team:frontend,priority:high"
atx ct repository update --source name --labels "migration:wave-1"

Running analysis

The --type flag specifies the kind of analysis to run:

atx ct analysis run --type type --source name [--repo source::repo] [--wait]
atx ct analysis get --id id --json
atx ct analysis list --json
atx ct analysis list --status pending|running|complete|cancelled|failed --json
atx ct analysis list --type type --json
atx ct analysis cancel --id id
atx ct analysis delete --id id [--cascade-findings]

If you omit --repo, the command analyzes every repository under --source. To scope the run to specific repositories, pass --repo (comma-separated) — each a fully-qualified source::repo, or a bare name used with --source.

Custom analysis

atx ct analysis run --type custom --transformation-name name --source source --repo source::repo --wait

Configuration with -g flag: key-value, JSON, or file path.

List TDs: atx custom def list

Managing findings

atx ct findings list --json
atx ct findings list --repo source::repo --source name --severity high|medium|low --type analysis-type --status open|dismissed|obsolete --analysis-id id --fix-transform transform-name --json

Finding statuses

atx ct findings update --id id --status dismissed --reason "reason"
atx ct findings update --id id --status open
atx ct findings batch-update --ids id1,id2 --status dismissed --reason "reason"
atx ct findings get --id id
atx ct findings delete --id id

Finding obsolescence

Re-analysis marks resolved findings as obsolete. Cannot be re-opened. Retained for audit.

Creating remediations

Three modes: findings-based, TD override, direct TD.

atx ct remediation create --ids id1,id2 --name "name"
atx ct remediation create --ids id1,id2 --transformation-name TD
atx ct remediation create --transformation-name TD --repo source::repo

Output by provider: GitHub PR, GitLab MR, Bitbucket PR, Local branch.

Local execution with --local flag.

atx ct remediation create --transformation-name TD --repo source::repo -g "additionalPlanContext=Upgrade to Node.js 22"
atx ct remediation list
atx ct remediation status --id id
atx ct remediation retry --id id
atx ct remediation cancel --id id
atx ct remediation delete --id id

Remote execution

By default, analyses and remediations run on your local machine. For larger portfolios, you can offload work to remote infrastructure. You can run on AWS Transform-managed infrastructure with nothing to provision (analyses only), or on infrastructure you provision and manage in your AWS account—a persistent Amazon EC2 instance or AWS Batch (Fargate) jobs. The atx ct remote commands provision, run, monitor, and tear down customer-managed infrastructure. Regardless of where execution happens, you create all resources in your AWS account and your source code stays under your control.

With the atx ct remote analysis and remediation commands, you choose which repositories to process using --sources and --repos (both comma-separated). --sources selects every repository in the named sources. --repos selects specific repositories, each written as source::repo. If you provide both, the command processes the union of the two sets: every repository in the named sources, plus the named repositories. To scope a run to specific repositories, pass only --repos.

Running on AWS Transform-managed infrastructure (no provisioning)

To run an analysis remotely without provisioning anything, use --mode aws-managed. The submission goes to AWS Transform, which runs the analysis on AWS Transform-managed infrastructure. There is no stack to provision, no networking to configure, and no credentials to store in AWS Secrets Manager. The submission is the run. Choose the AWS Region the workload runs in with --region.

# Run an analysis on AWS Transform-managed infrastructure
atx ct remote analysis --type type --mode aws-managed --sources name [--repos repo1,repo2] [--region region]

# Poll the submission (there is no remote status command in this mode)
atx ct analysis get --id id --json

This mode runs analyses only. It does not support remediation, the custom analysis type, or local sources. Because there is no stack, the --stack-name, --tags, --existing-instance, and --batch-name options don't apply. A single submission covers up to 100 repositories. To cover larger scopes, split them across multiple submissions with --repos. Unlike Amazon EC2 and Batch runs, you monitor progress with atx ct analysis get rather than atx ct remote status.

Networking

Remote compute must run in private subnets. Discover existing networking or create a new VPC before you provision:

# List VPCs, private subnets, and security groups in the current account and Region
atx ct remote network discover
atx ct remote network discover --vpc vpc-id --json

# Create a new VPC with private subnets, a NAT gateway, and a security group
atx ct remote network create --cidr 10.1.0.0/16 --ack

--cidr is optional and defaults to 10.1.0.0/16.

Whether you bring your own network or use network create, it must meet these requirements:

Sizing subnets and concurrency

Before you provision AWS Batch infrastructure for a large repository fleet, size your private subnets for the number of jobs that run in parallel. A subnet that is too small is the most common cause of failed jobs in a large run.

Each AWS Batch job runs as one Fargate task, which needs one elastic network interface and therefore one private IPv4 address. Public IP address assignment is disabled, so a private address is required — a job cannot start without one. AWS Batch does not queue a job it cannot place; it fails the job.

Checking free addresses before you provision

Provisioning does not check subnet capacity for you. Check it yourself with --json, which reports availableIpCount for each subnet. The default table output does not include this value. Compare the smallest count against the concurrency limit for the analysis type you plan to run.

atx ct remote network discover --vpc vpc-id --json

Concurrency limits for each analysis type

AWS Transform limits how many remote jobs run at the same time in an AWS account and Region. The limit depends on the analysis type. These limits are shared across all users in the account and across both compute modes, and they cap the number of addresses a run can consume. To request a change, contact AWS Support.

Minimum subnet size

Amazon VPC reserves five addresses in every subnet, so the usable count is five fewer than the subnet size — a /28 has 11 usable addresses and a /24 has 251. For details, see Subnet CIDR blocks in the Amazon VPC User Guide.

The addresses each subnet needs are the peak concurrent jobs, plus one or more for each interface endpoint in that subnet, plus any other network interfaces that share the subnet. Peak concurrent jobs is the smaller of the number of repositories in the submission and the concurrency limit for the analysis type. Because the limit caps the total, a 1,000-repository fleet needs no more addresses than a 128-repository one.

The minimums above include headroom for interface endpoints and for the addresses AWS reserves. Size up if other workloads share the subnet. A /25 is not enough for 128 concurrent jobs: it provides 128 addresses but only 123 usable ones.

We recommend dedicating subnets to remote execution. AWS Transform admits jobs down to the last free address and cannot account for other workloads that claim addresses in the same subnet.

Running large fleets

A single submission covers up to 100 repositories. Submissions above that limit are rejected before any job starts, so a 1,000-repository fleet needs at least 10 submissions. Split them with --repos, and list the repositories in a source with atx ct repository list --source name --json.

Splitting a fleet does not reduce the addresses you need. Submissions that run at the same time draw from the same subnets, up to the concurrency limit for the analysis type.

There is no option that limits how many repositories are scanned at once. The CLI submits every job in a submission, and AWS Transform releases jobs up to the concurrency limit for the analysis type and holds the rest. To pace a large fleet, size the subnets for that limit and submit in groups of 100 repositories or fewer.

Choosing Amazon EC2 for constrained networks

Amazon EC2 uses one private IP address in total, in the first subnet you pass, no matter how many workers the instance runs. If free addresses are scarce, Amazon EC2 avoids the problem entirely.

The tradeoff is concurrency: --workers accepts 1–5, so an Amazon EC2 instance runs at most 5 repositories in parallel. For fleets that need more, use AWS Batch. For security analysis the account limit is also 5, so AWS Batch offers no additional concurrency for that type.

Size --workers, --instance-type, and --volume-size when you provision. Instance memory must be at least 2 GB for each worker plus 4 GB for the operating system. atx ct remote update keeps these values; changing them requires tearing down and provisioning again, which replaces the instance and deletes its volume.

Provisioning infrastructure

Deploy the Amazon EC2 or AWS Batch stack. Omit --execute to preview the template or changeset; add --execute to apply.

Provisioning creates the compute stack for the mode you choose, plus dispatcher and scheduler stacks:

By default, Amazon EC2 stacks are named atx-runner and AWS Batch stacks are named AtxInfrastructureStack. To run more than one stack of the same mode, give each a distinct name when you provision: use --stack-name (Amazon EC2 only; the name must start with atx-runner) or --suffix to append a suffix to all resource names. For update, detect, and remote analyses or remediations, pass --stack-name to target a custom-named stack. If you omit it, they use the default name (atx-runner for Amazon EC2, AtxInfrastructureStack for AWS Batch). teardown always requires --stack-name. On Amazon EC2, --workers sets the number of parallel worker containers (1-5, default 5) and sizes the instance.

# Preview, then deploy an EC2 stack
atx ct remote provision --mode ec2 --vpc vpc-id --subnets subnet-a,subnet-b
atx ct remote provision --mode ec2 --vpc vpc-id --subnets subnet-a,subnet-b --execute --ack

# Deploy a Batch stack
atx ct remote provision --mode batch --vpc vpc-id --subnets subnet-a,subnet-b --securityGroup sg-id --execute --ack

# Update to the latest template (--stack-name optional; defaults to the standard stack name)
atx ct remote update --mode ec2|batch [--stack-name stack-name] --execute --ack

# Tear down (--stack-name required)
atx ct remote teardown --mode ec2|batch --stack-name stack-name --execute --ack

Container image

When you run remote analyses and remediations, they execute inside a container image. By default, when you provision a remote environment, it uses the public AWS Transform image, public.ecr.aws/d9h8z6l7/aws-transform:latest. AWS Batch sets it as the job definition image. Amazon EC2 uses it as the runner image.

To run a different image—for example, a private Amazon ECR image that bundles additional languages or tools—pass --image-uri when you provision:

# Batch: provision with a custom image
atx ct remote provision --mode batch --vpc vpc-id --subnets subnet-a,subnet-b --securityGroup sg-id --image-uri account-id.dkr.ecr.region.amazonaws.com/repo:tag --execute --ack

# EC2: provision with a custom image
atx ct remote provision --mode ec2 --vpc vpc-id --subnets subnet-a,subnet-b --image-uri account-id.dkr.ecr.region.amazonaws.com/repo:tag --execute --ack

Storing source credentials

Remote containers clone your repositories using tokens stored in AWS Secrets Manager. Register a token for each SCM source before running remote analysis or remediation:

atx ct remote credentials --source name --token token
atx ct remote credentials --source name --remove

Running remotely

Remote analysis runs one container for each repository; remote remediation runs one container for each finding. Use --sources, --repos, and --labels to control fan-out, and --stack-name or --tags to select which provisioned stack to use.

# Run analysis across a source on Batch
atx ct remote analysis --type type --mode batch --sources name [--repos repo1,repo2] [--labels "team:frontend"]

# Run remediation for specific findings on EC2
atx ct remote remediation --mode ec2 --ids id1,id2
atx ct remote remediation --mode ec2 --sources name --min-severity high

Monitoring and managing runs

# Check whether infrastructure is deployed
atx ct remote detect --mode ec2|batch

# Track a submission (Batch by batch ID, EC2 by group ID)
atx ct remote status --batch batch-id --stack-name name
atx ct remote status --group ec2-group-id --wait

# Resume a partially-failed Batch run (re-submits only incomplete repos).
# On resume, --batch-name takes the existing batch ID reported by "remote status --batch".
atx ct remote analysis --type type --mode batch --sources name --resume-incomplete --batch-name batch-id

# Cancel a running submission
atx ct remote cancel --mode batch --batch batch-id --stack-name name
atx ct remote cancel --mode ec2 --group ec2-group-id

Scheduling recurring analysis

Use atx ct schedule to run analyses automatically on a recurring cadence. You can schedule analyses but not remediations. Job options mirror atx ct remote analysis. Schedules run remotely, in one of two ways:

The --recurrence value accepts daily, weekly:DAY (for example, weekly:MONDAY), or monthly:N where N is a day from 1 to 28. Schedules on AWS Transform-managed infrastructure run in UTC.

# AWS Transform-managed schedule (no infrastructure; requires an execution role)
atx ct schedule create --name name --mode aws-managed --execution-role role-arn --recurrence daily --type type --sources name [--repos repo1,repo2]

# Customer-managed schedule (EventBridge Scheduler dispatching to your EC2 or Batch stack)
atx ct schedule create --name name --mode ec2|batch --recurrence weekly:MONDAY --type type --sources name [--repos repo1,repo2]

# Manage schedules of either type by their schedule ID (from schedule list)
atx ct schedule list
atx ct schedule get schedule-id
atx ct schedule disable schedule-id
atx ct schedule enable schedule-id
atx ct schedule delete schedule-id

To view the analyses a schedule has run, use atx ct analysis list --schedule-id schedule-id, which returns the schedule's fired runs, newest first.

To remove the scheduler role and schedule group used by customer-managed schedules, run atx ct schedule teardown --execute.

Execution role for AWS Transform-managed schedules

A schedule created with --mode aws-managed requires an --execution-role ARN that AWS Transform assumes each time the schedule runs. Configure the role as follows:

The following inline policy grants the AWS Secrets Manager access that scheduled runs need to retrieve source clone credentials. Attach it to the execution role alongside the AWSTransformCustomFullAccess managed policy, replacing region and account-id with the AWS Region and account the schedule runs in.

{
  "Version": "2012-10-17", 
  "Statement": [
    {
      "Sid": "AtxSourceCredentials",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret"
      ],
      "Resource": "arn:aws:secretsmanager:region:account-id:secret:atx/*"
    }
  ]
}

Tagging and access control

You can apply tags (comma-separated key=value pairs) to sources, analyses, and remediations with the --tags option. Tags are also supported on remote infrastructure, stored credentials, and networking resources. With tags, you can organize resources. Combined with IAM tag conditions, tags implement attribute-based access control (ABAC) so that teams access only the resources that carry their tags.

atx ct source add --name name --provider github --org org --token pat --tags team=platform,env=prod
atx ct analysis run --type type --source name --tags team=platform
atx ct remediation create --ids id1,id2 --tags team=platform

By default, resources are tagged with the tags you define in ~/.aws/atx/settings.json. Add the tags you want applied to every resource under applyTags, and they become your default tags.

{
  "applyTags": [
    { "team": "alpha" }
  ]
}

AWS Transform web application

Use the AWS Transform web application to create and run analyses, review findings, create remediations, and track generated pull requests across your code sources.

Before you use the web application, your organization must enable your user identity to access AWS Transform. For more information about setting up AWS Transform, see Setting up AWS Transform.

Sign in

To access the AWS Transform web application, complete the following steps.

Infrastructure modes

When you create an analysis, choose one of the following infrastructure modes:

To use customer-owned infrastructure, open the Settings tab. Use the AWS CloudFormation quick-create links to deploy the following stacks in order:

For CLI-based provisioning and networking configuration, see Remote execution.

Getting started workflow

Chat with AWS Transform directly from the web application to ask questions about your analyses, findings, or remediations.