Use a private repository

A rig fetches your project and your kit itself, from their git repositories. For a private repository, set up Git access once on control: a deploy key that control makes, or an access token you paste. Then choose it on the New campaign page. Control gives it only to the rigs that run a campaign that names it.

The New campaign page is the one place made for naming a Git access. From the command line, see From the command line.

Before you start

• You are signed in to the dashboard as the owner.
• You can add a deploy key, or make an access token, on the git host.
• Choose the kind of access by the repository’s address:

Access	Address it works with
A deploy key (control makes it)	ssh://git.example.com/you/project.git or [email protected]:you/project.git
An access token (HTTPS)	https://git.example.com/you/project.git

1. Add the Git access

1. Open Settings, the cog at the foot of the sidebar. The page is Providers.
2. Under Add a provider, set Type to A deploy key (control makes it) or An access token (HTTPS).
3. Fill in Name, such as project-deploy. Campaigns refer to the access by this name.
4. For a token, also fill in Token (read-only if the host allows it) and User name: the name the host expects with the token. Empty means x-access-token, which GitHub takes. GitLab takes oauth2.
5. Press Make the key or Add the token.

You see Made the deploy key "project-deploy": add its public key, below, to the repository as a read-only deploy key., or "project-deploy" is kept, sealed: choose it on the new-campaign page. The access shows in the Providers list as Git access. Control seals the secret and never shows it again.

2. Add a deploy key to the repository

For a deploy key, open its row in the list. It shows the public key. Add it on the git host as a read-only deploy key of the repository.

Many git hosts, GitHub among them, refuse one deploy key on a second repository. If both the project and the kit are private, make one Git access for each, or use one access token that can read both.

3. Try it

In the access’s row, enter the repository’s address under Try it on a repository and press Try it. Control reads the repository’s branches, as a rig would, and keeps nothing.

You see a line such as "project-deploy" reads [email protected]:you/project.git: its default branch is at 1a2b3c4, with 214 files., or "project-deploy" could not read … with the reason.

4. Choose it for a campaign

On Campaigns › New campaign:

• for the project, in 2 Project, write the address in Repository and choose the access in Repository access;
• for a kit in a repository, in 3 How to measure, choose it in Kit repository access.

Look it up then reads the project with the access. A deploy key needs an ssh:// or git@host:path address: an https:// one gives with an SSH deploy key, the repository is an ssh:// or git@host:path address. See Start a campaign from the dashboard for the other fields.

5. Check that the rig fetched it

The run shows on the campaign’s page, under At work now, within a minute or so. Press refresh in the status bar, the line along the bottom of the page. If the run doesn’t show, open Commands in the sidebar: the assign campaign row is failed, with the reason after staging:.

Reason	What to do
Git access project-deploy: control answered 404	Control has no Git access of that name for this rig. Check the name under Settings
… has no commit …	The commit is not in that repository, or the access can’t read it: use Try it on the repository
git’s own error, such as Permission denied (publickey)	The access can’t read the repository: its key is not a deploy key of that repository, or the token can’t read it. Try it shows the same error

When it is fixed, start the run again: press Start a run at the top of the campaign’s page, choose the rig, and press Start the run.

From the command line

thermite assign has no option to name a Git access. To start a run on a private repository from the command line, either put its commits in the rig’s inbox as git bundles (Start it when the rig can’t fetch), or name the access in the command yourself, with the owner’s token. (On a rig with a results repository, its deploy key can also read a project or kit whose source names no Git access: see Set up the results repository.)

Run npx thermite in your Thermite folder, after npm ci and npm run build (see the command line). The examples use the owner’s token file of the local stack, .dev/secrets/control-admin-token. If you made an owner’s token of your own, use its file instead.

1. Build the command’s payload with --print, with the repositories’ SSH addresses for a deploy key:

   npx thermite assign --contract contract.json --run sort-speed-1 \
     --seed [email protected]:you/project.git@0123456789abcdef0123456789abcdef01234567 \
     --kit [email protected]:you/project-kit.git --print > payload.json

2. In payload.json, add "access" and the access’s name beside the "git" address of each private repository:

   "source": { "git": "[email protected]:you/project.git", "access": "project-deploy" }

3. Send it:

   npx thermite command --control http://127.0.0.1:8800 --token-file .dev/secrets/control-admin-token \
     --rig local-1 --kind assign_campaign --payload @payload.json

Signed commands describes the payload’s sources. Then check that the rig fetched it, as in step 5.

Change or remove it

• A token: in its row, enter the new one under New token and press Replace the token. Campaigns that use it keep working.
• A deploy key: add a new access under a new name, add its key to the repository, and start the campaign’s next version with it.
• Delete this Git access removes an access. You see Rigs that ran with it keep nothing of it. An access that a campaign uses can’t be deleted: its row says In use by …: their runs fetch with it, so it can't be deleted. The row’s used by … line names those campaigns.