Connectors

Overview

A connector links one provider account to an owner. The owner is a person or a team. Pipelines use the link without a token that you paste.

GitHub is the first provider, and container registries are the second. A connector installs the Kode GitHub App on your GitHub account or organization. Kode keeps no GitHub token. It asks GitHub for a short-lived token when a job needs one.

A person's connector belongs to that person. A team's connector belongs to the team. Any active member can list the connectors of a team. Only a team admin or owner can connect or disconnect.

A GitHub account connects to one owner. A second owner that connects the same account gets the error This GitHub account is already connected to another owner.

To do these tasks with an AI agent, see Agentic workflows.

What Kode reads and writes

A GitHub or GitLab connector gives git read access to the pipeline jobs of its owner. It also gives git read access to the workspaces, capsules, and device workspaces of its person. A team connector gives it to those of every member of the team. The own connector of a member comes first. Kode writes nothing to the provider.

A provider event, such as a push or a pull request, starts no run. A run starts by hand, on a schedule, from a webhook, or after another pipeline.

GitLab

A GitLab connector links one gitlab.com account to an owner. You sign in on GitLab and approve the Kode app.

After you connect, pick the projects to use in the Projects list of the connector. The list shows your projects, most recently active first. Type in the search box to narrow the list. Select Load more for the next fifty.

Kode lists only the projects where you are a Maintainer or Owner. It needs that role to make deploy tokens. If the list is empty, you hold no such project on this account.

Tick a project to use it, and select Save projects. Each git credential request makes a read-only deploy token on the ticked project. The token ends one hour after the request at most. Nothing revokes it when the job ends.

Clear the box of a project to remove its tokens. A save also removes a webhook that an earlier version made. The projects that you picked stay ticked while you search. If a save fails, the page shows the reason that Kode gives.

If the list cannot load, the page shows a box where you type the project as group/name.

Connect and reconnect

You connect in the web console. A terminal cannot show the consent page of GitHub, so no command connects an account. The console shows each connector as connected, expired, or revoked.

A connector becomes expired or revoked when GitHub removes the installation or the sign-in stops working. The console then shows Reconnect. The connector keeps its name.

Disconnect

A disconnect removes the connector. Kode uninstalls the app when it can, and deletes the stored data of the connector. A git command of a running job then gets no credential, and the log shows kd git-credential: no git connector of OWNER covers HOST/REPOSITORY. A registry login of a running job fails with connector NAME is gone.

Git in pipeline jobs

A job with permissions.git: read runs plain git clone https://github.com/OWNER/NAME in a step. Git asks the Kode credential helper for a credential each time, and the helper asks Kode.

The credentials are HTTPS only and read-only. A pipeline of a team uses only the connectors of the team. Kode makes no credential for other hosts. For them, put a personal access token from a Kode secret in the clone URL. A pull request cannot change the pipeline that tests it, because a pipeline is not stored in a repository. The rules and their errors are in Code in a job.

Container registries

A registry connector holds a login for a container registry. The registries are Docker Hub, GitHub Container Registry (GHCR), Azure Container Registry (ACR), Amazon ECR, Google Artifact Registry (GAR), and other OCI registries. You paste the credential in the console. Kode signs in to the registry with it before it keeps anything. For a pasted login, it signs in again every hour. A registry that refuses the credential turns the connector to expired.

A broader credential works too. Kode never shows the secret again.

For Amazon ECR and GAR, the credential that you paste is a root credential. Kode never hands it out. It keeps the root credential. It asks AWS or Google for a short login each time that a build, a pull or a job needs one. An ECR login lasts 12 hours. A GAR login lasts 1 hour.

For ECR without a role, give the access key ecr:GetAuthorizationToken on all resources. Also give it the push and pull actions on the named repositories only. The console shows the full policy.

Kode does not sign in to GHCR through the GitHub connector until a superadmin turns it on. Until then, paste a personal access token.

The connector of another member is never used. kd and docker-credential-kd ask Kode for a login each time, so a workspace holds no registry secret. With no registry connected, the commands answer no registry is configured.

Tasks

Connect GitHub

Reason for the task

