CircleCI's 2.1 config processing preview disables the $CIRCLE_COMPARE_URL environment variable, useful when working with monorepo projects. This orb manually recreates (and slightly improves!) it.
Originally, and as recreated here, $CIRCLE_COMPARE_URL outputs a URL of the following form, slighly different for GitHub vs. Bitbucket projects:
# GitHub
https://github.com/$CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME/compare/$COMMIT1...$COMMIT2
# Bitbucket
https://bitbucket.org/$CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME/branches/compare/$COMMIT1...$COMMIT2
$COMMIT2 always represents the current job's commit ($CIRCLE_SHA1). In the most common use case, $COMMIT1 will be the most recent previously pushed commit on the same branch as the current job.
If the current branch is new or has only ever had a single commit pushed to it, then $COMMIT1 will be the most recent ancestor commit as defined in the git specifications (whereas the original $CIRCLE_COMPARE_URL environment variable would, in this case, instead output a compare URL containing only $COMMIT2—essentially unusable in the monorepo scenario that this orb addresses).
Declare the orb in your config.yml file:
orbs:
circle-compare-url: iynere/[email protected]Then call the orb's reconstruct command or job:
steps:
- checkout
- circle-compare-url/reconstructworkflows:
deploy:
jobs:
- circle-compare-url/reconstruct
- deploy:
requires:
- circle-compare-url/reconstructFinally, the circle-compare-url/use command saves the CIRCLE_COMPARE_URL value, previously stored in file, to a local environment variable and transforms it into a true commit range value (stored as a COMMIT_RANGE environment variable), ready to be utilized as desired:
- circle-compare-url/use:
step-name: Desired step name to display on CircleCI
attach-workspace: # set this to `true` if `reconstruct` was called as a job; default is `false`
custom-logic: |
# what would you like to do with the $CIRCLE_COMPARE_URL/$COMMIT_RANGE values?
# this typically involves some kind of dynamic decision-making about release types,
# based on what level of changes were made to your source code between the base commit and the current commit
# for examples, see below
The orb's reconstruct command and job both take three optional parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
circle-token |
env_var_name |
CIRCLE_TOKEN |
Name of environment variable storing your CircleCI API token |
project-path |
string |
~/project |
Absolute path to your project's base directory, for running git commands |
debug |
boolean | false |
Additional debugging output for folks developing the orb |
when |
enum |
always |
Specify when this command will run ([always, on_fail, on_success]) |
Its job also takes an optional fourth paramater, which allows users to run the job in a smaller container to conserve resources:
| Parameter | Type | Default | Description |
|---|---|---|---|
resource-class |
enum |
medium |
Container size for reconstruct job (["small", "medium"]) |
The use command also takes three optional parameters and one that is technically optional but typically required:
| Parameter | Type | Default | Description |
|---|---|---|---|
step-name |
string |
Evaluate/use CIRCLE_COMPARE_URL | Specify a custom step name for this command, if desired |
attach-workspace |
boolean |
false |
Attach a workspace for this command to use? Useful when this orb's reconstruct job is called upstream in a given workflow |
workspace-root |
string |
"." | Workspace root path (either an absolute path or a path relative to the working directory), defaults to "." (the working directory) |
custom-logic |
string |
echo "What should COMMIT_RANGE ($COMMIT_RANGE) be used for?" | What should be done with the commit information created by the reconstruct command/job? See examples in the orb registry (or below) |
Refer to CircleCI's Reusing Config documentation for additional information about parameters.
The below examples are drawn from CircleCI's circleci-orbs monorepo, where the Compare URL Orb is used to automate publishing changes to individual orbs. See that repository's config.yml file for a more recent iteration of what follows.
By default, every new CircleCI step runs in a fresh shell. Thus, any environment variables stored during the circle-compare-url/reconstruct step would not be available to subsequent steps, without additional configuration by the end user (e.g., exporting the environment variable to a .bash_env and then file manually sourcing that file in any subsequent steps).
To mitigate this problem, the orb outputs the $CIRCLE_COMPARE_URL data to a file called CIRCLE_COMPARE_URL.txt, making it available to any subsequent steps (and even subsequent jobs, via Workspaces). It also persists this file, along with a BASE_COMPARE_COMMIT.txt file, to a workspace, for possible usage in downstream jobs.
Thus, as seen in the below examples, it may be necessary to save the contents of the CIRCLE_COMPARE_URL.txt file as a (step-localized) environment variable in any steps that will make use of the compare URL.
version: 2.1
orbs:
compare-url: iynere/[email protected]
jobs:
publish:
docker:
- image: circleci/circleci-cli
steps:
- checkout
- compare-url/reconstruct
- compare-url/use:
step-name: Publish modified orbs
custom-logic: |
for ORB in folder-containing-orb-subdirs/*/; do
orbname=$(basename $ORB)
if [[ $(git diff $COMMIT_RANGE --name-status | grep "$orbname") ]]; then
echo "publishing ${orbname}"
circleci orb publish ${ORB}/orb.yml namespace/${orbname}@version
else
echo "${orbname} not modified; no need to publish"
fi
done
workflows:
publish-orbs:
jobs:
- publishversion: 2.1
orbs:
compare-url: iynere/[email protected]
jobs:
publish:
docker:
- image: circleci/circleci-cli
steps:
- checkout
- compare-url/use:
step-name: Publish modified orbs
attach-workspace: true
command: |
for ORB in folder-containing-orb-subdirs/*/; do
orbname=$(basename $ORB)
if [[ $(git diff $COMMIT_RANGE --name-status | grep "$orbname") ]]; then
echo "publishing ${orbname}"
circleci orb publish ${ORB}/orb.yml namespace/${orbname}@version
else
echo "${orbname} not modified; no need to publish"
fi
done
workflows:
publish-orbs:
jobs:
- compare-url/reconstruct
- publish:
requires:
- compare-url/reconstructSee CircleCI's Creating Orbs documentation to get started.
This orb has only minimal testing—issues, pull requests, or other suggestions are welcome towards the goal of improving test depth/coverage.
See Creating automated build, test, and deploy workflows for orbs, part 1 and Creating automated build, test, and deploy workflows for orbs, part 2 for more information on automated orb testing/deployment.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent