Connect your code

A connection is your workspace’s link to one place your code lives: a GitHub organization or account, or an AWS account in one region. Once a workspace has a connection, 3mote can list the repositories behind it, so you can choose which ones each project works on (see Link repositories to a project).

Connecting doesn’t copy your code: 3mote keeps the names of the repositories it can see, and that’s all. Only when an agent works on a repository does a copy exist, in a working folder on the agent’s workstation (see Let an agent open pull requests).

Only workspace owners and administrators can add and manage connections. They do it under Settings → Integrations, a tab other roles don’t see.

A workspace can have several connections, for example two GitHub organizations and an AWS account. How many your plan allows is covered in Plan limits below.

Connect GitHub

1. Open Settings → Integrations and click Add connection.
2. Choose GitHub and click Continue to GitHub.
3. On GitHub, install the 3mote app on your account or organization, and choose which repositories it can see. You can pick specific repositories or all of them.
4. GitHub sends you back to 3mote, which finishes the connection and shows Connected with the number of repositories it found.

To connect a GitHub organization you need to be an owner of that organization. If you aren’t, GitHub sends a request to an owner. Once they approve it, come back to 3mote and choose Connect GitHub again. If you try to connect an organization you don’t own, 3mote tells you that only an owner can connect it.

A GitHub account or organization can be connected to only one 3mote workspace at a time. If it’s already connected elsewhere, disconnect it there first.

What 3mote can do on the repositories you choose. Read code and branches, push its own 3mote/ branches, open pull requests, and delete a 3mote/ branch it pushed itself, for example once its pull request is merged. It can’t delete any other branch, change GitHub Actions workflows, repository settings or members, and it never merges.

To see an agent use a connection end to end, read Let an agent open pull requests.

Recommended: protect your default branch. On GitHub, add a ruleset (or a branch protection rule) to your default branch that requires a pull request before merging. Then nothing, including an agent, can change it without a review by your people. Note that GitHub enforces rulesets on private repositories only on paid GitHub plans; on public repositories they work on every plan.

Recommended: limit what CI can reach. Opening a pull request usually starts your repository’s own checks, and a workflow that runs on pull_request runs on the agent’s changes with that workflow’s secrets and token. Set the default workflow permissions to read-only, and keep sensitive secrets in an environment that requires approval. More in Let an agent open pull requests.

Change which repositories 3mote can see with Manage on GitHub in the connection’s detail panel, then click Refresh repositories back in 3mote.

Connect AWS CodeCommit

CodeCommit is set up with a role in your own AWS account. 3mote never holds an AWS key of yours: it can reach your repositories only through that role, and only while the role exists.

1. Open Settings → Integrations, click Add connection and choose AWS CodeCommit.
2. Account. Enter your 12-digit AWS account ID and the Region your repositories are in. A Connection name is optional. A region holds one set of repositories, so to use a second region, add a second connection.
3. Create role. Click Open AWS CloudFormation. It opens a page in your AWS console with everything filled in. Sign in to that account if asked, tick the box saying CloudFormation might create IAM resources, and click Create stack. When the status reads CREATE_COMPLETE, open the Outputs tab and copy the value next to RoleArn.
4. Paste ARN. Paste the role ARN into 3mote and click Check connection.
5. Check. 3mote tries the role and lists your repositories. You’ll see Connected with the number it found.

Prefer to create the role by hand? Under Advanced: copy the policy instead you can copy the trust policy, the permissions policy and the external ID, or view the CloudFormation template.

Limit it to specific repositories. Before you open CloudFormation, expand Limit to specific repositories (optional) and enter repository names separated by commas. The link then creates a role that can work on only those, and 3mote saves the same names so its check looks at just those repositories. If you limit the role to specific repositories any other way, list them in the wizard too, so 3mote checks only those. Leave it empty to allow every repository in that region.

What the role allows

You can read every line of this in the CloudFormation template before you create it, and it lives in your account, so you control it.

The role lets 3mote:

• read your repositories and branches;
• push its own work branches, whose names start with 3mote/ (for example 3mote/VW-12-voice-orders). 3mote/ is a branch prefix, not a repository name, so this works in any repository;
• delete 3mote/ branches, which 3mote does only for a branch its agent pushed itself and nobody has pushed to since;
• open pull requests.

The role can never:

• merge or approve a pull request;
• push to or delete any other branch, including your main branch;
• delete a repository or change a repository’s settings.

You own the role. To cut off 3mote’s access at any time, delete the CloudFormation stack in AWS and the access ends at once. Every action shows up in your AWS CloudTrail, labelled with the agent that made it.

If the check fails, 3mote says why. The usual causes are a stack that is still being created (wait for CREATE_COMPLETE), an ARN from a different role or account, or a role made from an older link. If the role works but no repositories show up, check the region and the repository names you limited it to.

Connection statuses

Each connection in Settings → Integrations shows a status:

Look at and maintain a connection

Click a connection to open its detail panel. It shows the account, region, who connected it and when, and when it was last checked. From there:

• Check connection tests that 3mote can still use it.
• Refresh repositories updates the list of repositories. Use it after you change what 3mote can see on GitHub or what your AWS role reaches.
• Rename changes the name shown in 3mote. Two connections can share a name, so the account line helps tell them apart.
• A searchable list of the connection’s repositories, with each one’s default branch and which projects use it.

Disconnect

Click Disconnect at the bottom of the detail panel. Before you confirm, 3mote lists what will change. Disconnecting:

• unlinks the connection’s repositories from the projects that use them;
• clears the Repository field on cards that named one of them;
• stops agents from working on those repositories.

Nothing is deleted on GitHub or in AWS: your code, your pull requests and your repositories are untouched. To finish cleaning up, uninstall the 3mote app in your GitHub settings, or delete the CloudFormation stack in AWS.

Plan limits

On the Free plan, the Connections counter next to Add connection shows how many you’ve used, for example “Connections · 1 of 1”, and Add connection is unavailable once you reach it. A CodeCommit setup you haven’t finished counts as a connection until you finish or discard it.

If a workspace moves to a plan with fewer connections than it has, nothing is removed. Every connection and project link stays, the oldest connections stay in use, and the rest show Paused until you disconnect one or upgrade.

Support for self-hosted Git servers (Team and Enterprise) and Git hosts on a private network (Enterprise) is coming soon. See Plans and storage.