Connectors

Description and operation

General

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 Kloudlite GitHub App on your GitHub account or organization. Kloudlite 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.

Hugging Face is the second provider. See Hugging Face.

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 – General.

What Kloudlite 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, benches and sandboxes of its person. A team connector gives it to those of every member of the team. The own connector of a member comes first. Kloudlite 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.

Hugging Face

A Hugging Face connector links one Hugging Face account to an owner. You sign in on Hugging Face and approve the Kloudlite app. The app asks for the scopes openid, profile, read-repos and write-repos. An owner has one Hugging Face connector. A second connect answers OWNER already has a Hugging Face connector.

A connector has one of two levels. The level is set by the owner that connects.

A pipeline job of a team never gets the token of a member.

The token is the environment variable HF_TOKEN. Kloudlite stores it as a secret that the connector manages. You cannot set or delete it with the secret commands. They answer HF_TOKEN is managed by connector NAME. If the env of a resource names HF_TOKEN, your value is used and the connector adds nothing.

Kloudlite refreshes the token before it expires. A process that runs keeps the token that it had at its start. A refresh restarts nothing and sets no restart_required. A resource that starts later has the new token. A disconnect deletes the HF_TOKEN secrets of the connector.

GitLab

A GitLab connector links one gitlab.com account to an owner. You sign in on GitLab and approve the Kloudlite 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.

Kloudlite 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 Kloudlite 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. Kloudlite 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 kl 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 Kloudlite credential helper for a credential each time, and the helper asks Kloudlite.

The credentials are HTTPS only and read only. A pipeline of a team uses only the connectors of the team. Kloudlite makes no credential for other hosts. For them, put a personal access token from a Kloudlite 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. Kloudlite 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. The choice is yours. Kloudlite never shows the secret again.

For Amazon ECR and GAR, the credential that you paste is a root credential. Kloudlite 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.

Kloudlite 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. kl and docker-credential-kl ask Kloudlite 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 Kloudlite 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. Show 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 Kloudlite GitHub App again. Sign in to GitHub when it asks.

Close-out

1. Show 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}, kloudlite connectors remove.

Procedure

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

   PythonCopy

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

   TypeScriptCopy

   import { Kloudlite } 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

   kloudlite connectors remove acme-github-1

Close-out

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

Show 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, kloudlite connectors list.

Procedure

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

   PythonCopy

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

   TypeScriptCopy

   import { Kloudlite } 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

   kloudlite connectors list --owner acme

Close-out

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

Connect Hugging Face

Reason for the task: Give your workspaces, or the pipelines and services of a team, the variable HF_TOKEN.

Job set-up

• Access: you. For a team, a team member with the role admin or higher.
• References: Hugging Face.

Procedure

1. Open Connectors in your profile settings. For a team, open Connectors in the settings of the team.
2. Select Connect Hugging Face.
3. Sign in to Hugging Face when it asks. Approve the Kloudlite app.

Close-out

1. Show the connectors as in task 004. Make sure that the connector is connected.
2. Start a workspace and run printenv HF_TOKEN in it. Make sure that the variable is set.

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}, kl 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. Show the connectors as in task 004. Make sure that the new connector is connected.

Troubleshooting