CircleCI FAQs

Some users may hit the following error while running bundle install after switching from an Xcode 10.x image to the Xcode 11 image on CircleCI.

The main error message to note is the following:

Gem::Ext::BuildError: ERROR: Failed to build gem native extension.

Why does this happen?

Recent versions of Xcode have removed the previously bundled macOS SDK headers package which installed the various Ruby 2.3 (system Ruby) headers required to build Ruby Gems. Without these headers, some Gems will fail during the bundle install phase with the following error message:

mkmf.rb can't find header files for ruby at

/System/Library/Frameworks/Ruby.framework/Versions/2.3/usr/lib/ruby/include/ruby.h

Steps to Resolve

This can be resolved by switching to one of the Ruby versions, available via chruby, that we ship with the Xcode 11 images. The versions of Ruby we ship can be found in the Software Manifests.

Follow the steps in our Using Custom Ruby Versions guide to switch to either Ruby 2.5 or Ruby 2.6 Once you have updated your config.yml, push a fresh commit to trigger a fresh build.

Sometimes during a job run, you may want to end the job early. You can end a job gracefully by running the commandcircleci-agent step halt

You can combine this with if statements to control the lifecycle of the job conditionally.

run: | if [ "$CIRCLE_BRANCH" = "develop" ]; then circleci-agent step halt

fi

One may sometimes want to interact with a GitHub or Bitbucket repository from within a CircleCI job, either in more than a read-only capacity, or with a repository external to the one being used for the current job. Either option requires generating a new SSH key, storing the public portion in the GitHub or Bitbucket repository with which the project will be interacting, and storing the private portion in CircleCI.

With the release of macOS Mojave, the default SSH key generated byssh-keygen is no longer the correct format for CircleCI. To generate a correctly formatted key on a computer running macOS, run the following command:

ssh-keygen -t rsa -b 4096 -m PEM

See GitHub and Bitbucket documentation for guidelines on storing SSH public keys:

https://developer.github.com/v3/guides/managing-deploy-keys

https://confluence.atlassian.com/bitbucket/use-deployment-keys-294486051.html

To store the private key in CircleCI, visit the Project Settings/SSH Permissions page:

https://circleci.com/[YOUR_VCS]/[YOUR_ORG]/[YOUR_PROJECT]/edit#ssh

Make sure to specify the hostname (github.com orbitbucket.org) when adding the private key.

Finally, the key will need to be added to yourconfig.yml file:

https://circleci.com/docs/2.0/configuration-reference/#add_ssh_keys

Check to make sure CircleCI is enabled in your GitHuborganization third-party app restrictions. You can read more about these restrictions on the GitHub docs page.

https://help.github.com/articles/about-oauth-app-access-restrictions/

You may sometimes want to run docker commands when SSH-ed into a rebuild for diagnostic purposes.

However, you may encounter the following error message when running a dockercommand in the SSH session:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

If you are encountering the above error in connecting to the remote Docker daemon which was set up by the setup_remote_docker step, you can try running docker and settingthe --tlsverify, -H, --tlscacert, --tlscert and --tlskey options to ensure that the right Docker daemon is being connected to.

First, please check the output of the "Setup a remote Docker engine" step in your build, to get the host and cert path of the remote Docker engine set up by CircleCI.

For convenience, you can set the environment variables in your SSH session, for example:

DOCKER_CERT_PATH=/tmp/docker-certs970508324DOCKER_HOST=tcp://35.237.187.184:2376

And then, you can reference the above environment variables when running docker commands with the --tlsverify, -H, --tlscacert, --tlscert and --tlskey options specified.

The example below shows how the docker ps command may be successfully run with the options specified.

docker --tlsverify -H=$DOCKER_HOST --tlscacert=$DOCKER_CERT_PATH/ca.pem --tlscert=$DOCKER_CERT_PATH/cert.pem --tlskey=$DOCKER_CERT_PATH/key.pem ps

If the CIRCLE_TAG built-in environment variable is not being populated even though you pushed a tagged commit, one way to resolve is to check what command is being used to push the commit.

The reason CIRCLE_TAG is not showing in your build could be that the first webhook being sent to CircleCI from GitHub / Bitbucket that is processed did not contain the tag information necessary for CIRCLE_TAG to be populated. The order of webhooks sent is influenced by the command used to push the commit.

To ensure that the first hook from GitHub that is processed is the one with the tag information, try pushing the commit by first pushing the tag rather than to the branch, e.g. usinggit push origin <tag-name>

Homebrew, by default, will check for updates at the start of any operation, meaning the step execution can take some extra time to complete.

It is best practise to leave Homebrew to automatically update, but if build speed, or bugs introduced by new updates, are of a concern, this can be disabled.

To disable this feature, add the following line to your config.yml before calling Homebrew:

- run: echo "HOMEBREW_NO_AUTO_UPDATE=1" >> $BASH_ENV

When building on CircleCI (or any other Linux/Unix environment), you may at some point run into a situation where a process has exited causing your build to fail. In this post, we aim to take you through what these codes mean and how they may have manifested.

If you have experienced exit code 137 and are looking for an immediate answer, please follow this link

At the end of most failed builds, you will find the shell will have exited with code 1. This is a catch-all error that simply means something has failed. However, if you search up further in the console, you are likely to find that your process has returned its own status code as it exited.

alarm(2)

