CircleCI Self-hosted Runner Overview
Cloud Server v3.x Introduction
CircleCI self-hosted runner enables you to use your own infrastructure for running jobs. This means you will be able to build and test on a wider variety of architectures, as well as have additional control over the environment. The diagram below illustrates how CircleCI self-hosted runner extends our existing systems.
CircleCI runner use cases
There are two key use cases CircleCI aims to meet with the self-hosted runner:
-
Privileged access & controls - CircleCI understands that some customers require running jobs on on-premises or limited-access infrastructure due to stricter isolation requirements. Some things the self-hosted runner enables are:
-
IP restrictions - Runners can have static IP addresses that you can control
-
Identity Access Management (IAM) permissions - If you set up runners in AWS, they can be assigned IAM permissions
-
Monitor the operating system
-
Connect to private networks
-
-
Unique compute requirements - Customers who need to run jobs on an environment or architecture that CircleCI does not offer as a resource class can use the runner to fill that need.
Getting started
To get started with CircleCI self-hosted runners:
-
Provide your own platform to deploy your CircleCI self-hosted runners (see the Available CircleCI self-hosted runner platforms page for supported platforms)
-
Install CircleCI self-hosted runners!
CircleCI self-hosted runner operation
Once a CircleCI self-hosted runner is installed, the self-hosted runner polls circleci.com for work, runs jobs, and returns status, logs, and artifacts to CircleCI. When the self-hosted runner is not running a job, it will auto-update itself when a new version is released.
Limitations
Almost all standard CircleCI features are available for use with self-hosted runner jobs, however, a few features are not yet supported. If these features are important for you to make use of self-hosted runner jobs, please let us know via the relevant canny page.
-
The following built in environment variables are not populated within runner executors:
-
CIRCLE_PREVIOUS_BUILD_NUM -
All deprecated cloud environment variables
-
Learn more
Take the runner course with CircleCI Academy to learn more about running jobs on your infrastructure.
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Need support?
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