Link a GitHub account or organization to a person or a team.

Job set-up

• Access: you. For a team, a team member with the role admin or higher.
• References: GET /v1/connectors.

Procedure

1. Open Connectors in your profile settings. For a team, open Connectors in the settings of the team.
2. Select Connect GitHub.
3. Install the Kode GitHub App on the account. Choose the repositories that pipelines use.
4. Sign in to GitHub when it asks, to prove who you are.

Close-out

1. List the connectors as in task 004. Make sure that the new connector is connected.

Reconnect a connector

Reason for the task

Restore a connector that is expired or revoked.

Job set-up

• Access: you. For a team, a team member with the role admin or higher.
• References: GET /v1/connectors.

Procedure

1. Open Connectors in your profile settings. For a team, open Connectors in the settings of the team.
2. Select Reconnect in the row of the connector.
3. Install the Kode GitHub App again. Sign in to GitHub when it asks.

Close-out

1. List the connectors as in task 004. Make sure that the connector is connected.

Disconnect a connector

Reason for the task

Remove the link to a GitHub account that pipelines no longer use.

Job set-up

• Access: you. For a team, a team member with the role admin or higher.
• References: DELETE /v1/connectors/{name}, kode connectors remove.

Procedure

1. Remove the connector acme-github-1. In the console, select Disconnect and type the name.

   PythonCopy

   from kloudlite import Kodekl = Kloudlite()kl.connectors.delete(name="acme-github-1")

   TypeScriptCopy

   import { Kode } from "./index.ts";const kl = new Kloudlite();await kl.connectors.delete({ name: "acme-github-1" });

   GoCopy

   kl := kloudlite.New(kloudlite.Options{})if err := kl.Connectors.Delete("acme-github-1"); err != nil {    log.Fatal(err)}

   RubyCopy

   require_relative "kloudlite"kl = Kloudlite::Client.newkl.connectors.delete(name: "acme-github-1")

   JavaCopy

   var kl = new Kloudlite();kl.connectors().delete("acme-github-1");

   CLICopy

   kode connectors remove acme-github-1

Close-out

1. List the connectors as in task 004. Make sure that the connector is not in the list.

List the connectors

Reason for the task

Find the connectors of an owner, and the state of each one.

Job set-up

• Access: you. For a team, a team member whose access is not paused.
• References: GET /v1/connectors, kode connectors list.

Procedure

1. List the connectors of the team acme. For your own, leave out the owner.

   PythonCopy

   from kloudlite import Kodekl = Kloudlite()print(kl.connectors.list(owner="acme"))

   TypeScriptCopy

   import { Kode } from "./index.ts";const kl = new Kloudlite();console.log(await kl.connectors.list({ owner: "acme" }));

   GoCopy

   kl := kloudlite.New(kloudlite.Options{})rows, err := kl.Connectors.List("acme")if err != nil {    log.Fatal(err)}fmt.Println(rows)

   RubyCopy

   require_relative "kloudlite"kl = Kloudlite::Client.newputs kl.connectors.list(owner: "acme")

   JavaCopy

   var kl = new Kloudlite();System.out.println(kl.connectors().list("acme"));

   CLICopy

   kode connectors list --owner acme

Close-out

1. Read the output. It shows the name, provider, account, and state, and never a token.

Connect a container registry

Reason for the task

Let builds push to a registry, and environments and pipelines pull from it.

Job set-up

• Access: you. For a team, a team member with the role admin or higher.
• References: POST /v1/connectors/{name}, kd container build.

Procedure

1. Create a token or a robot account in the registry. Give it the least rights that you need.
2. Open Connectors in your profile settings. For a team, open Connectors in the settings of the team.
3. Select the registry in Add a container registry.
4. Enter the host if the form asks, the path prefix, the user name, and the secret.
5. Enter the region, the access key ID, and the secret access key for Amazon ECR. Add the role ARN to use a role.
6. Enter the region, the path as PROJECT/REPOSITORY, and the JSON key of the service account for GAR.
7. Select Connect.

Close-out

1. List the connectors as in task 004. Make sure that the new connector is connected.

Troubleshooting