CircleCI will be moving to twice-yearly major and minor version releases of Server. Releases will be targeted for Spring (April) and Fall (October). Patch releases for bugs and security updates will be made monthly as needed.

We will support two minor releases or 1 year from the date of the release. This is a change from the current 4 minor releases or 1 year from the date of the release. After the April release of server 4.8, supported versions of server will include server 4.8 and server 4.7.

A catch-up release will be made available in the coming months that will allow existing customers to upgrade from 4.3, 4.5, and 4.6 variations to the most recent server version 4.7. Allowing customers to get to a supported version before we release 4.8 in April.

Server release 4.8 is planned to include some new features. The first enables more flexibility in defining which jobs or workflows run using conditional expressions. The second is the introduction of an observability stack that will enable proactive monitoring of the state of the server installations.

We are making some changes to when statements for workflows December 3rd. We will be adding conditional support to when statements so customers can do things like when: pipelines.git.tag == release. This conditional support allows for customers to run workflows based on pipeline parameters and values.

NOTE: When in Steps are not impacted by this change.

If you currently have when: always in your workflows you will need to make a change to your config. Always has never been a special value for workflow when, it is a non-empty string and currently evaluates as true. This is equivalent to removing the when key from your workflows.

Shortly the “always” string will be interpreted as an expression and will fail. To avoid your config failing to be processed you must remove the when from your workflows, which is equivalent to the prior behaviour.

For organizations that integrate with GitHub App, GitHub OAuth App, Bitbucket Cloud, and Bitbucket Data Center, we now pre-populate pipeline parameters when triggering pipelines in the CircleCI web app.

For more details or to share feedback, visit our community forum.

GitHub App triggers, previously uneditable, can now be edited.

Specifically, users can edit the following fields:

• Trigger name
• Config branch (if present)
• Checkout branch (if present)

Updates:

• For projects with a single pipeline, the modal now defaults to that pipeline, so users no longer need to select it from the dropdown
• Automatically populate the branch in the dropdown when users are on the Project > Branch page
• Added the ability to search in the branch dropdown within the modal
• Rolled out a fix so the text no longer duplicates when users copy and paste into the parameter inputs

The page Project Settings > Overview now includes a new “Project Slug” section, which lets users view and copy in one click the slug of their project.

Please note that both the following project slug formats are valid but mutually exclusive by project:

• github/org-name/project-name
• circleci/FMckQH4sfM6PsIPQEG1RLd/4CNEcx&6Yk6wkpwo2ft9Uo

Before Upgrading

See the CircleCI server 4.7 release notes and upgrade guide for this release.

NOTE: Vault is being deprecated and will no longer be supported in server 5.0. Refer to our script for steps to migrate to Tink.

What’s New in Release 4.7.0

The v4.7 release introduces security improvements with the implementation of rootless containers.

NEW FEATURES

• Approval jobs can now be canceled through the CircleCI UI or via the API.

CHANGES

• Server components now run as rootless containers, enhancing security.
• The Nomad server ReplicaSet is now scaled to 5 pods by default, which improves execution stability at scale.
• Configuration for the RabbitMQ PersistantVolumeClaim (PVC) is now exposed through server Helm values. For more details, see the docs.

BUG FIXES

• Resolved an issue where frontend pods would not automatically detect and apply a new server license.
• Fixed a bug where a workflow could be prematurely marked as failed before all non-blocking jobs were run.
• Fixed a configuration issue that could cause connection refusals between Kong and Soketi following an upgrade to version 1 of Soketi.
• Addressed a typo in the Helm values for machine_provisioner.machine_agent_base_url. The correct template value should be machine_provisioner.agent_base_url.

SERVICE CHANGES

Deprecated components removed with this release:

• web-ui-404: Previously served the 404 error page. Its functionality has now been merged into the main web-ui component.
• Support for GitHub Enterprise versions <= 2.2: Code supporting these versions has been removed, as they are no longer supported by GitHub.

DATABASE MIGRATIONS

The following databases will run migrations when upgrading to this version:

• authenticationservice
• conductor_production

KNOWN ISSUES

• SSH reruns in air-gap will time out, leaving the job in an error state
• Vault may not refresh its client token after a month of uptime. Migrate to Tink to resolve this issue.
• Retry with SSH for jobs using the machine executor advertises a private IP address. For this reason, retry with SSH for jobs using the machine executor works as standard for public installations, but for private installs you would need to ensure that you can access the private IP advertised. For example, by using a VPN into your VPC.
• CircleCI 1.0 builds are not supported. If an attempt is made to run a 1.0 build, no feedback will be available in the application to indicate the cause of the issue. If a build is run on your installation and does not show up in the CircleCI application, use the CircleCI CLI to validate the project configuration and get details of the possible cause of the issue.

To learn more about Server 4.7 installation, migration, or operations please review our documentation.

IP Ranges now support parameters providing more dynamic control of when ip ranges is used in builds.

Example

version: 2.1

parameters:
  ip_ranges:
    type: boolean
    default: true

executors:
  base:
    docker:
      - image: cimg/base:stable

