finan-code-push 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +198 -686
  2. package/package.json +3 -3
package/README.md CHANGED
@@ -1,837 +1,349 @@
1
- # CodePush CLI
1
+ # Finan CodePush CLI
2
2
 
3
- The CodePush CLI is a Node.js application that allows users to interact with CodePush Server.
3
+ CLI tool for managing OTA (Over-The-Air) updates for React Native apps via Finan CodePush server.
4
4
 
5
5
  ## Installation
6
6
 
7
- To run the CodePush CLI, follow these steps:
8
-
9
- 1. Clone the CodePush Service repository.
10
- 1. Install the necessary dependencies by running `npm install`.
11
- 1. Build the CLI by running `npm run build`.
12
- 1. Install CLI globally by running `npm install -g`.
13
-
14
- ## Getting started
15
-
16
- 1. Create a [CodePush account](#account-creation) push using the CodePush CLI.
17
- 1. Register your app with CodePush, and optionally share it with other developers on your team.
18
- 1. CodePush-ify your app and point it at the deployment you wish to use.
19
- 1. Release an update for your app.
20
- 1. Check out the debug logs to ensure everything is working as expected.
21
-
22
- ## Usage
23
-
24
- After installing CodePush CLI globally, it will be available under `code-push-standalone`.
25
-
26
- ## Account Management
27
-
28
- Before you can begin releasing app updates, you need to create a CodePush account. You can do this by simply running the following command once you've installed the CLI:
29
-
30
- ```
31
- code-push-standalone register <optional: server-url>
7
+ ```bash
8
+ npm install -g finan-code-push
32
9
  ```
33
10
 
34
- This will launch a browser, asking you to authenticate with either your GitHub or Microsoft account. Once authenticated, it will create a CodePush account "linked" to your GitHub/MSA identity, and generate an access key you can copy/paste into the CLI in order to login.
11
+ ## Quick Start
35
12
 
36
- _Note: After registering, you are automatically logged-in with the CLI, so until you explicitly log out, you don't need to login again from the same machine._
13
+ ```bash
14
+ # 1. Login to server
15
+ finan-code-push login --accessKey YOUR_ACCESS_KEY
37
16
 
38
- If you have an existing account, you may also link your account to another identity provider (e.g. Microsoft, GitHub) by running:
17
+ # 2. Create an app
18
+ finan-code-push app add MyApp
39
19
 
40
- ```
41
- code-push-standalone link
20
+ # 3. Release an update
21
+ finan-code-push release-react MyApp ios -d Staging
42
22
  ```
43
23
 
44
- _Note: In order to link multiple accounts, the email address associated with each provider must match._
24
+ ## Authentication
45
25
 
46
- ### Authentication
26
+ ### Login with Access Key
47
27
 
48
- Most commands within the CodePush CLI require authentication, and therefore, before you can begin managing your account, you need to login using the GitHub or Microsoft account you used when registering. You can do this by running the following command:
49
-
50
- ```shell
51
- code-push-standalone login <optional: server-url>
28
+ ```bash
29
+ finan-code-push login --accessKey YOUR_ACCESS_KEY
52
30
  ```
53
31
 
54
- This will launch a browser, asking you to authenticate with either your GitHub or Microsoft account. This will generate an access key that you need to copy/paste into the CLI (it will prompt you for it). You are now successfully authenticated and can safely close your browser window.
32
+ Get your access key from the CodePush dashboard at https://cp.sobanhang.com
55
33
 
56
- If at any time you want to determine if you're already logged in, you can run the following command to display the e-mail address associated with your current authentication session, which identity providers your account is linked to (e.g. GitHub):
34
+ ### Check Current Session
57
35
 
58
- ```shell
59
- code-push-standalone whoami
36
+ ```bash
37
+ finan-code-push whoami
60
38
  ```
61
39
 
62
- When you login from the CLI, your access key is persisted to disk for the duration of your session so that you don't have to login every time you attempt to access your account. In order to end your session and delete this access key, simply run the following command:
40
+ ### Logout
63
41
 
64
- ```shell
65
- code-push-standalone logout
42
+ ```bash
43
+ finan-code-push logout
66
44
  ```
67
45
 
68
- If you forget to logout from a machine you'd prefer not to leave a running session on (e.g. your friend's laptop), you can use the following commands to list and remove any current login sessions.
69
-
70
- ```shell
71
- code-push-standalone session ls
72
- code-push-standalone session rm <machineName>
73
- ```
74
-
75
- ### Access Keys
76
-
77
- If you need to be able to authenticate against the CodePush service without launching a browser and/or without needing to use your GitHub and/or Microsoft credentials (e.g. in a CI environment), you can run the following command to create an "access key" (along with a name describing what it is for):
78
-
79
- ```shell
80
- code-push-standalone access-key add "VSTS Integration"
81
- ```
82
-
83
- By default, access keys expire in 60 days. You can specify a different expiry duration by using the `--ttl` option and passing in a [human readable duration string](https://github.com/jkroso/parse-duration#parsestr) (e.g. "2d" => 2 days, "1h 15 min" => 1 hour and 15 minutes). For security, the key will only be shown once on creation, so remember to save it somewhere if needed!
84
-
85
- After creating the new key, you can specify its value using the `--accessKey` flag of the `login` command, which allows you to perform "headless" authentication, as opposed to launching a browser.
86
-
87
- ```shell
88
- code-push-standalone login --accessKey <accessKey>
89
- ```
90
-
91
- When logging in via this method, the access key will not be automatically invalidated on logout, and can be used in future sessions until it is explicitly removed from the CodePush server or expires. However, it is still recommended that you log out once your session is complete, in order to remove your credentials from disk.
92
-
93
- Finally, if at any point you need to change a key's name and/or expiration date, you can use the following command:
94
-
95
- ```shell
96
- code-push-standalone access-key patch <accessKeyName> --name "new name" --ttl 10d
97
- ```
98
-
99
- _NOTE: When patching the TTL of an existing access key, its expiration date will be set relative to the current time, with no regard for its previous value._
100
-
101
46
  ## App Management
102
47
 
103
- Before you can deploy any updates, you need to register an app with the CodePush service using the following command:
48
+ ### Add a New App
104
49
 
105
- ```
106
- code-push-standalone app add <appName>
107
- ```
50
+ ```bash
51
+ finan-code-push app add <appName>
108
52
 
109
- If your app targets both iOS and Android, please _create separate apps for each platform_ with CodePush (see the note below for details). This way, you can manage and release updates to them separately, which in the long run, also tends to make things simpler. The naming convention that most folks use is to suffix the app name with `-iOS` and `-Android`. For example:
110
-
111
- ```
112
- code-push-standalone app add MyApp-Android
113
- code-push-standalone app add MyApp-iOS
53
+ # Example
54
+ finan-code-push app add MyApp
114
55
  ```
115
56
 
116
- _NOTE: Using the same app for iOS and Android may cause installation exceptions because the CodePush update package produced for iOS will have different content from the update produced for Android._
117
-
118
- All new apps automatically come with two deployments (`Staging` and `Production`) so that you can begin distributing updates to multiple channels without needing to do anything extra (see deployment instructions below). After you create an app, the CLI will output the deployment keys for the `Staging` and `Production` deployments, which you can begin using to configure your mobile clients with the [React Native](http://github.com/Microsoft/react-native-code-push) SDK.
119
-
120
- If you decide that you don't like the name you gave to an app, you can rename it at any time using the following command:
57
+ ### List All Apps
121
58
 
59
+ ```bash
60
+ finan-code-push app ls
122
61
  ```
123
- code-push-standalone app rename <appName> <newAppName>
124
- ```
125
-
126
- The app's name is only meant to be recognizable from the management side, and therefore, you can feel free to rename it as necessary. It won't actually impact the running app, since update queries are made via deployment keys.
127
62
 
128
- If at some point you no longer need an app, you can remove it from the server using the following command:
63
+ ### Remove an App
129
64
 
130
- ```
131
- code-push-standalone app rm <appName>
65
+ ```bash
66
+ finan-code-push app rm <appName>
132
67
  ```
133
68
 
134
- Do this with caution since any apps that have been configured to use it will obviously stop receiving updates.
69
+ ### Rename an App
135
70
 
136
- Finally, if you want to list all apps that you've registered with the CodePush server,
137
- you can run the following command:
138
-
139
- ```
140
- code-push-standalone app ls
71
+ ```bash
72
+ finan-code-push app rename <currentName> <newName>
141
73
  ```
142
74
 
143
- ### App Collaboration
75
+ ### Transfer App Ownership
144
76
 
145
- If you will be working with other developers on the same CodePush app, you can add them as collaborators using the following command:
146
-
147
- ```shell
148
- code-push-standalone collaborator add <appName> <collaboratorEmail>
77
+ ```bash
78
+ finan-code-push app transfer <appName> <email>
149
79
  ```
150
80
 
151
- _NOTE: This expects the developer to have already [registered](#account-creation) with CodePush using the specified e-mail address, so ensure that they have done that before attempting to share the app with them._
152
-
153
- Once added, all collaborators will immediately have the following permissions with regards to the newly shared app:
81
+ ## Deployment Management
154
82
 
155
- 1. View the app, its collaborators, [deployments](#deployment-management) and [release history](#viewing-release-history)
156
- 1. [Release](#releasing-updates) updates to any of the app's deployments
157
- 1. [Promote](#promoting-updates) an update between any of the app's deployments
158
- 1. [Rollback](#rolling-back-undesired-updates) any of the app's deployments
159
- 1. [Patch](#updating-existing-releases) any releases within any of the app's deployments
83
+ Each app has deployments (e.g., Staging, Production). By default, `Staging` and `Production` are created.
160
84
 
161
- Inversely, that means that an app collaborator cannot do any of the following:
85
+ ### List Deployments
162
86
 
163
- 1. Rename or delete the app
164
- 1. Transfer ownership of the app
165
- 1. Create, rename or delete new deployments within the app
166
- 1. Clear a deployment's release history
167
- 1. Add or remove collaborators from the app (\*)
87
+ ```bash
88
+ finan-code-push deployment ls <appName>
168
89
 
169
- _NOTE: A developer can remove him/herself as a collaborator from an app that was shared with them._
170
-
171
- Over time, if someone is no longer working on an app with you, you can remove them as a collaborator using the following command:
172
-
173
- ```shell
174
- code-push-standalone collaborator rm <appName> <collaboratorEmail>
90
+ # Example
91
+ finan-code-push deployment ls MyApp
175
92
  ```
176
93
 
177
- If at any time you want to list all collaborators that have been added to an app, you can simply run the following command:
178
-
179
- ```shell
180
- code-push-standalone collaborator ls <appName>
181
- ```
94
+ ### Add a Deployment
182
95
 
183
- Finally, if at some point, you (as the app owner) will no longer be working on the app, and you want to transfer it to another developer (or a client), you can run the following command:
96
+ ```bash
97
+ finan-code-push deployment add <appName> <deploymentName>
184
98
 
185
- ```shell
186
- code-push-standalone app transfer <appName> <newOwnerEmail>
99
+ # Example
100
+ finan-code-push deployment add MyApp Beta
187
101
  ```
188
102
 
189
- _NOTE: Just like with the `code-push-standalone collaborator add` command, this expects that the new owner has already registered with CodePush using the specified e-mail address._
190
-
191
- Once confirmed, the specified developer becomes the app's owner and immediately receives the permissions associated with that role. Besides the transfer of ownership, nothing else about the app is modified (e.g. deployments, release history, collaborators). This means that you will still be a collaborator of the app, and therefore, if you want to remove yourself, you simply need to run the `code-push-standalone collaborator rm` command after successfully transferring ownership.
192
-
193
- ### Deployment Management
194
-
195
- From the CodePush perspective, an app is simply a named grouping for one or more things called "deployments". While the app represents a conceptual "namespace" or "scope" for a platform-specific version of an app (e.g. the iOS port of Foo app), its deployments represent the actual target for releasing updates (for developers) and synchronizing updates (for end-users). Deployments allow you to have multiple "environments" for each app in-flight at any given time, and help model the reality that apps typically move from a dev's personal environment to a testing/QA/staging environment, before finally making their way into production.
196
-
197
- _NOTE: As you'll see below, the `release`, `promote` and `rollback` commands require both an app name and a deployment name is order to work, because it is the combination of the two that uniquely identifies a point of distribution (e.g. I want to release an update of my iOS app to my beta testers)._
198
-
199
- Whenever an app is registered with the CodePush service, it includes two deployments by default: `Staging` and `Production`. This allows you to immediately begin releasing updates to an internal environment, where you can thoroughly test each update before pushing them out to your end-users. This workflow is critical for ensuring your releases are ready for mass-consumption, and is a practice that has been established in the web for a long time.
200
-
201
- If having a staging and production version of your app is enough to meet your needs, then you don't need to do anything else. However, if you want an alpha, dev, etc. deployment, you can easily create them using the following command:
103
+ ### View Release History
202
104
 
203
- ```
204
- code-push-standalone deployment add <appName> <deploymentName>
205
- ```
105
+ ```bash
106
+ finan-code-push deployment history <appName> <deploymentName>
206
107
 
207
- If you want to re-use an existing deployment key, you can do this with:
208
-
209
- ```
210
- code-push-standalone deployment add <appName> <deploymentName> -k <existing-deployment-key>
108
+ # Example
109
+ finan-code-push deployment h MyApp Staging
211
110
  ```
212
111
 
213
- Just like with apps, you can remove and rename deployments as well, using the following commands respectively:
112
+ ### Clear Deployment History
214
113
 
215
- ```
216
- code-push-standalone deployment rm <appName> <deploymentName>
217
- code-push-standalone deployment rename <appName> <deploymentName> <newDeploymentName>
114
+ ```bash
115
+ finan-code-push deployment clear <appName> <deploymentName>
218
116
  ```
219
117
 
220
- If at any time you'd like to view the list of deployments that a specific app includes, you can simply run the following command:
118
+ ### Remove a Deployment
221
119
 
120
+ ```bash
121
+ finan-code-push deployment rm <appName> <deploymentName>
222
122
  ```
223
- code-push-standalone deployment ls <appName> [--displayKeys|-k]
224
- ```
225
-
226
- This will display not only the list of deployments, but also the update metadata (e.g. mandatory, description) and installation metrics for their latest release:
227
-
228
- ![Deployment list](https://cloud.githubusercontent.com/assets/116461/12526883/7730991c-c127-11e5-9196-98e9ceec758f.png)
229
-
230
- _NOTE: Due to their infrequent use and needed screen real estate, deployment keys aren't displayed by default. If you need to view them, simply make sure to pass the `-k` flag to the `deployment ls` command._
231
-
232
- The install metrics have the following meaning:
233
-
234
- - **Active** - The number of successful installs that are currently running this release (i.e. if the user opened your app, they would see/run this version). This number will increase and decrease as end-users upgrade to and away from this release, respectively. This metric shows both the total of active users, as well as what percentage of your overall audience that represents. This makes it easy to determine the distribution of updates that your users are currently running, as well as answer questions such as "How many of my users have received my latest update?".
235
-
236
- - **Total** - The total number of successful installations that this update has received overall. This number only ever increases as new users/devices install it, and therefore, this is always a superset of the total active count. An update is considered successful once `notifyApplicationReady` (or `sync`) is called after it was installed. Between the moment that an update is downloaded, and it is marked as being successful, it will be reported as a "pending" update (see below for details).
237
-
238
- - **Pending** - The number of times this release has been downloaded, but not yet installed (i.e. the app was restarted to apply the changes). Therefore, this metric increases as updates are downloaded, and decreases as those corresponding downloaded updates are installed. This metric primarily applies to updates that aren't configured to install immediately, and helps provide the broader picture of release adoption for apps that rely on app resume and/or restart to apply an update (e.g. I want to rollback an update and I'm curious if anyone has downloaded it yet). If you've configured updates to install immediately, and are still seeing pending updates being reported, then it's likely that you're not calling `notifyApplicationReady` (or `sync`) on app start, which is the method that initiates sending install reports and marks installed updates as being considered successful.
239
-
240
- - **Rollbacks** - The number of times that this release has been automatically rolled back on the client. Ideally this number should be zero, and in that case, this metric isn't even shown. However, if you released an update that includes a crash as part of the installation process, the CodePush plugin will roll the end-user back to the previous release, and report that issue back to the server. This allows your end-users to remain unblocked in the event of broken releases, and by being able to see this telemetry in the CLI, you can identify erroneous releases and respond to them by [rolling it back](#rolling-back-undesired-updates) on the server.
241
-
242
- - **Rollout** - Indicates the percentage of users that are eligible to receive this update. This property will only be displayed for releases that represent an "active" rollout, and therefore, have a rollout percentage that is less than 100%. Additionally, since a deployment can only have one active rollout at any given time, this label would only be present on the latest release within a deployment.
243
-
244
- - **Disabled** - Indicates whether the release has been marked as disabled or not, and therefore, is downloadable by end users. This property will only be displayed for releases that are actually disabled.
245
-
246
- When the metrics cell reports `No installs recorded`, that indicates that the server hasn't seen any activity for this release. This could either be because it precluded the plugin versions that included telemetry support, or no end-users have synchronized with the CodePush server yet. As soon as an install happens, you will begin to see metrics populate in the CLI for the release.
247
123
 
248
124
  ## Releasing Updates
249
125
 
250
- Once your app has been configured to query for updates against the CodePush server, you can begin releasing updates to it. In order to provide both simplicity and flexibility, the CodePush CLI includes two different commands for releasing updates:
251
-
252
- 1. [General](#releasing-updates-general) - Releases an update to the CodePush server that was generated by an external tool or build script (e.g. a Gulp task, the `react-native bundle` command). This provides the most flexibility in terms of fitting into existing workflows, since it strictly deals with CodePush-specific step, and leaves the app-specific compilation process to you.
253
-
254
- 2. [React Native](#releasing-updates-react-native) - Performs the same functionality as the general release command, but also handles the task of generating the updated app contents for you (JS bundle and assets), instead of requiring you to run both `react-native bundle` and then `code-push-standalone release`.
126
+ ### Release React Native App (Recommended)
255
127
 
256
- Which of these commands you should use is mostly a matter of requirements and/or preference. However, we generally recommend using the platform-specific command to start (since it greatly simplifies the experience), and then leverage the general-purpose `release` command if/when greater control is needed.
128
+ Automatically bundles and releases your React Native app:
257
129
 
258
- ### Releasing Updates (General)
259
-
260
- ```
261
- code-push-standalone release <appName> <updateContents> <targetBinaryVersion>
262
- [--deploymentName <deploymentName>]
263
- [--description <description>]
264
- [--disabled <disabled>]
265
- [--mandatory]
266
- [--noDuplicateReleaseError]
267
- [--rollout <rolloutPercentage>]
130
+ ```bash
131
+ finan-code-push release-react <appName> <platform> [options]
268
132
  ```
269
133
 
270
- #### App name parameter
271
-
272
- This specifies the name of the CodePush app that this update is being released for. This value corresponds to the friendly name that you specified when originally calling `code-push-standalone app add` (e.g. "MyApp-Android"). If you need to look it up, you can run the `code-push-standalone app ls` command to see your list of apps.
273
-
274
- #### Update contents parameter
275
-
276
- This specifies the location of the updated app code and assets you want to release. You can provide either a single file (e.g. a JS bundle for a React Native app), or a path to a directory. Note that you don't need to ZIP up multiple files or directories in order to deploy those changes, since the CLI will automatically ZIP them for you.
277
-
278
- It's important that the path you specify refers to the platform-specific, prepared/bundled version of your app. The following table outlines which command you should run before releasing, as well as the location you can subsequently refer to using the `updateContents` parameter:
279
-
280
- | Platform | Prepare command | Package path (relative to project root) |
281
- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
282
- | React Native wo/assets (Android) | `react-native bundle --platform android --entry-file <entryFile> --bundle-output <bundleOutput> --dev false` | Value of the `--bundle-output` option |
283
- | React Native w/assets (Android) | `react-native bundle --platform android --entry-file <entryFile> --bundle-output <releaseFolder>/<bundleOutput> --assets-dest <releaseFolder> --dev false` | Value of the `--assets-dest` option, which should represent a newly created directory that includes your assets and JS bundle |
284
- | React Native wo/assets (iOS) | `react-native bundle --platform ios --entry-file <entryFile> --bundle-output <bundleOutput> --dev false` | Value of the `--bundle-output` option |
285
- | React Native w/assets (iOS) | `react-native bundle --platform ios --entry-file <entryFile> --bundle-output <releaseFolder>/<bundleOutput> --assets-dest <releaseFolder> --dev false` | Value of the `--assets-dest` option, which should represent a newly created directory that includes your assets and JS bundle |
286
-
287
- #### Target binary version parameter
288
-
289
- This specifies the store/binary version of the application you are releasing the update for, so that only users running that version will receive the update, while users running an older and/or newer version of the app binary will not. This is useful for the following reasons:
290
-
291
- 1. If a user is running an older binary version, it's possible that there are breaking changes in the CodePush update that wouldn't be compatible with what they're running.
292
-
293
- 2. If a user is running a newer binary version, then it's presumed that what they are running is newer (and potentially incompatible) with the CodePush update.
294
-
295
- If you ever want an update to target multiple versions of the app store binary, we also allow you to specify the parameter as a [semver range expression](https://github.com/npm/node-semver#advanced-range-syntax). That way, any client device running a version of the binary that satisfies the range expression (i.e. `semver.satisfies(version, range)` returns `true`) will get the update. Examples of valid semver range expressions are as follows:
296
-
297
- | Range Expression | Who gets the update |
298
- | ---------------- | -------------------------------------------------------------------------------------- |
299
- | `1.2.3` | Only devices running the specific binary app store version `1.2.3` of your app |
300
- | `*` | Any device configured to consume updates from your CodePush app |
301
- | `1.2.x` | Devices running major version 1, minor version 2 and any patch version of your app |
302
- | `1.2.3 - 1.2.7` | Devices running any binary version between `1.2.3` (inclusive) and `1.2.7` (inclusive) |
303
- | `>=1.2.3 <1.2.7` | Devices running any binary version between `1.2.3` (inclusive) and `1.2.7` (exclusive) |
304
- | `~1.2.3` | Equivalent to `>=1.2.3 <1.3.0` |
305
- | `^1.2.3` | Equivalent to `>=1.2.3 <2.0.0` |
306
-
307
- _NOTE: If your semver expression starts with a special shell character or operator such as `>`, `^`, or \*\*
308
- _, the command may not execute correctly if you do not wrap the value in quotes as the shell will not supply the right values to our CLI process. Therefore, it is best to wrap your `targetBinaryVersion` parameter in double quotes when calling the `release` command, e.g. `code-push-standalone release MyApp-iOS updateContents ">1.2.3"`.\*
309
-
310
- _NOTE: As defined in the semver spec, ranges only work for non pre-release versions: https://github.com/npm/node-semver#prerelease-tags. If you want to update a version with pre-release tags, then you need to write the exact version you want to update (`1.2.3-beta` for example)._
311
-
312
- The following table outlines the version value that CodePush expects your update's semver range to satisfy for each respective app type:
313
-
314
- | Platform | Source of app store version |
315
- | ---------------------- | ---------------------------------------------------------------------------- |
316
- | React Native (Android) | The `android.defaultConfig.versionName` property in your `build.gradle` file |
317
- | React Native (iOS) | The `CFBundleShortVersionString` key in the `Info.plist` file |
318
- | React Native (Windows) | The `<Identity Version>` key in the `Package.appxmanifest` file |
134
+ **Platforms:** `ios`, `android`, `windows`
319
135
 
320
- _NOTE: If the app store version in the metadata files are missing a patch version, e.g. `2.0`, it will be treated as having a patch version of `0`, i.e. `2.0 -> 2.0.0`._
136
+ **Examples:**
321
137
 
322
- #### Deployment name parameter
138
+ ```bash
139
+ # Release iOS to Staging
140
+ finan-code-push release-react MyApp ios
323
141
 
324
- This specifies which deployment you want to release the update to. This defaults to `Staging`, but when you're ready to deploy to `Production`, or one of your own custom deployments, just explicitly set this argument.
142
+ # Release Android to Production
143
+ finan-code-push release-react MyApp android -d Production
325
144
 
326
- _NOTE: The parameter can be set using either "--deploymentName" or "-d"._
145
+ # Release with description
146
+ finan-code-push release-react MyApp ios --des "Bug fixes and performance improvements"
327
147
 
328
- #### Description parameter
148
+ # Release as mandatory update
149
+ finan-code-push release-react MyApp ios -m
329
150
 
330
- This provides an optional "change log" for the deployment. The value is simply round tripped to the client so that when the update is detected, your app can choose to display it to the end-user (e.g. via a "What's new?" dialog). This string accepts control characters such as `\n` and `\t` so that you can include whitespace formatting within your descriptions for improved readability.
151
+ # Release with specific target version
152
+ finan-code-push release-react MyApp ios -t "1.2.0"
331
153
 
332
- _NOTE: This parameter can be set using either "--description" or "-des"_
154
+ # Release with Hermes enabled
155
+ finan-code-push release-react MyApp android --useHermes
333
156
 
334
- #### Disabled parameter
335
-
336
- This specifies whether an update should be downloadable by end users or not. If left unspecified, the update will not be disabled (i.e. users will download it the moment your app calls `sync`). This parameter can be valuable if you want to release an update that isn't immediately available, until you explicitly [patch it](#patching-releases) when you want end users to be able to download it (e.g. an announcement blog post went live).
337
-
338
- _NOTE: This parameter can be set using either "--disabled" or "-x"_
339
-
340
- #### Mandatory parameter
341
-
342
- This specifies whether the update should be considered mandatory or not (e.g. it includes a critical security fix). This attribute is simply round tripped to the client, who can then decide if and how they would like to enforce it.
343
-
344
- _NOTE: This parameter is simply a "flag", and therefore, its absence indicates that the release is optional, and its presence indicates that it's mandatory. You can provide a value to it (e.g. `--mandatory true`), however, simply specifying `--mandatory` is sufficient for marking a release as mandatory._
345
-
346
- The mandatory attribute is unique because the server will dynamically modify it as necessary in order to ensure that the semantics of your releases are maintained for your end-users. For example, imagine that you released the following three updates to your app:
347
-
348
- | Release | Mandatory? |
349
- | ------- | ---------- |
350
- | v1 | No |
351
- | v2 | Yes |
352
- | v3 | No |
353
-
354
- If an end-user is currently running `v1`, and they query the server for an update, it will respond with `v3` (since that is the latest), but it will dynamically convert the release to mandatory, since a mandatory update was released in between. This behavior is important since the code contained in `v3` is incremental to that included in `v2`, and therefore, whatever made `v2` mandatory, continues to make `v3` mandatory for anyone that didn't already acquire `v2`.
355
-
356
- If an end-user is currently running `v2`, and they query the server for an update, it will respond with `v3`, but leave the release as optional. This is because they already received the mandatory update, and therefore, there isn't a need to modify the policy of `v3`. This behavior is why we say that the server will "dynamically convert" the mandatory flag, because as far as the release goes, its mandatory attribute will always be stored using the value you specified when releasing it. It is only changed on-the-fly as necessary when responding to an update check from an end-user.
357
-
358
- If you never release an update that is marked as mandatory, then the above behavior doesn't apply to you, since the server will never change an optional release to mandatory unless there were intermingled mandatory updates as illustrated above. Additionally, if a release is marked as mandatory, it will never be converted to optional, since that wouldn't make any sense. The server will only change an optional release to mandatory in order to respect the semantics described above.
359
-
360
- _NOTE: This parameter can be set using either `--mandatory` or `-m`_
361
-
362
- #### No duplicate release error parameter
363
-
364
- This specifies that if the update is identical to the latest release on the deployment, the CLI should generate a warning instead of an error. This is useful for continuous integration scenarios where it is expected that small modifications may trigger releases where no production code has changed.
365
-
366
- #### Rollout parameter
367
-
368
- **IMPORTANT: In order for this parameter to actually take affect, your end users need to be running version `1.9.0-beta+` (for React Native) of the CodePush plugin. If you release an update that specifies a rollout property, no end user running an older version of React Native plugins will be eligible for the update. Therefore, until you have adopted the neccessary version of the platform-specific CodePush plugin (as previously mentioned), we would advise not setting a rollout value on your releases, since no one would end up receiving it.**
369
-
370
- This specifies the percentage of users (as an integer between `1` and `100`) that should be eligible to receive this update. It can be helpful if you want to "flight" new releases with a portion of your audience (e.g. 25%), and get feedback and/or watch for exceptions/crashes, before making it broadly available for everyone. If this parameter isn't set, it is set to `100%`, and therefore, you only need to set it if you want to actually limit how many users will receive it.
371
-
372
- When leveraging the rollout capability, there are a few additional considerations to keep in mind:
373
-
374
- 1. You cannot release a new update to a deployment whose latest release is an "active" rollout (i.e. its rollout property is non-null). The rollout needs to be "completed" (i.e. setting the `rollout` property to `100`) before you can release further updates to the deployment.
375
-
376
- 2. If you rollback a deployment whose latest release is an "active" rollout, the rollout value will be cleared, effectively "deactivating" the rollout behavior
377
-
378
- 3. Unlike the `mandatory` and `description` fields, when you promote a release from one deployment to another, it will not propagate the `rollout` property, and therefore, if you want the new release (in the target deployment) to have a rollout value, you need to explicitly set it when you call the `promote` command.
379
-
380
- _NOTE: This parameter can be set using either `--rollout` or `-r`_
381
-
382
- ### Releasing Updates (React Native)
383
-
384
- ```shell
385
- code-push-standalone release-react <appName> <platform>
386
- [--bundleName <bundleName>]
387
- [--deploymentName <deploymentName>]
388
- [--description <description>]
389
- [--development <development>]
390
- [--disabled <disabled>]
391
- [--entryFile <entryFile>]
392
- [--gradleFile <gradleFile>]
393
- [--mandatory]
394
- [--noDuplicateReleaseError]
395
- [--outputDir <outputDir>]
396
- [--plistFile <plistFile>]
397
- [--plistFilePrefix <plistFilePrefix>]
398
- [--sourcemapOutput <sourcemapOutput>]
399
- [--targetBinaryVersion <targetBinaryVersion>]
400
- [--rollout <rolloutPercentage>]
401
- [--useHermes <useHermes>]
402
- [--podFile <podFile>]
403
- [--extraHermesFlags <extraHermesFlags>]
404
- [--privateKeyPath <privateKeyPath>]
405
- [--xcodeProjectFile <xcodeProjectFile>]
406
- [--xcodeTargetName <xcodeTargetName>]
407
- [--buildConfigurationName <buildConfigurationName>]
157
+ # Release to 25% of users (gradual rollout)
158
+ finan-code-push release-react MyApp ios -r 25%
408
159
  ```
409
160
 
410
- The `release-react` command is a React Native-specific version of the "vanilla" [`release`](#releasing-app-updates) command, which supports all of the same parameters (e.g. `--mandatory`, `--description`), yet simplifies the process of releasing updates by performing the following additional behavior:
411
-
412
- 1. Running the `react-native bundle` command in order to generate the [update contents](#update-contents-parameter) (JS bundle and assets) that will be released to the CodePush server. It uses sensible defaults as much as possible (e.g. creating a non-dev build, assuming an iOS entry file is named `index.ios.js`), but also exposes the relevant `react-native bundle` parameters to enable flexibility (e.g. `--sourcemapOutput`).
413
-
414
- 2. Inferring the [`targetBinaryVersion`](#target-binary-version-parameter) of this release by using the version name that is specified in your project's `Info.plist` (for iOS) and `build.gradle` (for Android) files.
161
+ **Options:**
415
162
 
416
- To illustrate the difference that the `release-react` command can make, the following is an example of how you might generate and release an update for a React Native app using the "vanilla" `release` command:
163
+ | Option | Description | Default |
164
+ |--------|-------------|---------|
165
+ | `-d, --deploymentName` | Target deployment | `Staging` |
166
+ | `--des, --description` | Release description | - |
167
+ | `-m, --mandatory` | Mandatory update | `false` |
168
+ | `-x, --disabled` | Disabled initially | `false` |
169
+ | `-r, --rollout` | Rollout percentage | `100%` |
170
+ | `-t, --targetBinaryVersion` | Target app version | Auto-detect |
171
+ | `-h, --useHermes` | Enable Hermes | `false` |
172
+ | `-e, --entryFile` | Entry JS file | Auto-detect |
173
+ | `-b, --bundleName` | Bundle file name | Auto-detect |
174
+ | `-s, --sourcemapOutput` | Sourcemap output path | - |
175
+ | `-o, --outputDir` | Output directory | - |
176
+ | `-p, --plistFile` | Info.plist path (iOS) | Auto-detect |
177
+ | `-g, --gradleFile` | build.gradle path (Android) | Auto-detect |
417
178
 
418
- ```shell
419
- mkdir ./CodePush
420
-
421
- react-native bundle --platform ios \
422
- --entry-file index.ios.js \
423
- --bundle-output ./CodePush/main.jsbundle \
424
- --assets-dest ./CodePush \
425
- --dev false
426
-
427
- code-push-standalone release MyApp-iOS ./CodePush 1.0.0
428
- ```
179
+ ### Release Pre-built Bundle
429
180
 
430
- Achieving the equivalent behavior with the `release-react` command would simply require the following command, which is generally less error-prone:
181
+ If you have a pre-built bundle:
431
182
 
432
- ```shell
433
- code-push-standalone release-react MyApp-iOS ios
183
+ ```bash
184
+ finan-code-push release <appName> <bundlePath> <targetBinaryVersion> [options]
434
185
  ```
435
186
 
436
- #### App name parameter
187
+ **Examples:**
437
188
 
438
- This is the same parameter as the one described in the [above section](#app-name-parameter).
189
+ ```bash
190
+ # Release a folder
191
+ finan-code-push release MyApp ./build "1.0.0" -d Staging
439
192
 
440
- #### Platform parameter
193
+ # Release with wildcard version (targets all versions)
194
+ finan-code-push release MyApp ./bundle "*"
441
195
 
442
- This specifies which platform the current update is targeting, and can be either `android`, `ios` or `windows` (case-insensitive). This value is only used to determine how to properly bundle your update contents and isn't actually sent to the server.
443
-
444
- #### Deployment name parameter
445
-
446
- This is the same parameter as the one described in the [above section](#deployment-name-parameter).
447
-
448
- #### Description parameter
449
-
450
- This is the same parameter as the one described in the [above section](#description-parameter).
451
-
452
- #### Mandatory parameter
453
-
454
- This is the same parameter as the one described in the [above section](#mandatory-parameter).
455
-
456
- #### No duplicate release error parameter
457
-
458
- This is the same parameter as the one described in the [above section](#no-duplicate-release-error-parameter).
459
-
460
- #### Rollout parameter
461
-
462
- This is the same parameter as the one described in the [above section](#rollout-parameter). If left unspecified, the release will be made available to all users.
463
-
464
- #### Target binary version parameter
465
-
466
- This is the same parameter as the one described in the [above section](#target-binary-version-parameter). If left unspecified, this defaults to targeting the exact version specified in the app's `Info.plist` (for iOS) and `build.gradle` (for Android) files.
467
-
468
- #### Bundle name parameter
469
-
470
- This specifies the file name that should be used for the generated JS bundle. If left unspecified, the standard bundle name will be used for the specified platform: `main.jsbundle` (iOS), `index.android.bundle` (Android) and `index.windows.bundle` (Windows).
471
-
472
- _NOTE: This parameter can be set using either --bundleName or -b_
473
-
474
- #### Development parameter
475
-
476
- This specifies whether to generate a unminified, development JS bundle. If left unspecified, this defaults to `false` where warnings are disabled and the bundle is minified.
477
-
478
- _NOTE: This parameter can be set using either --development or --dev_
479
-
480
- #### Disabled parameter
481
-
482
- This is the same parameter as the one described in the [above section](#disabled-parameter).
483
-
484
- #### Entry file parameter
485
-
486
- This specifies the relative path to the app's root/entry JavaScript file. If left unspecified, this defaults to `index.ios.js` (for iOS), `index.android.js` (for Android) or `index.windows.bundle` (for Windows) if that file exists, or `index.js` otherwise.
487
-
488
- _NOTE: This parameter can be set using either --entryFile or -e_
489
-
490
- #### Gradle file parameter (Android only)
491
-
492
- This specifies the relative path to the `build.gradle` file that the CLI should use when attempting to auto-detect the target binary version for the release. This parameter is only meant for advanced scenarios, since the CLI will automatically be able to find your `build.grade` file in "standard" React Native projects. However, if your gradle file is located in an arbitrary location, that the CLI can't discover, then using this parameter allows you to continue releasing CodePush updates, without needing to explicitly set the `--targetBinaryVersion` parameter. Since `build.gradle` is a required file name, specifying the path to the containing folder or the full path to the file itself will both achieve the same effect.
493
-
494
- ```shell
495
- code-push-standalone release-react MyApp-Android android -p "./foo/bar/"
496
- code-push-standalone release-react MyApp-Android android -p "./foo/bar/build.gradle"
196
+ # Release with semver range
197
+ finan-code-push release MyApp ./bundle "~1.2.0"
497
198
  ```
498
199
 
499
- #### Plist file parameter (iOS only)
500
-
501
- This specifies the relative path to the `Info.plist` file that the CLI should use when attempting to auto-detect the target binary version for the release. This parameter is only meant for advanced scenarios, since the CLI will automatically be able to find your `Info.plist` file in "standard" React Native projects, and you can use the `--plistFilePrefix` parameter in order to support per-environment plist files (e.g. `STAGING-Info.plist`). However, if your plist is located in an arbitrary location, that the CLI can't discover, then using this parameter allows you to continue releasing CodePush updates, without needing to explicitly set the `--targetBinaryVersion` parameter.
502
-
503
- ```shell
504
- code-push-standalone release-react MyApp-iOS ios -p "./foo/bar/MyFile.plist"
505
- ```
200
+ ## Promoting & Rolling Back
506
201
 
507
- _NOTE: This parameter can be set using either --plistFile or -p_
202
+ ### Promote Release
508
203
 
509
- #### Plist file prefix parameter (iOS only)
204
+ Promote latest release from one deployment to another:
510
205
 
511
- This specifies the file name prefix of the `Info.plist` file that that CLI should use when attempting to auto-detect the target binary version for the release. This can be useful if you've created per-environment plist files (e.g. `DEV-Info.plist`, `STAGING-Info.plist`), and you want to be able to release CodePush updates without needing to explicitly set the `--targetBinaryVersion` parameter. By specifying a `--plistFilePrefx`, the CLI will look for a file named `<prefix>-Info.plist`, instead of simply `Info.plist` (which is the default behavior), in the following locations: `./ios` and `./ios/<appName>`. If your plist file isn't located in either of those directories (e.g. your app is a native iOS app with embedded RN views), or uses an entirely different file naming convention, then consider using the `--plistFile` parameter.
206
+ ```bash
207
+ finan-code-push promote <appName> <sourceDeployment> <destDeployment>
512
208
 
513
- ```shell
514
- # Auto-detect the target binary version of this release by looking up the
515
- # app version within the STAGING-Info.plist file in either the ./ios or ./ios/<APP> directories.
516
- code-push-standalone release-react MyApp-iOS ios --pre "STAGING"
517
-
518
- # Tell the CLI to use your dev plist (`DEV-Info.plist`).
519
- # Note that the hyphen separator can be explicitly stated.
520
- code-push-standalone release-react MyApp-iOS ios --pre "DEV-"
209
+ # Example: Promote from Staging to Production
210
+ finan-code-push promote MyApp Staging Production
521
211
  ```
522
212
 
523
- _NOTE: This parameter can be set using either --plistFilePrefix or --pre_
524
-
525
- #### Sourcemap output parameter
526
-
527
- This specifies the relative path to where the generated JS bundle's sourcemap file should be written. If left unspecified, sourcemaps will not be generated.
528
-
529
- _NOTE: This parameter can be set using either --sourcemapOutput or -s_
530
-
531
- #### Output directory parameter
532
-
533
- This specifies the relative path to where the assets, JS bundle and sourcemap files should be written. If left unspecified, the assets, JS bundle and sourcemap will be copied to the `/tmp/CodePush` folder.
534
-
535
- _NOTE: This parameter can be set using either --outputDir or -o_
536
-
537
- #### Use Hermes parameter
538
-
539
- This parameter enforces the use of the Hermes compiler. If not specified, the automatic checks will be performed, inspecting the `build.gradle` and `Podfile` for the Hermes flag.
540
-
541
- _NOTE: This parameter can be set using either --hermesEnabled or -h_
542
-
543
- #### Podfile parameter (iOS only)
544
-
545
- The Podfile path will be used for Hermes automatic check. Not used if `--useHermes` is specified.
546
-
547
- _NOTE: This parameter can be set using either --podfile or -pod_
548
-
549
- #### Extra hermes flags parameter
550
-
551
- Hermes flags which will be passed to Hermes compiler.
552
-
553
- _NOTE: This parameter can be set using either --extraHermesFlags or -hf_
554
-
555
- #### Private key path parameter
556
-
557
- Private key path which is used for code signing.
558
-
559
- _NOTE: This parameter can be set using either --privateKeyPath or -k_
560
-
561
- #### Xcode project file parameter
562
-
563
- Path to the Xcode project or project.pbxproj file.
564
-
565
- _NOTE: This parameter can be set using either --xcodeProjectFile or -xp_
566
-
567
- #### Xcode target name parameter
568
-
569
- Name of target (PBXNativeTarget) which specifies the binary version you want to target this release at (iOS only).
570
-
571
- _NOTE: This parameter can be set using either --xcodeTargetName or -xt_
572
-
573
- #### Build configuration name parameter
574
-
575
- Name of build configuration which specifies the binary version you want to target this release at. For example, 'Debug' or 'Release' (iOS only).
576
-
577
- _NOTE: This parameter can be set using either --buildConfigurationName or -c_
213
+ ### Rollback Release
578
214
 
579
- ## Debugging CodePush Integration
215
+ Rollback to the previous release:
580
216
 
581
- Once you've released an update, React Native plugin has been integrated into your app, it can be helpful to diagnose how the plugin is behaving, especially if you run into an issue and want to understand why. In order to debug the CodePush update discovery experience, you can run the following command in order to easily view the diagnostic logs produced by the CodePush plugin within your app:
217
+ ```bash
218
+ finan-code-push rollback <appName> <deploymentName>
582
219
 
583
- ```shell
584
- code-push-standalone debug <platform>
585
-
586
- # View all CodePush logs from a running
587
- # instace of the iOS simulator.
588
- code-push-standalone debug ios
589
-
590
- # View all CodePush logs from a running
591
- # Android emulator or attached device.
592
- code-push-standalone debug android
220
+ # Example
221
+ finan-code-push rollback MyApp Production
593
222
  ```
594
223
 
595
- <img width="500" src="https://cloud.githubusercontent.com/assets/116461/16246597/bd49a9ac-37ba-11e6-9aa4-a2d3b2821a90.png" />
224
+ ### Patch Release Metadata
596
225
 
597
- Under the covers, this command simply automates the usage of the iOS system logs and ADB logcat, but provides a platform-agnostic, filtered view of all logs coming from the CodePush plugin. This way, you don't need to learn and/or use another tool simply to be able to answer basic questions about how CodePush is behaving.
226
+ Update metadata of an existing release:
598
227
 
599
- _NOTE: The debug command supports both emulators and devices for Android, but currently only supports listening to logs from the iOS simulator. We hope to add device support soon._
228
+ ```bash
229
+ finan-code-push patch <appName> <deploymentName> [options]
600
230
 
601
- ## Patching Update Metadata
231
+ # Example: Make latest release mandatory
232
+ finan-code-push patch MyApp Production -m
602
233
 
603
- After releasing an update, there may be scenarios where you need to modify one or more of the metadata attributes associated with it (e.g. you forgot to mark a critical bug fix as mandatory, you want to increase the rollout percentage of an update). You can easily do this by running the following command:
604
-
605
- ```shell
606
- code-push-standalone patch <appName> <deploymentName>
607
- [--label <releaseLabel>]
608
- [--mandatory <isMandatory>]
609
- [--description <description>]
610
- [--rollout <rolloutPercentage>]
611
- [--disabled <isDisabled>]
612
- [--targetBinaryVersion <targetBinaryVersion>]
234
+ # Example: Disable a release
235
+ finan-code-push patch MyApp Staging -x
613
236
  ```
614
237
 
615
- _NOTE: This command doesn't allow modifying the actual update contents of a release. If you need to respond to a release that has been identified as being broken, you should use the [rollback](#rolling-back-updates) command to immediately roll it back, and then if necessary, release a new update with the approrpriate fix when it is available._
616
-
617
- Aside from the `appName` and `deploymentName`, all parameters are optional, and therefore, you can use this command to update just a single attribute or all of them at once. Calling the `patch` command without specifying any attribute flag will result in a no-op.
238
+ ## Collaborators
618
239
 
619
- ```shell
620
- # Mark the latest production release as mandatory
621
- code-push-standalone patch MyApp-iOS Production -m
240
+ ### Add Collaborator
622
241
 
623
- # Increase the rollout for v23 to 50%
624
- code-push-standalone patch MyApp-iOS Production -l v23 -rollout 50%
242
+ ```bash
243
+ finan-code-push collaborator add <appName> <email>
625
244
  ```
626
245
 
627
- ### Label parameter
628
-
629
- Indicates which release (e.g. `v23`) you want to update within the specified deployment. If ommitted, the requested changes will be applied to the latest release in the specified deployment. In order to look up the label for the release you want to update, you can run the `code-push-standalone deployment history` command and refer to the `Label` column.
630
-
631
- _NOTE: This parameter can be set using either `--label` or `-l`_
632
-
633
- ### Mandatory parameter
634
-
635
- This is the same parameter as the one described in the [above section](#mandatory-parameter), and simply allows you to update whether the release should be considered mandatory or not. Note that `--mandatory` and `--mandatory true` are equivalent, but the absence of this flag is not equivalent to `--mandatory false`. Therefore, if the parameter is ommitted, no change will be made to the value of the target release's mandatory property. You need to set this to `--mandatory false` to explicitly make a release optional.
636
-
637
- ### Description parameter
638
-
639
- This is the same parameter as the one described in the [above section](#description-parameter), and simply allows you to update the description associated with the release (e.g. you made a typo when releasing, or you forgot to add a description at all). If this parameter is ommitted, no change will be made to the value of the target release's description property.
640
-
641
- ### Disabled parameter
642
-
643
- This is the same parameter as the one described in the [above section](#disabled-parameter), and simply allows you to update whether the release should be disabled or not. Note that `--disabled` and `--disabled true` are equivalent, but the absence of this flag is not equivalent to `--disabled false`. Therefore, if the parameter is ommitted, no change will be made to the value of the target release's disabled property. You need to set this to `--disabled false` to explicitly make a release acquirable if it was previously disabled.
644
-
645
- ### Rollout parameter
646
-
647
- This is the same parameter as the one described in the [above section](#rollout-parameter), and simply allows you to increase the rollout percentage of the target release. This parameter can only be set to an integer whose value is greater than the current rollout value. Additionally, if you want to "complete" the rollout, and therefore, make the release available to everyone, you can simply set this parameter to `--rollout 100`. If this parameter is ommitted, no change will be made to the value of the target release's rollout parameter.
246
+ ### List Collaborators
648
247
 
649
- Additionally, as mentioned above, when you release an update without a rollout value, it is treated equivalently to setting the rollout to `100`. Therefore, if you released an update without a rollout, you cannot change the rollout property of it via the `patch` command since that would be considered lowering the rollout percentage.
650
-
651
- ### Target binary version parameter
652
-
653
- This is the same parameter as the one described in the [above section](#target-binary-version-parameter), and simply allows you to update the semver range that indicates which binary version(s) a release is compatible with. This can be useful if you made a mistake when originally releasing an update (e.g. you specified `1.0.0` but meant `1.1.0`) or you want to increase or decrease the version range that a release supports (e.g. you discovered that a release doesn't work with `1.1.2` after all). If this parameter is ommitted, no change will be made to the value of the target release's version property.
654
-
655
- ```shell
656
- # Add a "max binary version" to an existing release
657
- # by scoping its eligibility to users running >= 1.0.5
658
- code-push-standalone patch MyApp-iOS Staging -t "1.0.0 - 1.0.5"
248
+ ```bash
249
+ finan-code-push collaborator ls <appName>
659
250
  ```
660
251
 
661
- ## Promoting Updates
662
-
663
- Once you've tested an update against a specific deployment (e.g. `Staging`), and you want to promote it "downstream" (e.g. dev->staging, staging->production), you can simply use the following command to copy the release from one deployment to another:
252
+ ### Remove Collaborator
664
253
 
254
+ ```bash
255
+ finan-code-push collaborator rm <appName> <email>
665
256
  ```
666
- code-push-standalone promote <appName> <sourceDeploymentName> <destDeploymentName>
667
- [--description <description>]
668
- [--label <label>]
669
- [--disabled <disabled>]
670
- [--mandatory]
671
- [--noDuplicateReleaseError]
672
- [--rollout <rolloutPercentage>]
673
- [--targetBinaryVersion <targetBinaryVersion]
674
- ```
675
-
676
- The `promote` command will create a new release for the destination deployment, which includes the **exact code and metadata** (description, mandatory and target binary version) from the latest release of the source deployment. While you could use the `release` command to "manually" migrate an update from one environment to another, the `promote` command has the following benefits:
677
-
678
- 1. It's quicker, since you don't need to reassemble the release assets you want to publish or remember the description/app store version that are associated with the source deployment's release.
679
-
680
- 2. It's less error-prone, since the promote operation ensures that the exact thing that you already tested in the source deployment (e.g. `Staging`) will become active in the destination deployment (e.g. `Production`).
681
-
682
- We recommend that all users take advantage of the automatically created `Staging` and `Production` environments, and do all releases directly to `Staging`, and then perform a `promote` from `Staging` to `Production` after performing the appropriate testing.
683
-
684
- ### Description parameter
685
-
686
- This is the same parameter as the one described in the [above section](#description-parameter), and simply allows you to override the description that will be used for the promoted release. If unspecified, the new release will inherit the description from the release being promoted.
687
-
688
- ### Label parameter
689
-
690
- This optional parameter allows you to pick the specified label from the source deployment and promote it to the destination deployment. If unspecified, the latest release on the source deployment will be promoted.
691
-
692
- ### Disabled parameter
693
257
 
694
- This is the same parameter as the one described in the [above section](#disabled-parameter), and simply allows you to override the value of the disabled flag that will be used for the promoted release. If unspecified, the new release will inherit the disabled property from the release being promoted.
258
+ ## Access Keys
695
259
 
696
- ### Mandatory parameter
260
+ ### List Access Keys
697
261
 
698
- This is the same parameter as the one described in the [above section](#mandatory-parameter), and simply allows you to override the mandatory flag that will be used for the promoted release. If unspecified, the new release will inherit the mandatory property from the release being promoted.
699
-
700
- ### No duplicate release error parameter
701
-
702
- This is the same parameter as the one described in the [above section](#no-duplicate-release-error-parameter).
703
-
704
- ### Rollout parameter
705
-
706
- This is the same parameter as the one described in the [above section](#rollout-parameter), and allows you to specify whether the newly created release should only be made available to a portion of your users. Unlike the other release metadata parameters (e.g. `description`), the `rollout` of a release is not carried over/inherited as part of a promote, and therefore, you need to explicitly set this if you don't want the newly created release to be available to all of your users.
707
-
708
- ### Target binary version parameter
709
-
710
- This is the same parameter as the one described in the [above section](#target-binary-version-parameter), and simply allows you to override the target binary version that will be used for the promoted release. If unspecified, the new release will inherit the target binary version property from the release being promoted.
711
-
712
- ```shell
713
- # Promote the release to production and make it
714
- # available to all versions using that deployment
715
- code-push-standalone promote MyApp-iOS Staging Production -t "*"
262
+ ```bash
263
+ finan-code-push access-key ls
716
264
  ```
717
265
 
718
- ## Rolling Back Updates
266
+ ### Add Access Key
719
267
 
720
- A deployment's release history is immutable, so you cannot delete or remove an update once it has been released. However, if you release an update that is broken or contains unintended features, it is easy to roll it back using the `rollback` command:
721
-
722
- ```
723
- code-push-standalone rollback <appName> <deploymentName>
724
- code-push-standalone rollback MyApp-iOS Production
268
+ ```bash
269
+ finan-code-push access-key add --name "CI Server"
725
270
  ```
726
271
 
727
- This has the effect of creating a new release for the deployment that includes the **exact same code and metadata** as the version prior to the latest one. For example, imagine that you released the following updates to your app:
728
-
729
- | Release | Description | Mandatory |
730
- | ------- | ----------------- | --------- |
731
- | v1 | Initial release! | Yes |
732
- | v2 | Added new feature | No |
733
- | v3 | Bug fixes | Yes |
734
-
735
- If you ran the `rollback` command on that deployment, a new release (`v4`) would be created that included the contents of the `v2` release.
736
-
737
- | Release | Description | Mandatory |
738
- | --------------------------- | ----------------- | --------- |
739
- | v1 | Initial release! | Yes |
740
- | v2 | Added new feature | No |
741
- | v3 | Bug fixes | Yes |
742
- | v4 (Rollback from v3 to v2) | Added new feature | No |
743
-
744
- End-users that had already acquired `v3` would now be "moved back" to `v2` when the app performs an update check. Additionally, any users that were still running `v2`, and therefore, had never acquired `v3`, wouldn't receive an update since they are already running the latest release (this is why our update check uses the package hash in addition to the release label).
745
-
746
- If you would like to rollback a deployment to a release other than the previous (e.g. `v3` -> `v2`), you can specify the optional `--targetRelease` parameter:
272
+ ### Remove Access Key
747
273
 
748
- ```
749
- code-push-standalone rollback MyApp-iOS Production --targetRelease v34
274
+ ```bash
275
+ finan-code-push access-key rm <accessKeyName>
750
276
  ```
751
277
 
752
- _NOTE: The release produced by a rollback will be annotated in the output of the `deployment history` command to help identify them more easily._
278
+ ## Debugging
753
279
 
754
- ## Viewing Release History
280
+ View CodePush debug logs from a running app:
755
281
 
756
- You can view a history of the 50 most recent releases for a specific app deployment using the following command:
282
+ ```bash
283
+ finan-code-push debug <platform>
757
284
 
285
+ # Example
286
+ finan-code-push debug ios
758
287
  ```
759
- code-push-standalone deployment history <appName> <deploymentName>
760
- ```
761
-
762
- The history will display all attributes about each release (e.g. label, mandatory) as well as indicate if any releases were made due to a promotion or a rollback operation.
763
-
764
- ![Deployment History](https://cloud.githubusercontent.com/assets/696206/11605068/14e440d0-9aab-11e5-8837-69ab09bfb66c.PNG)
765
288
 
766
- Additionally, the history displays the install metrics for each release. You can view the details about how to interpret the metric data in the documentation for the `deployment ls` command above.
289
+ ## Configuration
767
290
 
768
- By default, the history doesn't display the author of each release, but if you are collaborating on an app with other developers, and want to view who released each update, you can pass the additional `--displayAuthor` (or `-a`) flag to the history command.
291
+ Access key is stored at `~/.code-push.config`
769
292
 
770
- _NOTE: The history command can also be run using the "h" alias_
293
+ ## Server Configuration
771
294
 
772
- ## Clearing Release History
295
+ - **Dashboard:** https://cp.sobanhang.com (web UI để quản lý apps, lấy access key)
296
+ - **API Server:** https://cp-api.sobanhang.com (CLI kết nối tới đây)
773
297
 
774
- You can clear the release history associated with a deployment using the following command:
298
+ To use a different server, set during login:
775
299
 
300
+ ```bash
301
+ finan-code-push login --accessKey YOUR_KEY
776
302
  ```
777
- code-push-standalone deployment clear <appName> <deploymentName>
778
- ```
779
-
780
- After running this command, client devices configured to receive updates using its associated deployment key will no longer receive the updates that have been cleared. This command is irreversible, and therefore should not be used in a production deployment.
781
-
782
- ## Code Signing for CodePush
783
303
 
784
- Code Signing ensures that updates deployed via CodePush are secure and verified. Follow these steps to set up Code Signing:
304
+ Or set environment variable:
785
305
 
786
- ### 1. Generate a Signing Key
787
-
788
- **Create private and public keys using OpenSSL:**
789
-
790
- ```shell
791
- # generate private RSA key and write it to private.pem file
792
- openssl genrsa -out private.pem
793
-
794
- # export public key from private.pem into public.pem
795
- openssl rsa -pubout -in private.pem -out public.pem
306
+ ```bash
307
+ export CODE_PUSH_SERVER_URL=https://your-server.com
796
308
  ```
797
309
 
798
- ### 2. Configure CodePush CLI
310
+ ## Requirements
799
311
 
800
- **Specify the path to your private key when releasing updates:**
312
+ - Node.js >= 18.0.0
313
+ - React Native project (for `release-react` command)
314
+ - Xcode (for iOS releases)
315
+ - Android SDK (for Android releases)
801
316
 
802
- ```shell
803
- code-push-standalone release-react <appName> <platform> --privateKeyPath private.pem
804
- ```
317
+ ## Common Workflows
805
318
 
806
- ### 3. Configure Your App
319
+ ### CI/CD Release
807
320
 
808
- #### iOS
809
-
810
- **Add the public key to your `Info.plist`:**
321
+ ```bash
322
+ # In your CI pipeline
323
+ finan-code-push login --accessKey $CODEPUSH_ACCESS_KEY
324
+ finan-code-push release-react MyApp ios -d Production -m --des "v1.2.3"
325
+ finan-code-push release-react MyApp android -d Production -m --des "v1.2.3"
326
+ ```
811
327
 
812
- - Open your `Info.plist` file.
813
- - Add a new entry:
328
+ ### Staged Rollout
814
329
 
815
- ```xml
816
- <key>CodePushPublicKey</key>
817
- <string>-----BEGIN PUBLIC KEY-----
818
- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
819
- -----END PUBLIC KEY-----</string>
820
- ```
330
+ ```bash
331
+ # Release to 10% of users
332
+ finan-code-push release-react MyApp ios -d Production -r 10%
821
333
 
822
- Replace the placeholder with the actual contents of your `public.pem` file.
334
+ # After monitoring, increase to 50%
335
+ finan-code-push patch MyApp Production -r 50%
823
336
 
824
- #### Android
337
+ # Finally, release to all users
338
+ finan-code-push patch MyApp Production -r 100%
339
+ ```
825
340
 
826
- **Add the public key to your `strings.xml`:**
341
+ ## Links
827
342
 
828
- - Open `res/values/strings.xml`.
829
- - Add the following entry:
343
+ - **CodePush Dashboard:** https://cp.sobanhang.com
344
+ - **API Server:** https://cp-api.sobanhang.com
345
+ - **Source Repository:** https://code.finan.one/finan-fe/code-push-server
830
346
 
831
- ```xml
832
- <string name="CodePushPublicKey">-----BEGIN PUBLIC KEY-----
833
- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
834
- -----END PUBLIC KEY-----</string>
835
- ```
347
+ ## License
836
348
 
837
- Replace the placeholder with the actual contents of your `public.pem` file.
349
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "finan-code-push",
3
- "version": "1.0.0",
3
+ "version": "1.0.2",
4
4
  "description": "CLI for Finan CodePush - Self-hosted OTA update service for React Native",
5
5
  "main": "./bin/script/cli.js",
6
6
  "scripts": {
@@ -27,9 +27,9 @@
27
27
  ],
28
28
  "repository": {
29
29
  "type": "git",
30
- "url": "git+https://github.com/nicejji/code-push-server.git"
30
+ "url": "https://code.finan.one/finan-fe/code-push-server.git"
31
31
  },
32
- "homepage": "https://github.com/nicejji/code-push-server#readme",
32
+ "homepage": "https://code.finan.one/finan-fe/code-push-server",
33
33
  "license": "MIT",
34
34
  "author": "Finan",
35
35
  "engines": {