{"id":20490985,"url":"https://github.com/circleci-public/cimg-overview","last_synced_at":"2025-09-23T07:26:59.385Z","repository":{"id":42602218,"uuid":"178468972","full_name":"CircleCI-Public/cimg-overview","owner":"CircleCI-Public","description":"Overview of CircleCI's pilot project for revamped/improved convenience images","archived":false,"fork":false,"pushed_at":"2023-02-09T04:50:56.000Z","size":38,"stargazers_count":16,"open_issues_count":3,"forks_count":6,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-03-27T07:35:49.219Z","etag":null,"topics":["cimg","circleci","circleci-cimg","docker"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CircleCI-Public.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-29T20:05:11.000Z","updated_at":"2025-02-27T02:19:03.000Z","dependencies_parsed_at":"2024-11-19T02:52:22.902Z","dependency_job_id":null,"html_url":"https://github.com/CircleCI-Public/cimg-overview","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CircleCI-Public%2Fcimg-overview","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CircleCI-Public%2Fcimg-overview/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CircleCI-Public%2Fcimg-overview/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CircleCI-Public%2Fcimg-overview/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CircleCI-Public","download_url":"https://codeload.github.com/CircleCI-Public/cimg-overview/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248746693,"owners_count":21155314,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cimg","circleci","circleci-cimg","docker"],"created_at":"2024-11-15T17:19:20.471Z","updated_at":"2025-09-23T07:26:54.340Z","avatar_url":"https://github.com/CircleCI-Public.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# CircleCI \"cimg\" Convenience Images Overview\n\nThe CircleCI `cimg` Convenience Images are a suite of Docker images that are intended to replace the legacy Convenience Images.\nThe legacy images live in [this repository](https://github.com/circleci/circleci-images) and use the Docker Hub orgname `circleci`.\nThe new images live in this GitHub org (`CircleCI-Public`) and the repository names are prefixed with `cimg-`.\nThe Docker Hub orgname for the new images is `cimg`.\n\nEach Docker image has a repository where the image is built and its `Dockerfile` is located.\nThis GitHub org is maintained by the CircleCI Community \u0026 Partner Engineering Team.\n\nThis repository serves as an overview of CircleCI's revamped Docker convenience images pilot project. This project is intended to improve the user experience for CircleCI convenience images and solve a number of underlying problems in the original images' codebase.\n\n## Status\n\nSince there are many images, they are in different stages of their life cycle.\nThis table will show where each image is and how \"ready\" they are to replace their predecessor.\n\n| Name | Image | Release Life Cycle | GitHub | Docker Hub | Notes |\n| --- | --- | --- | --- | --- | --- |\n| Ubuntu Base | `cimg/base` |  **public beta** | [link](https://github.com/CircleCI-Public/cimg-base) | [link](https://hub.docker.com/r/cimg/base) | new image |\n| Android | `cimg/android` |  **alpha** | [link](https://github.com/CircleCI-Public/cimg-android) | [link](https://hub.docker.com/r/cimg/alpha) | Replaces `circleci/android` |\n| Clojure | `cimg/clojure` |  **public beta** | [link](https://github.com/CircleCI-Public/cimg-clojure) | [link](https://hub.docker.com/r/cimg/clojure) | Replaces `circleci/clojure` |\n| Elixir | `cimg/elixir` |  **private beta** | [link](https://github.com/CircleCI-Public/cimg-elixir) | [link](https://hub.docker.com/r/cimg/elixir) | Replaces `circleci/elixir` |\n| Go | `cimg/go` |  **public beta** | [link](https://github.com/CircleCI-Public/cimg-go) | [link](https://hub.docker.com/r/cimg/go) | Replaces `circleci/golang` |\n| Node.js | `cimg/node` |  **public beta** | [link](https://github.com/CircleCI-Public/cimg-node) | [link](https://hub.docker.com/r/cimg/node) | Replaces `circleci/node` |\n| OpenJDK | `cimg/openjdk` |  **public beta** | [link](https://github.com/CircleCI-Public/cimg-openjdk) | [link](https://hub.docker.com/r/cimg/openjdk) | Replaces `circleci/openjdk` |\n| PHP | `cimg/php` |  **public beta** | [link](https://github.com/CircleCI-Public/cimg-php) | [link](https://hub.docker.com/r/cimg/php) | Replaces `circleci/php` |\n| Python | `cimg/python` |  **public beta** | [link](https://github.com/CircleCI-Public/cimg-python) | [link](https://hub.docker.com/r/cimg/python) | Replaces `circleci/python` |\n| Ruby | `cimg/ruby` |  **public beta** | [link](https://github.com/CircleCI-Public/cimg-ruby) | [link](https://hub.docker.com/r/cimg/ruby) | Replaces `circleci/ruby` |\n| Rust | `cimg/rust` |  **public beta** | [link](https://github.com/CircleCI-Public/cimg-rust) | [link](https://hub.docker.com/r/cimg/rust) | Replaces `circleci/rust` |\n\n**Release Life Cycle:**\n- alpha - image is recently created and still in the prototyping phase. Will have big changes and may even be deleted.\n- private beta - image is tested on a 1 on 1 basis with specific people and teams to gather feedback. Breaking changes likely.\n- public beta - image can be used by anyone but please provide feedback if you have it, breaking changes less likely.\n- stable - image is considered production ready. Breaking changes are rare and will be communicated first.\n\n\n## Structure\n\n### Image Repository\n\nAn `ls -lah` of a typical image repository will show the following:\n\n```\ndrwxr-xr-x 4.0K Jul 10 13:35 .\ndrwxrwxr-x 4.0K Jul 10 11:50 ..\n-rwxr-xr-x   20 Jul 10 12:46 build-images.sh\ndrwxr-xr-x 4.0K Jul 10 13:35 .circleci\n-rw-r--r--  242 Jul 10 13:35 Dockerfile.template\ndrwxr-xr-x 4.0K Jul 10 13:36 .git\n-rw-r--r--   90 Jul 10 11:40 .gitmodules\n-rw-r--r-- 1.1K Jul 10 12:46 LICENSE\n-rw-r--r--   67 Jul 10 12:46 manifest\n-rw-r--r-- 1.2K Jul 10 13:34 README.md\ndrwxr-xr-x 4.0K Jul 10 11:33 shared\n```\n\nWe'll walk through the files one by one.\n\n`build-images.sh` - This is a Bash script that contains the `docker build` command(s) that will build the image(s).\nIt also is designed to build an image with the main Docker tag and any alias tags it may need.\nThis file is generated from `shared/generate-images.sh` (covered later) and should not be edited by hand.\n\n`.circleci` - This is a directory containing the CircleCI configuration file.\n\n`Dockerfile.template` - A template to create a Dockerfile.\nThis contains the `%%MAIN_VERSION%%` and `%%MAIN_SHA%%` variables that will be replaced by `shared/generate-images.sh` script (covered later).\nThese variables are the main software version and SHA.\nFor example, the Ruby version or Go version.\nThis file is the guts of what makes an image.\nThe middle of this file should have RUN/CP statements that configure the container to do whatever the image needs to do.\nTypically, this is installing the language, toolchain, and any relevant package managers and CI tools specific to this image.\n\n`.git`, `.gitmodules` - Git related files we won't touch directly.\n\n`LICENSE` - The source code license file.\nAll of our images at the moment will be using the MIT license.\n\n`manifest` - This small but important file holds key information about the image.\nIt holds the slug name of the repository, the slug name of the parent image this image is based off of, and what variants from the parent image it will use.\n\n`README.md` - The readme file should be helpful for people to know what the image is, how it works, and how to contribute.\nOutside of some image specific information, it should link to this repo for deeper understanding of how everything works.\n\n`shared`- This directory is a submodule pointing to the `cimg-shared` repo.\nThis repo can be found [here](https://github.com/CircleCI-Public/cimg-shared).\n\n  `shared/generate-images.sh` - This Bash script uses the information passed as commandline arguments, and the `manifest` file, to turn `Dockerfile.template` into multiple, buildable, Dockerfiles.\n  To you, from the root of the repo, you run it and pass the version of the software to build, and the SHA if you have one.\n  For example, to build Python v3.6.2, you would run: `./shared/generate-images.sh 3.6.2`.\n  The result of running this script is that directories for each major.minor version of the software is created, and `build-images.sh` is created.\n  Running this directly won't be necessary for regular version updates.\n  Instead, you can run the `release.sh` script.\n\n  `shared/release.sh` - This script should be run from the root of the repository, on the `master` branch.\n  This script automates most of the work for releasing a new image.\n  It will create a new branch for the version, run `generate-images.sh` for you, add all the files to git, create a commit, and push the branch to GitHub.\n  All you'd need to do afterward is open the PR itself.\n  Running this script is similar to running `generate-images.sh` as they use the same parameters.\n  For example, to build Python v3.6.2, you would run: `./shared/release.sh 3.6.2`.\n\n  Both scripts support more advanced versioning support for your images.\n  See the [Version Support](#version-support-version-groups) section for more information.\n\n\n## Version Support / Version Groups\n\nIn the examples so far, we see that the scripts `gen-dockerfiles.sh` and `release.sh` can be passed a version to build a release.\nThe `cimg-shared` repository actually has more powerful support than that.\nLet's breakdown what's supported.\n\n1. As we know, a version can be passed to the scripts.\nMore specifically, the version passed should be a full SemVer version number (major.minor.patch) or a partial SemVer (major.minor).\nWith either format, an optional letter 'v' can prefix the version.\nHere are valid versions: `1.14`, `1.13.6`, or `v2.10.0`.\n1. Multiple version numbers can be passed.\nEach one should be separated by a space.\nThe build system will build these images from left to right so older versions should be listed first and newer versions later.\n1. Each version passed to the script is actually called a \"version group\".\nThis is because in addition to the actual version number, a version alias or other parameter can be passed.\n    - An alias is a string that can be used instead of a version number.\n    This is common for projects such as Ubuntu where Ubuntu 20.04 could be called \"focal\" or Ubuntu 18.04 could be called \"bionic\".\n    Another common case is for Node.js which always runs two series of code at the same time.\n    They always have a \"current\" version as well as a \"lts\" version.\n    An alias can be passed right after the version with an equal sign (=).\n    For example: `14.0.0=current`, `v12.16.3=lts`, or `20.04=focal`.\n    - An additional parameter could be provided as well.\n    Some images might want to be passed a SHA hash, some a special download URL, etc.\n    This can be passed to the scripts either after the version or after an alias with a hash (#).\n    For example: `14.0.0#847r84uhuf4848`, `v12.16.3#https://example.com/download/12.16.3.tar.gz`, or `20.04#server-edition`.\n    - A version, alias, and parameter together are called a version group.\n    Only the version number is required in a version group, the other two are optional.\n    As before, each version group is separated by a space.\n1. Here's more examples of what's valid to pass to `gen-dockerfiles.sh` or `release.sh`:\n    ```\n    1.13.1 v1.14.2\n    v1.13.1#sha256abcfabdbc674bcg\n    v13.0.1=lts\n    v20.04\n    v8.0.252=lts=https://example.com/download/item.tar-gz\n    ```\n\n### Extending a Base Image\n\nAll of our Docker images extend a base image.\nThe majority of our images will extend the CircleCI Base Image `cimg/base`.\nThis base image, and thus most of the CircleCI Convenience Images, will be utilizing Ubuntu.\nThe base image will itself be based on the latest Ubuntu LTS release, 2 months after it's published.\nFor example, our base image will default to Ubuntu 20.04 in July 2020, and Ubuntu 22.04 in July 2022.\nLTSs will be supported for 3 years total, about 2 years as the default and about 1 year once it's no longer the default.\n\n## Contributing\n\nEach image has its own repository.\nPlease find the repository for the image in question, and then open a GitHub Issue or Pull Requests in that repository.\nGitHub Issues shouldn't be used for general image support, see [resources](#resources).\n\n### Creating New Repositories/Orbs\n\n1. The CPE Team should be added as admin.\n1. Force status checks should be enabled for `master`.\n1. Protect from pushing to `master` directly.\n1. Turn off Wiki/Projects for the repo.\n\n## Resources\n\nThis section needs to be built out.\nLinks to improved/new Image Docs as well as a second in Discuss needs to be created.\n\nSee [the `cimg` topic tag on the CircleCI-Public organization](https://github.com/search?q=topic%3Acimg+org%3ACircleCI-Public\u0026type=Repositories) for all repositories associated with new images work. The repositories under this topic tag consist of the following:\n\n- Documentation and shared resources ([`cimg-overview`](https://github.com/CircleCI-Public/cimg-overview), [`cimg-docs`](https://github.com/CircleCI-Public/cimg-docs), [`cimg-shared`](https://github.com/CircleCI-Public/cimg-shared));\n- A single base image ([`cimg-base`](https://github.com/CircleCI-Public/cimg-base));\n- A repository for each language/tool image covered by the current convenience images fleet (so far, only [`cimg-golang`](https://github.com/CircleCI-Public/cimg-golang) and [`cimg-ruby`](https://github.com/CircleCI-Public/cimg-ruby) exist)\n\n\n## Creating a New Image\n\nThe easiest way to create a new CircleCI Convenience Image is by cloning the `cimg-template` repository.\nDon't fork.\nThen change the Git remote to your new, empty repo.\nThis repo can be found [here](https://github.com/CircleCI-Public/cimg-template).\nYou'll want to start customising your repo for the image you're building.\nThe first step is to replace instances of `\u003c\u003cIMAGE_NAME\u003e\u003e` with the slug name of the image.\nFor example, if we were to setup the Python image, we would do the following:\n\n```\nsed -i 's/\u003c\u003cIMAGE_NAME\u003e\u003e/python/g' README.md manifest .circleci/config.yml\n```\n\n\n## Other Documents\n\nPlease see other files in this repository for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcircleci-public%2Fcimg-overview","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcircleci-public%2Fcimg-overview","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcircleci-public%2Fcimg-overview/lists"}