What is an Exit Code?

When a process terminates on a Linux/Unix based system, it may pass a status code back to its parent process (likely your shell). It is common practice to return a 0 if the process has terminated gracefully, and any larger integer would indicate a failure of some condition.

The " Advanced Bash-Scripting Guide " has a great reference for reserved status codes you can expect to be standard across most applications.

Exit Code Number

Meaning

Example

Comments

1

Catchall for general errors

let "var1 = 1/0"

Miscellaneous errors, such as"divide by zero"and other impermissible operations

2

Misuse of shell builtins (according to Bash documentation)

empty_function() {}

Missing keyword or command, or permission problem (and diffreturn code on a failed binary file comparison ).

126

Command invoked cannot execute

/dev/null

Permission problem or command is not an executable

127

"command not found"

illegal_command

Possible problem with$PATHor a typo

128

Invalid argument to exit

exit 3.14159

exittakes only integer args in the range0 - 255(see first footnote)

128+n

Fatal error signal"n"

kill -9$PPIDof script

$?returns137(128 + 9)

130

Script terminated by Control-C

Ctl-C

Control-C is fatal error signal2, (130 = 128 + 2, see above)

255*

Exit status out of range

exit-1

exittakes only integer args in the range0 - 255

As we covered earlier, and as you can see in this chart, an exit code of 1 is expected in all cases to represent a generic error.

If you receive an exit code higher than 128, you have receiveda fatal error signal. Linux also has several standard signals. If you receive an error above 128, you must subtract 128 from that number to identify the signal.

Standard Linux Signals

We can see from the man page for Signal the list of standard signals. These signals provide additional insight into why a fatal error had been received.

Signal Value Action Comment

SIGHUP 1 Term Hangup detected on controlling terminal

or death of controlling process

SIGINT 2 Term Interrupt from keyboard

SIGQUIT 3 Core Quit from keyboard

SIGILL 4 Core Illegal Instruction

SIGABRT 6 Core Abort signal from abort(3)

SIGFPE 8 Core Floating-point exception

SIGKILL 9 Term Kill signal

SIGSEGV 11 Core Invalid memory reference

SIGPIPE 13 Term Broken pipe: write to pipe with no

readers; see pipe(7)

SIGALRM 14 Term Timer signal from

SIGTERM 15 Term Termination signal

SIGUSR1 30,10,16 Term User-defined signal 1

SIGUSR2 31,12,17 Term User-defined signal 2

SIGCHLD 20,17,18 Ign Child stopped or terminated

SIGCONT 19,18,25 Cont Continue if stopped

SIGSTOP 17,19,23 Stop Stop process

SIGTSTP 18,20,24 Stop Stop typed at terminal

SIGTTIN 21,21,26 Stop Terminal input for background process

SIGTTOU 22,22,27 Stop Terminal output for background process

So, if you receive the exit code of 137, you must subtract 128 as we stated above to identify which signal you received.

137 - 128 = 9 orSIGKILL

In the scope of CircleCI, 'SGKILL' likely means your build went over its allocated resources, such as RAM, and was ended in response.

Cache Clearing

With CircleCI 2.0, you gain more control over your caches. You can add a versioning prefix to the beginning of your keys and increment it when you want to clear out and rebuild the cache.UI environment variables are useful here, as you could set a variable likeCACHE_VERSION=v1, then change it tov2in the UI and re-run a job without pushing a commit.

Still having cache issues?

If you've cleared your project's cache and still feel like you're having cache related issues, submit a support ticket and we'll take a closer look.

https://circleci.com/docs/2.0/caching/#example-caching-configuration

You may wish to clear the cache for your project in the event it becomes corrupt or old. You may also notice you have the ability to re-run your build without a cache, only to find out that after your next build, you are still pulling from the outdated cache.

"Rebuild without cache" only runs a single build without your cache.

To Delete Your Cache

Your cache is saved via a specified key. Perhaps like so:m2-{{ checksum "pom.xml"}} You can "clear" your cache by changing this key.

m2-v2{{ checksum "pom.xml"}}

This will start a fresh cache under a new key.

This can commonly happen when you're running your tests within a multi-line run step.

Example:

- run:

name: run tests

command: |

source venv/bin/activate

python manage.py test

To work around this addset -e at the top of the multiline command. This will ensure that errors are not suppressed and are instead passed up to fail the build.

- run:

name: run tests

command: | set -e

source venv/bin/activate

python manage.py test

It's not possible to use volume mounting with the docker executor, but using themachine executorit's possible to mount local directories to your running Docker containers. You can learn more about the machine executor here on our docs page.

You may run into this error while using docker-compose with DLC enabled. You'll want to make sure that the network is removed prior to running docker-compose in each job. You could rundocker network rm ${network_name} || true. Thetruemakes sure that a non-zero result isn't returned if the network doesn't exist. This should prevent network name collisions.

Here is a trick to give yourself a cache that is cleared daily. This is not required or recommended for many use cases but can prove potentially useful for some instances.

For instance, in building static blog sites that fetch from external API's, you may want to clear your cache periodically to ensure any new information is fetched.

How:

Early in your job create a file containing today's date without a timestamp

- run: date +%F > date

You can now use this file to test against when choosing when to rebuild cache by utilizing the checksum template.

- restore_cache:

keys:

- date-cache-{{ checksum "date" }}

- save_cache:

