Use CircleCI version 2.1 at the top of your .circleci/config.yml file.
1
version: 2.1
Add the orbs
stanza below your version, invoking the orb:
1
2
orbs:
salesforce-sfdx: circleci/salesforce-sfdx@3.0.2
Use salesforce-sfdx
elements in your existing workflows and jobs.
Create, open, and then delete a scratch org.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
version: '2.1'
orbs:
sfdx: circleci/salesforce-sfdx@x.y
jobs:
create-open-delete:
executor: sfdx/default
steps:
- checkout
- sfdx/install
- sfdx/auth:
defaultusername: user@email.com
- sfdx/scratch_create:
scratch_alias: circleci
scratch_config: ./config/project-scratch-def.json
- sfdx/scratch_open:
scratch_alias: circleci
- sfdx/scratch_delete:
scratch_alias: circleci
workflows:
basic-test:
jobs:
- create-open-delete
Simple example showing how to install the Salesforce sf CLI with the default options and authenticate against it with JWT.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
version: '2.1'
orbs:
sfdx: circleci/salesforce-sfdx@x.y
jobs:
install_authenticate:
executor: sfdx/default
steps:
- checkout
- sfdx/install
- sfdx/auth:
defaultusername: user@email.com
- run:
command: >
echo You now have access to the sf cli and may execute commands
against it.
sf auth list
name: Run your SF commands here
workflows:
basic-test:
jobs:
- install_authenticate
Authenticate with and configure the SF CLI after installation. This orb utilizes JWT-based authentication. You will need to create a connected app and provide a base64 encoded server key for authentication. Learn more: https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth_jwt_flow.htm
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
apiVersion | The API version for a specific project or all projects. Normally, the Salesforce CLI assumes that you're using the same version of the CLI as the Dev Hub org. | No | '' | string |
consumerKey | The consumer key of the connected app for salesforce. Stored as an environment variable | No | SFDX_CONSUMER_KEY | env_var_name |
decryption_key | Environment variable name for server.key decryption key, if available. | No | DECRYPTION_KEY | env_var_name |
defaultdevhubusername | The username of your Dev Hub org that the 'org create scratch' command defaults to. Used as alias. | No | ${CIRCLE_PROJECT_REPONAME}-${CIRCLE_BRANCH} | string |
defaultusername | The username for an org that all commands run against by default. | Yes | - | string |
instanceUrl | The URL of the Salesforce instance that is hosting your org. | No | '' | string |
jwtKey | Environment variable containing the base64 encoded private server key. | No | SFDX_JWT_KEY | env_var_name |
server_key | Path to encrypted server.key within the project, if available. | No | '' | string |
Install and configure the Salesforce "sf" cli utility giving access to the "sf" commands. Set parameters to automatically set the sf config values. Also able to be set via environment variables. Learn more: https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_dev_cli_config_values.htm
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
version | By default, the latest version of the standalone CLI will be installed. To install via npm, supply a version tag such as "latest", "latest-rc", "nightly", "2.1.1", etc. | No | '' | string |
"Create a scratch Salesforce Org."
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
overrides | Overrides for scratch organization. | No | '' | string |
scratch_alias | The alias of the scratch Org. | Yes | - | string |
scratch_config | The scratch JSON definition. | Yes | - | string |
"Delete a scratch Salesforce Org."
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
scratch_alias | The name of the scratch Org, can either be the alias or target username. | No | '' | string |
"Open a scratch Salesforce Org."
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
scratch_alias | The name of the scratch Org, can either be the alias or target username. | No | '' | string |
This is a sample executor using Docker and Node. If you want to provide a custom environment in your orb, insert your image here. If you do not require an executor, you can simply delete this directory.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
tag | Pick a specific circleci/node image variant: https://hub.docker.com/r/cimg/node/tags
| No | lts | string |
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
# This code is licensed from CircleCI to the user under the MIT license.
# See here for details: https://circleci.com/developer/orbs/licensing
version: 2.1
description: |
Salesforce SF CLI integration for CircleCI. Easily create CI/CD pipelines for your Salesforce integrations.
display:
home_url: https://github.com/CircleCI-Public/Salesforce-sfdx-cli-orb
source_url: https://github.com/CircleCI-Public/Salesforce-sfdx-cli-orb
commands:
auth:
description: |
Authenticate with and configure the SF CLI after installation. This orb utilizes JWT-based authentication. You will need to create a connected app and provide a base64 encoded server key for authentication. Learn more: https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth_jwt_flow.htm
parameters:
apiVersion:
default: ""
description: The API version for a specific project or all projects. Normally, the Salesforce CLI assumes that you're using the same version of the CLI as the Dev Hub org.
type: string
consumerKey:
default: SFDX_CONSUMER_KEY
description: The consumer key of the connected app for salesforce. Stored as an environment variable
type: env_var_name
decryption_key:
default: DECRYPTION_KEY
description: Environment variable name for server.key decryption key, if available.
type: env_var_name
defaultdevhubusername:
default: ${CIRCLE_PROJECT_REPONAME}-${CIRCLE_BRANCH}
description: The username of your Dev Hub org that the 'org create scratch' command defaults to. Used as alias.
type: string
defaultusername:
description: The username for an org that all commands run against by default.
type: string
instanceUrl:
default: ""
description: The URL of the Salesforce instance that is hosting your org.
type: string
jwtKey:
default: SFDX_JWT_KEY
description: Environment variable containing the base64 encoded private server key.
type: env_var_name
server_key:
default: ""
description: Path to encrypted server.key within the project, if available.
type: string
steps:
- when:
condition:
not: << parameters.server_key >>
steps:
- run:
command: |
if [ -z $<<parameters.jwtKey>> ]; then
echo "Authentication requires a base64 encoded server key to be provided as an environment variable. Please ensure the <<parameters.jwtKey>> env var has been set correctly."
exit 1
fi
if [ -z $<<parameters.consumerKey>> ]; then
echo "Authentication requires a consumer key to be present. Please ensure the <<parameters.consumerKey>> env var has been set correctly."
exit 1
fi
echo Creating jwt key file.
echo
if [ -f ./server.key ]; then
echo "It appears you may have committed your server.key file. For your safety please never commit secrets to your code repository. We instead recommend utilizing environment variables for this purpose. You may wish to invalidate and regenerate your server key."
exit 1
fi
echo $<<parameters.jwtKey>> | base64 --decode --ignore-garbage > ./server.key
name: Check and install SFDC authentication key
- when:
condition:
and:
- << parameters.decryption_key >>
- << parameters.server_key >>
steps:
- run:
command: |
openssl enc -aes-256-cbc -md sha256 -salt -d -in << parameters.server_key >> -out server.key -K << parameters.decryption_key >> -pbkdf2
name: Decrypt SFDC authentication key.
- run:
command: |
#! /bin/bash
sf config set org-instance-url="${INSTANCE_URL}" --global
sf auth jwt grant \
--client-id "${CONSUMER_KEY}" \
--jwt-key-file ./server.key \
--username "${DEFAULT_USERNAME}" \
--instance-url "${INSTANCE_URL}" \
--set-default-dev-hub \
--alias "${DEFAULT_DEVHUB_USERNAME}"
sf config set org-api-version="${API_VERSION}"
environment:
API_VERSION: <<parameters.apiVersion>>
CONSUMER_KEY: <<parameters.consumerKey>>
DEFAULT_DEVHUB_USERNAME: <<parameters.defaultdevhubusername>>
DEFAULT_USERNAME: <<parameters.defaultusername>>
INSTANCE_URL: <<parameters.instanceUrl>>
name: Authenticate with Salesforce
install:
description: |
Install and configure the Salesforce "sf" cli utility giving access to the "sf" commands. Set parameters to automatically set the sf config values. Also able to be set via environment variables. Learn more: https://developer.salesforce.com/docs/atlas.en-us.sfdx_setup.meta/sfdx_setup/sfdx_dev_cli_config_values.htm
parameters:
version:
default: ""
description: By default, the latest version of the standalone CLI will be installed. To install via npm, supply a version tag such as "latest", "latest-rc", "nightly", "2.1.1", etc.
type: string
steps:
- when:
condition: <<parameters.version>>
steps:
- run:
command: |
command -v npm >/dev/null 2>&1 || { echo >&2 "NPM not installed in the current environment. Aborting."; exit 1; }
if [[ $EUID == 0 ]]; then export SUDO=""; else # Check if we're root
if ! [[ -w $(npm root -g) ]]; then
export SUDO="sudo";
fi
fi
$SUDO npm install @salesforce/cli@<<parameters.version>> --global
name: Install SF - NPM
- unless:
condition: <<parameters.version>>
steps:
- run:
command: |
cd /tmp
wget https://developer.salesforce.com/media/salesforce-cli/sf/channels/stable/sf-linux-x64.tar.xz
mkdir sf
tar xJf sf-linux-x64.tar.xz -C sf --strip-components 1
echo 'export PATH=/tmp/sf/bin:$PATH' >> "$BASH_ENV"
name: Install SF - Standalone
- run:
command: sf --version
name: Verify SF installation
scratch_create:
description: |
"Create a scratch Salesforce Org."
parameters:
overrides:
default: ""
description: Overrides for scratch organization.
type: string
scratch_alias:
description: The alias of the scratch Org.
type: string
scratch_config:
description: The scratch JSON definition.
type: string
steps:
- run:
command: |
#! /bin/bash
sf org create scratch -f "${SCRATCH_CONFIG}" -a "${SCRATCH_ALIAS}" "${SCRATCH_OVERRIDES}"
sf org list | grep "${SCRATCH_ALIAS}"
environment:
SCRATCH_ALIAS: << parameters.scratch_alias >>
SCRATCH_CONFIG: << parameters.scratch_config >>
SCRATCH_OVERRIDES: << parameters.overrides >>
name: Create << parameters.scratch_alias >> Salesforce scratch org
scratch_delete:
description: |
"Delete a scratch Salesforce Org."
parameters:
scratch_alias:
default: ""
description: The name of the scratch Org, can either be the alias or target username.
type: string
steps:
- run:
command: |
#! /bin/bash
sf org delete scratch --no-prompt --target-org "${SCRATCH_ALIAS}"
environment:
SCRATCH_ALIAS: << parameters.scratch_alias >>
name: Delete <<# parameters.scratch_alias >><< parameters.scratch_alias >> <</ parameters.scratch_alias >>Salesforce scratch org
scratch_open:
description: |
"Open a scratch Salesforce Org."
parameters:
scratch_alias:
default: ""
description: The name of the scratch Org, can either be the alias or target username.
type: string
steps:
- run:
command: |
#! /bin/bash
sf org open --target-org "${SCRATCH_ALIAS}"
environment:
SCRATCH_ALIAS: << parameters.scratch_alias >>
name: Open <<# parameters.scratch_alias >><< parameters.scratch_alias >> <</ parameters.scratch_alias >>Salesforce scratch org in browser
executors:
default:
description: |
This is a sample executor using Docker and Node. If you want to provide a custom environment in your orb, insert your image here. If you do not require an executor, you can simply delete this directory.
docker:
- image: cimg/node:<<parameters.tag>>
parameters:
tag:
default: lts
description: |
Pick a specific circleci/node image variant: https://hub.docker.com/r/cimg/node/tags
type: string
examples:
create_open_delete_scratch:
description: |
Create, open, and then delete a scratch org.
usage:
version: "2.1"
orbs:
sfdx: circleci/salesforce-sfdx@x.y
jobs:
create-open-delete:
executor: sfdx/default
steps:
- checkout
- sfdx/install
- sfdx/auth:
defaultusername: user@email.com
- sfdx/scratch_create:
scratch_alias: circleci
scratch_config: ./config/project-scratch-def.json
- sfdx/scratch_open:
scratch_alias: circleci
- sfdx/scratch_delete:
scratch_alias: circleci
workflows:
basic-test:
jobs:
- create-open-delete
install_and_authenticate:
description: |
Simple example showing how to install the Salesforce sf CLI with the default options and authenticate against it with JWT.
usage:
version: "2.1"
orbs:
sfdx: circleci/salesforce-sfdx@x.y
jobs:
install_authenticate:
executor: sfdx/default
steps:
- checkout
- sfdx/install
- sfdx/auth:
defaultusername: user@email.com
- run:
command: |
echo You now have access to the sf cli and may execute commands against it.
sf auth list
name: Run your SF commands here
workflows:
basic-test:
jobs:
- install_authenticate