> For the complete documentation index, see [llms.txt](https://cleyrop.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cleyrop.gitbook.io/docs/documentation-fr-en/the-factory/gerer-les-images.md).
# Manage images
A Docker image is an executable version of your code, built from a Git repository and stored in Cleyrop's internal registry.
***
## Manage images in the internal registry
To build Docker images from your source code, you must connect an external Git repository.
### Connect a private repository
**Prerequisites:**
* Have a GitLab repository with your source code and a Dockerfile
* Have access to the Cleyrop platform SSH key (available in your user profile)
Connection to a private repository is done via SSH.
1. From your App page, go to the **Internal registry**
2. Click on **Create an image**
3. In the **Repository**, click on **+ Add an external repository**
4. Enter the**SSH URL** of your repository (e.g., `git@gitlab.com:mon-org/mon-repo.git`)
5. Click on **Copy your SSH key** to retrieve the platform's public key
6. In GitLab, add this key as a **Deploy Key** :
* Go to your repository → Settings → Deploy keys
* Click on **Add deploy key**
* Paste the copied SSH key
* Check **Allow write access** if needed
7. Go back to Cleyrop and click on **Test your connection**
8. If the test succeeds, click on **Add**
{% hint style="info" %}
Name your key with a clear name so you can find it again
{% endhint %}
### Connect a public repository
If your repository is public, no deploy key is necessary.
1. In the **Repository**, click on **+ Add an external repository**
2. Enter the**HTTPS URL** of your repository (e.g., `https://gitlab.com/mon-org/mon-repo.git`)
3. Click on **Test your connection**
4. If the test succeeds, click on **Add**
### Error handling
| Error | Cause | Solution |
| ------------------------------------------ | ---------------------------- | ---------------------------------------------------------- |
| "We were unable to access your repository" | SSH key not added or invalid | Check that the Deploy Key is properly configured in GitLab |
| "Insufficient permissions" | Missing read permissions | Make sure the Deploy Key has read permissions |
| "This repository contains no tags" | Repository without Git tags | Create at least one tag or use a branch |
{% hint style="success" %}
The platform SSH key is also viewable from your **user profile** → section **SSH keys**.
{% endhint %}
## Create and build an image
1. From your App page, go to the **Internal registry**
2. Click on **Create an image**
3. Configure the repository (see previous section)
4. In the **Configuration** :
* Enter the **path to the Dockerfile** (e.g., `/Dockerfile`)
* Choose which reference will be used to build the image: a **branch** or a **tag** Git.
* Choose the relevant branch or tag from the dropdown menu.
5. In the **Image** :
* The version name is pre-filled with the branch/tag name
* You can change it if needed
6. Click on **Create**
{% hint style="info" %}
Reuse an existing version name **overwrites** the previous image. A confirmation message is shown before the operation.
{% endhint %}
The build is launched. The image can have the following statuses:
| Status | Description |
| --------------- | -------------------------------------------------------------- |
| **In progress** | Build in progress |
| **Valid** | Build succeeded, image available in the registry |
| **Error** | First build failed, no image available |
| **Warning** | Rebuild failed, but a previous valid version remains available |
## Available actions on an image
* **Rebuild** : rerun a build on the same branch/tag (fetches the latest commit)
* **Delete** : delete the image from the registry
* **Copy the URL** : copy the image URL to use it in an instance
* View the result of the **CVE scan** from the build
* **View the build logs:** Build logs are available in the image detail page. They help diagnose errors if the build fails.
### Best practices for building images
* **Use Git tags** for your production versions rather than branches
* **Version explicitly** your images (e.g., v1.0.0, v1.1.0) to make rollback easier
* **Check the build logs** if the build fails to quickly identify errors
* **Avoid overwriting** production images: create a new version rather than rebuilding on the same tag
***
## Git repositories
A Git repository is a Git versioning space **hosted directly on the Cleyrop platform**, without requiring an external repository or credentials configuration.
It allows you to **centralize and version the source code** intended to power one or more Apps. A repository can be used by several Apps simultaneously, and exists independently of them.
### Access Git repositories
Internal repositories are accessible from **The** **Factory > Git repositories**
Each project member can view the list of existing repositories. For each repository, you can see:
* The repository name
* Its owner
* The number of Apps using it
| Role | Permissions |
| ------------- | -------------------------------------------------------- |
| Owner | Read, write, file upload, file deletion, branch creation |
| Other members | Read only |
### Create a Git repository
* Go to **The** **Factory → Git repositories**
* Click on **Create**
* Enter the name, identifier, and description
* Click on **Create**
You are automatically redirected to the repository detail page. A file `README.md` is automatically created on the branch `main`.
{% hint style="info" %}
The repository creator automatically becomes its owner.
{% endhint %}
### Explore a repository - detail page
A repository detail page is organized into three tabs:
* **Files** — Browse the tree, view and edit files
* **Information**
The owner can edit the information:
* Rename the repository or change its description
* Transfer repository responsibility to another Platform Manager or Data Worker
### Manage a repository's files
From the **Files**, select a branch and perform the following actions (owner only):
**Edit a file**
* Select the desired branch
* Navigate to the file and open it
* Modify the content
* Click on **Save** — a commit is automatically created
**Upload a file**
* Select the desired branch
* Click on **Upload**
* Select one or more files (100 MB max per file)
* Confirm — a commit is automatically created
**Delete a file**
* Select the desired branch
* Open the file
* Click on **Delete**
* Confirm deletion — a commit is automatically created
**Create a branch**
* From the detail page, click the branch selector
* Enter the name of the new branch
* Select the source branch (default: `main`)
* Confirm
{% hint style="info" %}
Creating a branch does not impact any existing App.
{% endhint %}
### Delete a Git repository
Only the repository owner can delete it. Deletion is irreversible.
1. Go to **The Factory → Git repositories**
2. Open the detail page of the repository to delete
3. Click on **Delete**
4. Enter the repository name to confirm
Upon deletion:
* The repository is removed from the platform
* The associated Git repository is permanently deleted
* The apps that used this repository remain accessible but can no longer be built until a new valid repository is associated
### Use a Git repository in an App
An internal repository can be used as a build source for a Docker image for an App or a Tool.
From your App page, tab **Internal registry** :
1. Click on **Create an image**
2. Choose **Internal repository** as the source
3. Select the desired repository
4. Choose the Git reference type (branch or tag) and the corresponding reference
5. Start the build
{% hint style="info" %}
Only repositories you own are listed.
{% endhint %}
From an App detail page, a tab **Linked repositories** lists all internal repositories used as build sources for this App.