key: date-cache-{{ checksum "date" }}

paths:

- "/docs"

The checksum of the `date` file will remain static until the next day, at which point a new cache will be created.

If you receive the following error message while running a CircleCI 2.0 build:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

This typically indicates that you are running a docker command without using remote docker.

In order to run any docker command on CircleCI 2.0 you need to add the setup_remote_docker step as described in the following documentation.

Currently, published orbs are world-readable as long as they are referenced by the correct name. We do not support private orbs at this moment but you are most welcome to provide your feedback on this on our Ideas Portal.

While private orbs are not supported at this time, orb publishers can unlist their orbs from Orb Registry search results by using our CLI (See the documentation of the relevant command here: https://circleci-public.github.io/circleci-cli/circleci_orb_unlist.html ). Unlisted orbs can be listed in the orb registry again with the same CLI command. Only org admins can unlist/list orbs. Note that unlisting an orb does not affect its ability to be referenced by name in builds or for its source to be viewed.

You may see this message in your builds if the tag name includes a forward slash character, `/`. This character is currently not supported for Docker tags.

More on supported characters for tag names can be found on the Docker Tag documentation.

We have instructions and examples of using docker-compose with the docker executor here on our docs page.

CircleCI has a built-in 10 minute no-output timeout. This means that if it has been 10 minutes since the last output, the build will be cancelled and stopped. This can cause users to encounter issues where they intend for a part of their build to continue beyond 10 minutes without giving output, but the system kills it.

The no_output_timeoutparameter for run gives users the option to change the no-output timeout from the default 10 minutes to a user-specified timeout.

For example, if we have a run step as follows:

- run: command: . ./ourlongscript.sh

If we expect our script will take a while to complete execution, we can extend the no-output timeout as follows:

- run:

command: . ./ourlongscript.sh

no_output_timeout: 30m

The value set for no_output_timeout can be in hours, minutes or seconds - a digit followed by h, m or s respectively. Partial times can also be used, like 1.5h.

You may run into a situation where your app attempts to access the database before it is ready to accept connections, resulting in a failure. It this case it is necessary to wait for the database to come online fully before continuing.

We suggest dockerize: https://github.com/jwilder/dockerize

In this example PostgreSQL is our database. Our first run step downloads the newest Dockerize binary and the next run step `Wait for db` waits on the port for our database until it receives a response, with a 1 minute timeout.

version: 2.0

jobs:

build:

docker:

- image: your/image_for_primary_container

- image: postgres:9.6.2-alpine

environment:

POSTGRES_USER: your_postgres_user

POSTGRES_DB: your_postgres_test

workDir: /your/workdir

steps:

- checkout

- run:

name: install dockerize

command: wget https://github.com/jwilder/dockerize/releases/download/$DOCKERIZE_VERSION/dockerize-linux-amd64-$DOCKERIZE_VERSION.tar.gz && sudo tar -C /usr/local/bin -xzvf dockerize-linux-amd64-$DOCKERIZE_VERSION.tar.gz && rm dockerize-linux-amd64-$DOCKERIZE_VERSION.tar.gz

environment:

DOCKERIZE_VERSION: v0.3.0

- run:

name: Wait for db

command: dockerize -wait tcp://localhost:5432 -timeout 1m

You can apply the same principle for MySQL:

dockerize -wait tcp://localhost:3306 -timeout 1m

Redis:

dockerize -wait tcp://localhost:6379 -timeout 1m

and other services such as web servers

dockerize -wait http://localhost:80 -timeout 1m

Running the Android emulator is not currently supported onCircleCI 2.0, since it's not supported by the type of virtualization CircleCI uses on Linux. We recommend using an external service such as Firebase Test Lab to run your emulator tests from yourCircleCI job.

You can use the gcloud Command Line to do this. (We're working on documenting a full example to help get this set up. If you get something working, do let us know on Discuss.) The gcloud tools are preinstalled on theCircleCI Docker images for Android - see the Dockerfiles here and Docker Hub links here.

Follow the links for more information on branch filtering based on your config type.

2.0 config

2.0 config workflows

OnCircleCI 2.0 the only supported way to do CodeSigning is to use Fastlane Match as described in the code signing documentation.

Note: Forfastlane match to work correctly, you must addsetup_circle_ci tobefore_all in yourFastfile. This ensures that a temporary Fastlane keychain is used.

If you see errors like "Code Signing Error: No profile" or "Provisioning Profile Not Found" it's likely that youdon'thave the keychain unlocked.

You canrun security find-identity -v -p codesigning from inside the build to list the current status of your code signing credentials.

Sometimes you'll see a blue banner on your build page indicating that there was an issue and the job was re-run automatically.

These issues are not related to your project. Sometimes CircleCI will suffer infrastructure failures, and in these instances, we will try to automatically start the job again. If you notice this happening for an extended period on your project please submit a support ticket.

Both CircleCI 1.0 and 2.0 have the ability to send notifications to Slack. They are configured in the same way as show in this documentation.

To support the delivery of the CircleCI services, Circle Internet Services, Inc., dba CircleCI (or one of its affiliates listed below) uses service providers that may store and process personal data about visitors to the CircleCI website and authorized users of the CircleCI platform.

The processors we engage may change. Please check this page regularly for updates.

Third-Party Processors

CircleCI currently uses the following third-party processors:

Entity Name

Processing Activities

Entity Country

Aha!

Roadmap software.

USA

Amazon Cloudfront, AWS S3 / AWS RDS

Amazon Cloudfront is the content delivery network for CircleCI.com. Our data warehouse is on AWS.

USA

Amplitude

Visualize data from Segment

USA

Appcues

User onboarding software

USA

Atlassian

Software development and collaboration tools.

Australia

Bill.com

Digital business payments.

USA

Bing

Search marketing through the Bing ad network.

USA

Calendly

Scheduling software.

USA

Calibre

Web site monitoring.

USA

Chargify

Subscription billing software.

USA

Clearbit

Contact enrichment for Sales.

USA

Cookiebot

GDPR and ePrivacy compliant online tracking.

Denmark

DataDear

Excel add-in.

Malta

Datadog

Cloud monitoring service.

USA

DemandTools

Data quality tool.

United Kingdom

Discourse

Internet forum and mailing list management software.

USA

DiscoverOrg

Sales and marketing intelligence platform.

USA

DocuSign

Contract management.

USA

Drift

Chat software.

USA

Dropbox

Secure file sharing and storage.

USA

Engagio

Engagement with existing customers.

USA

Eventbrite

Platform to manage live events.

USA

Facebook

Potential customers contact us via Facebook forms.

USA

Gainsight

Customer success platform for managing NPS process.

USA

Google Cloud, Google AdWords, Google Analytics, Google Tag Manager, YouTube

Google Cloud: Provides word processing, spreadsheet, and presentation needs. Google AdWords: Search ads on Google. Google Analytics: Web analytics. Google Tag Manager: Manage third-party pixels. YouTube: Host videos

USA

Honeycomb

Log analysis.

USA

Host Analytics

Platform that accelerates reporting, analytics, financial planning, and close processes.

USA

HotJar

Web analytics.

Malta, Europe (EU)

LeanData

Lead routing in Salesforce.

USA

LinkedIn

Potential customers contact us via LinkedIn forms.

USA

ListenLoop

Display ads tailor-made for Account Based Marketing (ABM).

USA

Looker

Business intelligence through data visualization.

USA

Mailgun

Product related emails (system notifications).

USA

Marketo

Marketing automation software.

USA

Microsoft

GitHub authentication.

USA

MongoDB

Next-generation database.

USA

Optimizely

Web optimization.

USA

Outreach

Enterprise engagement platform for sales.

USA

Percy

Automated visual reviews for web apps.

USA

PureB2B

Content marketing platform.

USA

Pusher

Real-time data and functionality for web and mobile applications.

United Kingdom

Rollbar

Error monitoring and debugging for developers.

USA

Salesforce.com Inc.

Sales automation platform.

USA

Segment

Event management platform for reporting and analytics.

USA

SendSafely

End-to-end encryption platform.

USA

Showpad

Sales enablement platform to give sales team the content and the knowledge they need.

USA, Belgium

Slack

Communication and collaboration platform.

USA

Stripe

Payment platform to accept and manage online payments.

USA

Terminus

Account-based marketing capability.

USA

Tray.io

Integrate product data with downstream systems.

USA

Twitter

Demand generation on Twitter platform.

USA

Xero

Cloud accounting software.

New Zealand

Zapier

Integrate CircleCI form fills with downstream systems.

USA

Zendesk

Customer service platform.

USA

Zuora

Billing management platform.

USA

If you see the following banner appear on your jobs page:

"Your project references CircleCI 1.0 or it has no configuration. CircleCI 1.0 and projects without configuration files are no longer supported."

there is most likely a build missing its config.yml file or 1.0 version build on the page you are viewing. Once you've run a few more builds, thus pushing older builds to the next page, you'll no longer see the banner in the UI.

If you are still seeing this banner, please submit a ticket to Support or write to [email protected].

You may encounter the following error when trying to install a Ruby gem.

Unable to download data from https://rubygems.org/ - SSL_connect returned=1 errno=0 state=

This is a result of infrastructure updates at rubygems.org. You can find more details and solutions to this error here on their docs page.

Overview

CircleCI connects your GitHub orBitbucket account to our system.

If you no longer want to build on CircleCI, visit your project settings page https://circleci.com/add-projects/gh/USERNAME and click "Unfollow all projects".Your account will then be inactive.

[email protected]

Note:If you're using a Bitbucket account, replace `gh` with `bb` in the URL above.

If you need to cancel your paid plan, please follow the steps here How to cancel or modify your plan

Delete account

If you would like full deletion of your account, please submit a support ticket or contact

If you are utilizing Workflows and either saving and restoring cache or persisting your Workspaces, keep in mind the users and directories involved. If you are using CircleCI convenience images, each Docker container runs under the same user with the same base permissions. If you save your cache in a job that uses one image, and it is restored in another, make sure they have compatible permissions.

If you receive the error "Permission denied" when restoring your cache, check where it had been saved in the previous job. A common instance of this is when using an image as the root user and saving cache, then attempting to restore that cache in a later job with a user who does not have root access.The same error will cause files in a persisted workspace to be missing as well if the permissions are not set correctly.

customizing one of our images

You can see here in this `Restoring Cache` step, the cache was originally saved to `/root/tmp` as the original image was runningas root and had it's working directory set to `~/tmp`. In this part of the Workflow, running under the CircleCI user, we do not have access to the `/root` folder.

If possible, use the same image across multiple jobs. If this is not possible, try setting yourworking directory to a common location between the two images (`/tmp` may work for some). You may need to change or set file permissions before saving yourcache.

Example: Use `chmod-R 777 ./workingDirectory` to give full read/write access to these files.

The best option is to use a common image among your jobs. If the convenience images we provide are missing something essential to your project, consider .

Architecture Permissions Issues

Caches generated in environments can also run into permissions issues when they are restored in environments that use a different architecture. To prevent these issues try adding the{arch} variable to your cache key. This will make sure that caches are unique to the environment they're generated in.

- restore_cache:

key: '-v1-node-cache-{{ checksum "yarn.lock" }}-{{ arch}}'

- run:

name: Install App

command: yarn

- save_cache:

key: '-v1-node-cache-{{ checksum "yarn.lock" }}-{{ arch }}'

paths:

- node_modules

If you run into this error when trying to login to https://discuss.circleci.com you can resolve it by going to the user settings page and send a password reset email to yourself. This will provide a link so that you can configure a password to use in the future.

As part of CircleCI's SOC 2 compliance efforts and continuously bolstering our security practices more generally, we have adopted wider implementation of two-factor authentication (2FA) across many of our applications and systems, including our community forum.

Our goal is to provide our users the benefit of the additional layer of security offered by 2FA and decreasing the probability that an attacker can impersonate a user and gain access to accounts or other sensitive resources. 2FA also provides a safe and secure way for our users and customers to reset their own passwords if/when needed.

The error "Certificate Signed By Unknown Authority" may indicate your Docker container lacks ca-certificates, which are used to check against and authenticate SSL connections. Without this package, some features of CircleCI will be unable to function, such as downloading workspaces.

Error when attempting to use Workspaces :

Error downloading workspace layer for job xxxxx: RequestError: send request failed

caused by: Get https://xxxxxxxx.amazonaws.com/xxxxxxxxxxxxxxxxxx:

x509: certificate signed by unknown authority

Resolution

Install the ca-certificates package for your Linux distribution.

Install for Alpine:

apk add ca-certificates

If your Android builds are suddenly failing with the error message "A problem occurred starting process 'command '/opt/android/android-ndk-r17b/toolchains/mips64el-linux-android-4.9/prebuilt/linux-x86_64/bin/mips64el-linux-android-strip'', when the transformNativeLibsWithStripDebugSymbolForRelease gradle task is run, and previously the task used to run successfully, the cause of the error may be an update to CircleCI's convenience Docker images for Android published around 31st July 2018 midnight GMT time.

If you are using any of the CircleCI convenience images from https://hub.docker.com/r/circleci/android/, please try specifying a specific sha256 digest for the image, in your CircleCI configuration file, that was previously working with your builds. For instance, using "circleci/android:api-27-alpha@sha256:83c8a732f88652e4c160c1481b7233a1968bc6d52a5917224c81b5f5268117db" instead of "circleci/android:api-27-alpha" may resolve the build error.

For related information on how to ensure your CircleCI convenience image-based builds do not break when incompatible changes are introduced to the images, please see this article.

in our documentation

ERROR: Repository not found.

fatal: Could not read from remote repository.

Please make sure you have the correct access rights and the repository exists.

Exited with code 128

If you receive this error, more than likely you are attempting to access a private repository from within your container without authentication. You will need to create a "User Key" and add it to your project.

More information on creating a user key can be found .

A common issue with running NodeJS test suites that spawn workers/threads in a Docker container is that these scripts will spawn too many workers/threads and cause excessive memory usage. In most cases this will cause jobs to fail withENOMEM errors.

This happens because the scriptlooks at the number of CPUs available on the physical machine, which can be 32+ cores, rather than the number vCPUs the Docker container has been allocated.

The number of workers/threads your test suites uses will need to be configured to not exceed the number of vCPUs allocated to the resource class in use (medium by default).

For example, if using Jest, set the maxWorkers option:

--maxWorkers=2

There are a number of reasons why test splitting across parallel containers may be behaving unexpectedly. Our documentation on Running Tests in Parallel has a wealth of information to help you, too.

Save Artifacts

The store_test_results step will ensure test timings are saved, but it doesn't allow for easy debugging. You may also want to upload your tests via store_artifacts to visually verify the number of tests being run.

Echo Test Results

Similar to saving artifacts, here is an example of how you can implementa clean test split command and also echo out the test data.

TESTFILES=$(circleci tests glob "test/**_test.rb" | circleci tests split --split-by=timings)

echo ${TESTFILES}

# bundle exec rake knapsack_pro:minitest

bundle exec rspec --format progress \

--format RspecJunitFormatter \

-o test/reports/rspec.xml \

-- ${TESTFILES}

Examples on our community forums, Discuss

Find Slowest Test

Some testing libraries such as RSpec will report back the "Slowest test":

Our documentation has more information about splitting tests here

Investigate these tests to see if they take considerably longer than other test files, and see what can be done to make the test smaller or more efficient.

Vary Your Parallelism

Different amounts of parallelism may have a great effect on your tests, depending on the way they are written. It may also help you identify particular tests that are causing problems repeatedly.

Resync Timings

Timing data will be saved upon a successful "green" build. These results are then analyzed over the previous several builds when being used for splitting in the future. If these results are skewed or otherwise improper, they will continue to affect your build timing after you have corrected the issue. Once the issue has been resolved, the timing data will normalize over the next severalbuilds and produce the expected results. Please take this into consideration and push several commits to flush the system. You can view your timing data in$CIRCLE_INTERNAL_TASK_DATA/circle-test-results if you need to.

Variable Length Tests

You may have a test or suite of tests that naturally will vary greatly in their completion time, either on purpose, or for a number of other reasons. This is common with UI or Unit Testing. If your test timing varies with every test, the CircleCI splitting system will never be able to determine valid timing data.

Consider Other Ways to Split Tests

If your android build is failing withINSTALL_FAILED_INSUFFICIENT_STORAGE ?Try increasing the partitionsize of the emulator with:emulator -partition-size 1024

You can adjust the value depending on your project requirements.

CircleCI starts with the config.ymlbut the base of your build begin with the Dockerfile.

If you are entirely new to Docker, please check out the officialgetting started guide:

https://docs.docker.com/get-started /

What is a Dockerfile?

Docker builds images automatically based on the information presented to it in the Dockerfile. This defines the operating system you'll be running, install any software or dependencies required for your project, and execute commands in the shell automatically.

Because many of our users often need similar environmentsand tools, we have created a selection of maintained Dockerfiles suited best for projects on CircleCI with different languages available. You can view these "convenience" images here:https://hub.docker.com/r/circleci/

Why make a custom Dockerfile?

While you can use our images install your own tools on top of them, this may not be the most efficient method for your use case. You may have a large selection of software that needs to be included that would best be served in the base Docker image rather than installed on CircleCI every time you run a build. Or perhaps you have unique OS requirements that we simply do not have a convenience image for at this time.

On that note, if you think we are missing something, let us know!https://circleci.com/ideas/

How to make a Dockerfile

Dockerfile Wizard

https://docs.docker.com/engine/reference/commandline/build/

https://github.com/CircleCI-Public/dockerfile-wizard

This tool is an automated script for Linux and MacOS to generate Dockerfiles for use with CircleCI. This script will prompt you for some popular options for operating systems, tools, databases, and more. When the script is complete, it will generate a CircleCI config.yml. Commit your project and follow it from your CircleCI dashboard to begin building.

The new project will build your newly created Dockerfile and automatically push your image to Dockerhub.After the Docker image has been published the `test_image`job will begin, which will pull your newly created Docker image from Dockerhub

More information here: https://circleci.com/blog/build-custom-docker-images-faster-and-more-easily-with-our-dockerfile-wizard/

Code your own Dockerfile

Get more fine control by building your own Dockerfile.

Official Docs: https://docs.docker.com/engine/reference/builder

Start with an empty folder with whatever name you like, and enter it with cd

mkdirmydockerfile

cd mydockerfile

Inside your folder you need your Dockerfile, it's most common to name this as such.

touch Dockerfile

And you can open this file up in your favorite text editor.

FROM

'FROM' is the first and most important command in your Dockerfile. This specifies the base image for your Docker build. This is most commonly a distro of Linux though other options exist. You can browse through the DockerHub to find a suitable base image for your Dockerfile.

You can see every image shows the pull command which also shows you the image name

You can also find the available tags for that base image. Tags are generally different versions or variants of the base image. Without a tag, you will always pull the newest image, if you want to ensure your builds are consistent you should choose a tag as well.

When you have chosen your image and tag you may insert this into your 'FROM' line like so

FROM alpine/3.5

WORKDIR

Adding 'WORKDIR' will set the working directory inside of the container. This will be the target for any following commands and act somewhat as the 'root' folder.

WORKDIR /app

COPY

Now that we have an operating system we can work with, let's feed it a script. This is optional by the way. Let's stay we have a script called install.sh in our root directory with our Dockerfile. What we want to do is copy that script into our running Docker container. So somewhere underneath the 'FROM' command, let's add 'COPY'. COPY takes two parameters, the first being the source and the second being the destination.

COPY install.sh .

If you established the 'WORKDIR' earlier, this should copy install.sh to /app/install.sh

RUN

You now have a base image but, this container doesn't really do much, though it would run. RUN will allow us to execute commands in the shell so we can control the OS the same way we would locally.

RUN install.sh

'RUN' is extremely powerful and can do anything you would be able to do sitting in front of the terminal. This command above will execute/app/install.sh

Minimize layers and keep your image small

Best practices to follow when writing Dockerfiles:https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practices/One of the best reasons to use CirlceCI's convenience images is because of the high probability that we will have layers from your image cached on the host, decreasing your spin-up time. But you may want a smaller image, or have another need not solved by our images.

It is in your best interest to limit the number of layers in your build and the total build size.

Each ADD, COPY, and RUN command adds an additional layer to your build. Make sure when possible to chain commands like so.

Run apt-get update && apt-get upgrade -y \

apt-get install -ynodejsnpm

Or give multi-stage builds a try:https://docs.docker.com/engine/userguide/eng-image/multistage-build/#use-multi-stage-builds

Start with a small base image

Many base images out there still come with a host of tools that you may not need at all for the purposes of your project.

The Ubuntu Trusty image is 43mb compressed (which can be well over 100mb uncompressed), which is nice, but consider you may only need Alpine which comes in at 2mb.

Build your image

On your local machine, enter the terminal and enter the following command while in your root directory for the project.

docker build -t IMAGENAME/TAG

This command will start the build of your image as well as name it. The TAG is optional.

Push to Dockerhub

There are many ways to deploy your Docker build to a repo, right now we are only going to discuss pushing your image to Dockerhub.

Login to Dockerhub.

docker login -u USERNAME -p PASSWORD< /code>

Once you have logged in you are ready to submit your build to Docker.

docker pushIMAGENAME/TAG

You've Done It!

Your docker image will now be available on the Dockerhubon your profile

If your build produces persistent artifacts such as screenshots, coverage reports, core files, or deployment tarballs, CircleCI can provide a link to download them. You can find them on the 'Artifacts' tab:

Netlify

The documentation for using artifacts is here: https://circleci.com/docs/2.0/artifacts/

We don't make guarantees about how long an artifact is available. If you're relying on them as a source of documentation / persistent content, we recommend deploying the output to a dedicated output target, such as GitHub Pages or for static websites.

Overview

This is a guide for users to modify your Linux and macOS plans. To change or cancel your plan, visit your org settings page ( https://circleci.com/gh/organizations/ORGNAME/settings ) then follow the appropriate steps below. If you encounter any issues, contact [email protected].

Note: Admin access is required to modify your plan. For more information, visit Am I an Org Admin?

Performance Plan

Upgrade to the Performance Plan

Please reach out to [email protected] to understand how your current Container Plan usage compares to the Performance Plan and to assist with switching.

As long as you are only making changes to your billing/payment information and continue to use the same account on CircleCI, your build history and project settings (env variables, advance settings, checkout keys, etc.) will remain intact.

Please be aware that changing your GitHub org and/or usernames can result in unintended side effects, which can cause your project settings to not sync over properly.

Make changes to your Performance Plan

If you find you need higher concurrency, contact [email protected] to put in a request to increase concurrent jobs.The default limit is set to 40x parallelism for jobs to prevent credit overuse.

Cancel your Performance Plan

Go into your org settings page directly within your account. An admin can cancel the plan by clicking "Cancel Plan" toward the bottom of the page.

Note: Performance Plans will stay active until the end of your current billing cycle.

Container Linux and macOS Plans

Note:Container plans are grandfathered cannot be re-purchasedafter cancellation.

Modify your Container Plan

Linux -Click Add Containers on your org settings page.

macOS -Click "Change Plan" on your org settings page.

Cancel your Container Plan

Linux -Change your paid containers to 0 and the "Pay Now" button will change to "Cancel Plan".

macOS -Click "Cancel your current macOS plan" on your org settings page.

If you continue to experience issues, please reach us at [email protected]

How do I change my credit card on file?

Go to your billing portal by clicking on the Manage Billing and Statements button on your Plan overview page and click Update Payment Method.

How do I update my billing contact?

Go to your billing portal by clicking on the Manage Billing and Statements button on your Plan overview page. Go to My Account and add or alter the fields in the Account Information area. Please also select Update Contact Information before clicking Save.

We received a credit card billing failed message

A failed credit card transaction could be due to insufficient funds, an expired or canceled card, or the bank declining the charge for some other reason. If there were insufficient funds, please increase the limit on the card. If it is expired or canceled, update the card in your billing portal by clicking on the Manage Billing and Statements button on your Plan overview page and click Update Payment Method. The charge will automatically retry when you update the card on file. If it was not one of those reasons, we suggest getting in touch with your bank for more details about the nature of the decline.

Where can I retrieve my statements?

Go to your billing portal by clicking on the Manage Billing and Statements button on your Plan overview page and click Statements. This will take you to your list of prior statements. If you are looking for past statements thataren'tavailable, contact [email protected] for one of our associates to retrieve invoices from our previous billing portal.

How do I cancel my Bootstrap or other GitHub Marketplace plans and switch to Performance?

If your settings page state your plan is managed by GitHub Marketplace, you must cancel your plan via GitHub. Because GitHub Marketplace is billed on a monthly basis, you will need to wait for your billing cycle to end before signing up on CircleCI. If you have any further questions, please contact GitHub Support. You can read more about GitHub Marketplace here https://github.com/marketplace/circleci.

Yes! You can deploy to Heroku onCircleCI 2.0 by following our docs here.

If you are experiencing AWS authentication errors despite having provided the correct AWS credentials in your project or context environment variables, etc (e.g. AWS_SECRET_ACCESS_KEY, AWS_ACCESS_KEY_ID or other means as documented in https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html ), this may be caused by AWS credentials previously set for the project in a legacy settings page that has now been removed from our UI, as part of the EOL (End-of-Life) of CircleCI 1.0

To verify if this is the case, you can still access the legacy settings page by directly visiting its URL, which will be in the format

For example, for the CircleCI-Public/circleci-demo-workflows GitHub project, the URL to directly access the legacy page would be: https://circleci.com/gh/CircleCI-Public/circleci-demo-workflows/edit#aws

We strongly recommend clearing any values found on this legacy page, so that they will not unexpectedly interfere with authenticating to AWS in your builds.

Note: The legacy settings page is subject to being completely taken offline in the future, when the steps in this article are no longer applicable.

his error is most likely due to a recent change in a package for Google Chrome - it no longer pulls in libgconf-2-4 as a dependency.

Adding in a step like the following:

sudo apt-get install libgconf-2-4

shouldget your builds back to normal.

If you see something like this on CircleCI 2.0 builds:

/bin/bash: mongo: command not found

This is because all of your commands will run in the first container that is listed (primary container). This is typically not the database container, which means that themongocli is likely not installed in the primary container. The same can happen for mysql and postgresql.

In these cases you can install the client using sudo apt install or the relevant package manager for the distro your image is running.

example:

- run: sudo apt-get install mongodb-clients

More details on Discuss here: https://discuss.circleci.com/t/bin-bash-mongo-command-not-found/16218/6

In the "Spin up Environment" step, or elsewhere when pulling a Docker image from a repository, you may run into an error similar to the following:

Step 1/26 : FROM <IMAGE>

latest: Pulling from library/<IMAGE>

no matching manifest for linux/amd64 in the manifest list entries

Exited with code 1

There are three possible reasons for this error.

Error When Using "Latest" TagWhile images are rebuilding on Dockerub, the "latest" tag will become momentarily unavailable while updating. This issue will resolve itself or can be mitigated by selecting a versioned tag.

The Tag Is Not AvailableA tag that used to be available may no longer be listed or have had it's naming convention modified. A tag may have been "Version8.0" previously and became "Version8.0.0" recently.

Image Is Not Designed For x86, Such As ARMThe image you are trying to build may be designed to run on a different architecture, such as an ARM-basedCPU.

If you see a build failure with:

Cannot find a job named `build` to run in the `jobs:` section of your configuration file.

If you expected a workflow to run, check your config contains a top-level key called 'workflows:'

Check how the job was triggered (top right):

Triggered by:username (updated project settings)

This usually means a build was triggered when settings were changed in the UI. If the config includes a CircleCI 2.0 Workflow then it will fail since it tries to run without the context of understanding that it's a Workflow. We're aware of this issue and plan to fix it in the future.

To solve the issue for future builds, push a new commit toGitHub orBitbucket and the Workflow will run correctly.

There are few secret-storage options that CircleCI can support at this time:

You can store them as plaintext using Contexts resources (org-wide) or environment variables (job-specific), and thenechothem into files, etc., at job runtime via your config.yml

You can encrypt files and store them in your source repository, but store the decryption keys in CircleCI, again either via Contexts or job environment variables, and then decrypt as-needed at job runtime

You can use a third-party secret storage solution (for example, Hashicorp's Vault ), so long as it has a headless CLI-accessible option that you can use in your CircleCI job (which Vault does)

For further questions or suggestions for your particular use-case, please contact [email protected]

Overview

An "Unregistered User" is how CircleCI tracks users who have triggered builds but have not signed up for CircleCI. These users will count as "Active Users", despite being unregistered.

How can I see who an unregistered user actually is?

Because the "Unregistered User" has not signed up for CircleCI, we do not have permission to view who triggered the build to run. The easiest way to see who an "Unregistered User" is actually referencing is to go by the commit hash. Find a job with a blank profile image - the top right corner of the job will display the name of the committer along with a truncated commit hash, which can be clicked to go straight to the commit on GitHub or Bitbucket. From there you can view the author of the commit.

follow projects

How do my unregistered users become registered users?

To make a user known, they can sign up for CircleCI with their GitHub or Bitbucket login. If they are part of your organization, they can in order to view build history.

If an "Unregistered User" signs up for CircleCI, will they appear?

A user previously unknown to CircleCI will not replace the "Unregistered User" entity associated with builds or taking up seats since CircleCI retains no information necessary to link the two. If this user is still taking up a user seat, they will be removed upon the next billing cycle when "active users" reset.

You may have a use case for creating a new commit and pushing it to the same repository as part of your CircleCI job.

Configuration Steps

Here is how you can configure your CircleCI project to enable the above-mentioned use case.

1) Decide if you wish to configure the project with a user key generated by CircleCI or a manually-created read-write deployment key

1a) If you wish to use a user key, simply visit https://circleci.com/:vcs-type/:org-name/:project-name/edit#checkout and click on the "Authorize with GitHub" button.

1b) If you wish to use a read-write deployment key, follow the steps here to create it and configure the project so that the key has write permissions for it: https://circleci.com/docs/2.0/gh-bb-integration/#creating-a-github-user-key or https://circleci.com/docs/2.0/gh-bb-integration/#creating-a-bitbucket-user-key for Bitbucket users

Common Issues:

1) "*** Please tell me who you are." error message upon running "git commit"

In your CircleCI configuration file (config.yml), you might have to add commands to configure an email and user name with `git config` prior to running `git commit`, e.g.

git config user.email "[email protected]"git config user.name "My Name"

2) Running git push results in "ERROR: The key you are authenticating with has been marked as read only."

The deploy key that the project is configured with, by default when you add a project on CircleCI, only has read access, so a key with write permissions needs to be configured to be used, to avoid the above error message. Please ensure that a user key or a read-write deployment key has been configured for the project (See "Configuration Steps" above).

If you are using a read-write deployment key, please add an add_ssh_keys step to your configuration. The fingerprints value should match what is shown on https://circleci.com/:vcs-type/:org-name/:project-name/edit#ssh

3) How to stop your generated commits from triggering new builds

To prevent a commit from triggering a new build, add "[skip ci]" to the commit message. For more details, see: https://circleci.com/docs/2.0/skip-build/#skipping-a-build