jobs:
  job_a:
    executor: base
    circleci_ip_ranges: << pipeline.parameters.ip_ranges >>
    steps:
      - run: echo "Running job a"

workflows:
  workflow-a:
    jobs:
      - job_a

As a continuation of CircleCI’s update to enable access to “GitHub App functionality” to all CircleCI users (including users of the GitHub OAuth App integration), the “Triggers” tab in Project Settings of the CircleCI web app now shows a “GitHub OAuth App” trigger and a badge to indicate the integration type. This is intended to make it easier for all users to understand what is currently set up within their CircleCI project.

As part of CircleCI’s update to enable access to “GitHub App functionality” to all CircleCI users (including users of the GitHub OAuth App integration), the “Pipelines” tab in Project Settings of the CircleCI web app now shows a “GitHub OAuth App” or “Bitbucket Cloud” pipeline and a badge to indicate the integration type. This is intended to make it easier for all users to understand what is currently set up within their CircleCI project. A subsequent update will do the same for the “Triggers” tab.

Known issues: The organization name will be removed from the “Config Source” column to only show the repository name.

A new v2 API endpoint for triggering pipelines via API is now available to all organizations that integrate through GitHub (GitHub OAuth and GitHub App) and Bitbucket (Cloud and Data Center). This functionality is not yet available to organizations that integrate through GitLab.

The endpoint is:

POST /api/v2/project/{provider}/{organization}/{project}/pipeline/run

This is now the recommended API to be used to trigger pipelines.

The pre-existing endpoint for triggering new pipelines - which is only available to organizations integrating through GitHub oAuth or Bitbucket Cloud - continues to be supported.

Historically, CircleCI users have been limited to setting up validation systems that only worked within the scope of a single repository.

If a pipeline’s YML config was stored in Repo A, that pipeline could only be triggered from events on Repo A (or from a Custom Webhook). This has left many customers unable to set up the validation system that they want.

We have launched additional enhancements to pipeline and trigger configuration, which will enable customers to build any validation setup that they need.

Read more on our community forum.

Job Filters now support expression based conditions, much like contexts. This enables you to conditionally run jobs based on pipeline values. This supports you optimizing pipelines to lower costs, decrease time to feedback, or run specific jobs based on context of the source of change. Previously filtering was extremely limited to branches and evaluating to only and ignore.

Example for a Deploy workflow:

workflows:
  deploy:
    jobs:
      - init-service
      - build-service-image:
          requires:
            - init-service
      - dry-run-service:
          requires:
            - init-service
          filters: pipeline.git.branch != "main" and pipeline.git.branch != "canary"
      - publish-service:
          requires:
            - build-service-image
            - test-service
          filters: pipeline.git.branch == "main" or pipeline.git.tag starts-with "release"
      - deploy-service:
          context:
            - org-global
          requires:
            - publish-service
          filters: pipeline.git.branch == "main" and pipeline.git.commit.subject starts-with "DEPLOY:"

We will be following on this with expression based evaluations for When Statements which enable more flexibility in how you choose when steps or workflows run. When Statements are also currently limited in their evaluation options. Improving When Statements will expand your options optimizing for cost and speed.

We are enabling users who are a part an organization that integrates with CircleCI’s GitHub OAuth App to use functionality that was previously only available to organizations that integrate with CircleCI’s GitHub App.

The immediate change that users will see is the presence of “Pipelines” & “Triggers” tabs in Project Settings of the CircleCI web app.

Read our community forum for details.

GitHub App users who granted their App access to more than 100 repositories have been running into issues when creating Pipelines and Triggers on CircleCI, because the repository dropdown would only display a limited number of repositories.

We have now replaced the dropdown inputs with a search component, which lets users search repositories by keyword.

Note: at the moment the search results include all of an organization’s public repositories. We plan to adjust this behaviour in the near future.

Until today, the Pipeline property “Fallback branch” determined which branch would be used to fetch config and code for pipelines triggered via Custom Webhook. This field could only be configured by editing the Pipeline associated with a Custom Webhook, rather than by editing the Custom Webhook itself, and was poorly discoverable.

Now, the field “Fallback branch” has been removed from Pipeline configuration, and two new fields have been added to Custom Webhook setup:

• Config branch, which determines the branch to be used to fetch config
• Checkout branch, which determines the branch to be used to check out code when running a checkout step.

For existing custom webhook triggers, both new fields have been populated with the “fallback branch” value of the associated pipeline, so that existing behaviour is preserved.

Pipelines connected via GitHub App or Bitbucket Data Center can now be run via API, using a new API V2 endpoint:

https://circleci.com/api/v2/project/circleci/<org-id>/<project-id>/pipeline/run

See the docs for usage instructions. The new endpoint is not yet documented in the V2 API docs.

Orbs are the leading method to abstract away shared aspects of your pipelines. They make it possible to simplify the complex, share, and maintain jobs and commands across your organization. For large organizations, private orbs cab provide efficiency and scale.

Orb security settings now allow organizations to enable only private orbs. Previously orb settings required enabling uncertified orbs in order to enable private orbs. This prevented some organizations, whom were concerned about uncertified orb security, from benefiting from the private orbs.

For more information on orbs and creating your own private orbs see our documentation.