README.md in match-0.3.0 vs README.md in match-0.4.0
- old
+ new
@@ -1,25 +1,25 @@
<h3 align="center">
- <a href="https://github.com/fastlane/fastlane">
- <img src="assets/fastlane.png" width="150" />
+ <a href="https://github.com/fastlane/fastlane/tree/master/fastlane">
+ <img src="../fastlane/assets/fastlane.png" width="150" />
<br />
fastlane
</a>
</h3>
<p align="center">
- <a href="https://github.com/fastlane/deliver">deliver</a> •
- <a href="https://github.com/fastlane/snapshot">snapshot</a> •
- <a href="https://github.com/fastlane/frameit">frameit</a> •
- <a href="https://github.com/fastlane/pem">pem</a> •
- <a href="https://github.com/fastlane/sigh">sigh</a> •
- <a href="https://github.com/fastlane/produce">produce</a> •
- <a href="https://github.com/fastlane/cert">cert</a> •
- <a href="https://github.com/fastlane/spaceship">spaceship</a> •
- <a href="https://github.com/fastlane/pilot">pilot</a> •
+ <a href="https://github.com/fastlane/fastlane/tree/master/deliver">deliver</a> •
+ <a href="https://github.com/fastlane/fastlane/tree/master/snapshot">snapshot</a> •
+ <a href="https://github.com/fastlane/fastlane/tree/master/frameit">frameit</a> •
+ <a href="https://github.com/fastlane/fastlane/tree/master/pem">pem</a> •
+ <a href="https://github.com/fastlane/fastlane/tree/master/sigh">sigh</a> •
+ <a href="https://github.com/fastlane/fastlane/tree/master/produce">produce</a> •
+ <a href="https://github.com/fastlane/fastlane/tree/master/cert">cert</a> •
+ <a href="https://github.com/fastlane/fastlane/tree/master/spaceship">spaceship</a> •
+ <a href="https://github.com/fastlane/fastlane/tree/master/pilot">pilot</a> •
<a href="https://github.com/fastlane/boarding">boarding</a> •
- <a href="https://github.com/fastlane/gym">gym</a> •
- <a href="https://github.com/fastlane/scan">scan</a> •
+ <a href="https://github.com/fastlane/fastlane/tree/master/gym">gym</a> •
+ <a href="https://github.com/fastlane/fastlane/tree/master/scan">scan</a> •
<b>match</b>
</p>
-------
<p align="center">
@@ -27,33 +27,35 @@
</p>
match
============
-[](https://github.com/fastlane/match/blob/master/LICENSE)
+[](https://twitter.com/FastlaneTools)
+[](https://github.com/fastlane/fastlane/blob/master/match/LICENSE)
[](http://rubygems.org/gems/match)
+[](https://circleci.com/gh/fastlane/fastlane)
###### Easily sync your certificates and profiles across your team using git
A new approach to iOS code signing: Share one code signing identity across your development team to simplify your codesigning setup and prevent code signing issues.
-------
<p align="center">
- <a href="#why-match">Why?</a> •
- <a href="#installation">Installation</a> •
- <a href="#usage">Usage</a> •
- <a href="#is-this-secure">Is this secure?</a> •
+ <a href="#why-match">Why?</a> •
+ <a href="#installation">Installation</a> •
+ <a href="#usage">Usage</a> •
+ <a href="#is-this-secure">Is this secure?</a> •
<a href="#need-help">Need help?</a>
</p>
-------
<h5 align="center"><code>match</code> is part of <a href="https://fastlane.tools">fastlane</a>: connect all deployment tools into one streamlined workflow.</h5>
## Why match?
-Before starting to use `match`, make sure to read the [codesigning.guide](https://codesigning.guide)
+Before starting to use `match`, make sure to read the [codesigning.guide](https://codesigning.guide)
> When deploying an app to the App Store, beta testing service or even installing it on a device, most development teams have separate code signing identities for every member. This results in dozens of profiles including a lot of duplicates.
> You have to manually renew and download the latest set of provisioning profiles every time you add a new device or a certificate expires. Additionally this requires spending a lot of time when setting up a new machine that will build your app.
@@ -79,13 +81,13 @@
:computer: | Setup codesigning on a new machine in under a minute
:dart: | Designed to work with apps with multiple targets and bundle identifiers
:lock: | You have full control over your files and Git repo, no third party service involved
:sparkles: | Provisioning profile will always match the correct certificate
:boom: | Easily reset your existing profiles and certificates if your current account has expired or invalid profiles
-:recycle: | Automatically renew your provisioning profiles to include all your devices using the `--force`
+:recycle: | Automatically renew your provisioning profiles to include all your devices using the `--force` option
:busts_in_silhouette: | Support for multiple Apple accounts and multiple teams
-:sparkles: | Tightly integrated with [fastlane](https://fastlane.tools) to work seamlessly with [gym](https://github.com/fastlane/gym) and other build tools
+:sparkles: | Tightly integrated with [fastlane](https://fastlane.tools) to work seamlessly with [gym](https://github.com/fastlane/fastlane/tree/master/gym) and other build tools
For more information about the concept, visit [codesigning.guide](https://codesigning.guide).
## Installation
@@ -113,18 +115,18 @@
<img src="assets/match_init.gif" width="550" />
You'll be asked to enter the URL to your Git repo. This can be either a `https://` or a `git` URL. `match init` won't read or modify your certificates or profiles.
-This will create a `Matchfile` in your current directory (or in your `./fastlane/` folder).
+This will create a `Matchfile` in your current directory (or in your `./fastlane/` folder).
Example content (for more advanced setups check out the [fastlane section](#fastlane)):
```ruby
-git_url "https://github.com/fastlane/certificates"
+git_url "https://github.com/fastlane/fastlane/tree/master/certificates"
-app_identifier "tools.fastlane.app"
+app_identifier "tools.fastlane.app"
username "user@fastlane.tools"
```
#### Important: Use one git repo per team
@@ -168,13 +170,25 @@
```
match appstore -a tools.fastlane.app
match appstore -a tools.fastlane.app.watchkitapp
```
+You can make this even easier using [fastlane](https://github.com/fastlane/fastlane/tree/master/fastlane) by creating a match lane like this:
+
+```
+lane :match do
+ match(app_identifier: "com.krausefx.app1", readonly: true)
+ match(app_identifier: "com.krausefx.app2", readonly: true)
+ match(app_identifier: "com.krausefx.app3", readonly: true)
+end
+```
+
+Then all your team has to do is `fastlane match` and keys, certs and profiles for all targets will be synced.
+
#### Passphrase
-When running `match` for the first time on a new machine, it will ask you for the passphrase for the Git repository. This is an additional layer of security: each of the files will be encrypted using `openssl`.Make sure to remember the password, as you'll need it when you run match on a different machine
+When running `match` for the first time on a new machine, it will ask you for the passphrase for the Git repository. This is an additional layer of security: each of the files will be encrypted using `openssl`. Make sure to remember the password, as you'll need it when you run match on a different machine.
To set the passphrase using an environment variable, use `MATCH_PASSWORD`.
#### New machine
@@ -182,11 +196,11 @@
```
match development
```
-You can also run `match` in a `readonly` mode to be sure it won't create any new certificates or profiles.
+You can also run `match` in a `readonly` mode to be sure it won't create any new certificates or profiles.
```
match development --readonly
```
@@ -221,25 +235,25 @@
Add `match` to your `Fastfile` to automatically fetch the latest code signing certificates with [fastlane](https://fastlane.tools).
```ruby
match(type: "appstore")
-match(git_url: "https://github.com/fastlane/certificates",
+match(git_url: "https://github.com/fastlane/fastlane/tree/master/certificates",
type: "development")
-match(git_url: "https://github.com/fastlane/certificates",
- type: "adhoc",
+match(git_url: "https://github.com/fastlane/fastlane/tree/master/certificates",
+ type: "adhoc",
app_identifier: "tools.fastlane.app")
# `match` should be called before building the app with `gym`
gym
...
```
##### Multiple Targets
-If you app has multiple targets (e.g. Today Widget or WatchOS Extension)
+If your app has multiple targets (e.g. Today Widget or WatchOS Extension)
```ruby
match(app_identifier: "tools.fastlane.app", type: "appstore")
match(app_identifier: "tools.fastlane.app.today_widget", type: "appstore")
```
@@ -252,11 +266,11 @@
Additionally it is recommended to disable the `Fix Issue` button using the [FixCode Xcode Plugin](https://github.com/neonichu/FixCode). The `Fix Issue` button can revoke your existing certificates, which will invalidate your provisioning profiles.
#### To build from the command line using [fastlane](https://fastlane.tools)
-`match` automatically pre-fills environment variables with the UUIDs of the correct provisioning profiles, ready to be used in your Xcode project.
+`match` automatically pre-fills environment variables with the UUIDs of the correct provisioning profiles, ready to be used in your Xcode project.
<img src="assets/UDIDPrint.png" width="700" />
Open your target settings, open the dropdown for `Provisioning Profile` and select `Other`:
@@ -266,17 +280,34 @@
e.g. `$(sigh_tools.fastlane.app_development)`
#### To build from Xcode manually
-This is useful when installing your application on your device using the Development profile.
+This is useful when installing your application on your device using the Development profile.
You can statically select the right provisioning profile in your Xcode project (the name will be `match Development tools.fastlane.app`).
+### Continuous Integration
+
+#### Repo access
+There is one tricky part of setting up a CI system to work with `match`, which is enabling the CI to access the repo. Usually you'd just add your CI's public ssh key as a deploy key to your `match` repo, but since your CI will already likely be using its public ssh key to access the codebase repo, [you won't be able to do that](https://help.github.com/articles/error-key-already-in-use/).
+
+Some repo hosts might allow you to use the same deploy key for different repos, but GitHub will not. If your host does, you don't need to worry about this, just add your CI's public ssh key as a deploy key for your `match` repo and scroll down to "_Encryption password_".
+
+There are a few ways around this:
+
+1. Create a new account on your repo host with read-only access to your `match` repo. Bitrise have a good description of this [here](http://devcenter.bitrise.io/docs/adding-projects-with-submodules).
+2. Some CIs allow you to upload your signing credientials manually, but obviously this means that you'll have to re-upload the profiles/keys/certs each time they change.
+
+Neither solution is pretty. It's one of those _trade-off_ things. Do you care more about **not** having an extra account sitting around, or do you care more about having the :sparkles: of auto-syncing of credentials.
+
+#### Encryption password
+Once you've decided which approach to take, all that's left to do is to set your encryption password as secret environment variable named `MATCH_PASSWORD`. Match will pick this up when it's run.
+
### Nuke
-If you never really cared about code signing and have a messy Apple Developer account with a lot of invalid, expired or Xcode managed profiles/certificates, you can use the `match nuke` command to revoke your certificates and provisioning profiles. Don't worry, apps that are already available in the App Store will still work. Builds distributed via TestFlight might be disabled after nuking your account, you'll have to re-upload a new build. After clearing your account you'll start from a clean state, and you can run `match` to generate your certificates and profiles again.
+If you never really cared about code signing and have a messy Apple Developer account with a lot of invalid, expired or Xcode managed profiles/certificates, you can use the `match nuke` command to revoke your certificates and provisioning profiles. Don't worry, apps that are already available in the App Store will still work. Builds distributed via TestFlight might be disabled after nuking your account, so you'll have to re-upload a new build. After clearing your account you'll start from a clean state, and you can run `match` to generate your certificates and profiles again.
To revoke all certificates and provisioning profiles for a specific environment:
```sh
match nuke development
@@ -308,25 +339,25 @@
## Is this secure?
Both your keys and provisioning profiles are encrypted using OpenSSL using a passphrase.
-Storing your private keys in a Git repo may sound off-putting at first. We did an in-depth analysis of potential security issues and came to the following conclusions:
+Storing your private keys in a Git repo may sound off-putting at first. We did an in-depth analysis of potential security issues and came to the following conclusions:
#### What could happen if someone stole a private key?
-If attackers would have your certificate and provisioning profile, they could codesign an application with the same bundle identifier.
+If attackers would have your certificate and provisioning profile, they could codesign an application with the same bundle identifier.
What's the worst that could happen for each of the profile types?
##### App Store Profiles
An App Store profile can't be used for anything as long as it's not re-signed by Apple. The only way to get an app resigned is to submit an app for review (which takes around 7 days). Attackers could only submit an app for review, if they also got access to your iTunes Connect credentials (which are not stored in git, but in your local keychain). Additionally you get an email notification every time a build gets uploaded to cancel the submission even before your app gets into the review stage.
##### Development and Ad Hoc Profiles
-In general those profiles are harmless as they can only be used to install a signed application on a small subset of devices. To add new devices, the attacker would also need your Apple Developer Portal credentials (which are not stored in git, but in your local keychain).
+In general those profiles are harmless as they can only be used to install a signed application on a small subset of devices. To add new devices, the attacker would also need your Apple Developer Portal credentials (which are not stored in git, but in your local keychain).
##### Enterprise Profiles
Attackers could use an In-House profile to distribute signed application to a potentially unlimited number of devices. All this would run under your company name and it could eventually lead to Apple revoking your In-House account. However it is very easy to revoke a certificate to remotely break the app on all devices.
@@ -336,31 +367,31 @@
- You have full control over the access list of your Git repo, no third party service involved
- Even if your certificates are leaked, they can't be used to cause any harm without your iTunes Connect login credentials
- `match` does not currently support In-House Enterprise profiles as they are harder to control
- If you use GitHub or Bitbucket we encourage enabling 2 factor authentication for all accounts that have access to the certificates repo
-- The complete source code of `match` is fully open source on [GitHub](https://github.com/fastlane/match)
+- The complete source code of `match` is fully open source on [GitHub](https://github.com/fastlane/fastlane/tree/master/match)
## [`fastlane`](https://fastlane.tools) Toolchain
- [`fastlane`](https://fastlane.tools): Connect all deployment tools into one streamlined workflow
-- [`deliver`](https://github.com/fastlane/deliver): Upload screenshots, metadata and your app to the App Store
-- [`snapshot`](https://github.com/fastlane/snapshot): Automate taking localized screenshots of your iOS app on every device
-- [`frameit`](https://github.com/fastlane/frameit): Quickly put your screenshots into the right device frames
-- [`pem`](https://github.com/fastlane/pem): Automatically generate and renew your push notification profiles
-- [`produce`](https://github.com/fastlane/produce): Create new iOS apps on iTunes Connect and Dev Portal using the command line
-- [`cert`](https://github.com/fastlane/cert): Automatically create and maintain iOS code signing certificates
-- [`spaceship`](https://github.com/fastlane/spaceship): Ruby library to access the Apple Dev Center and iTunes Connect
-- [`pilot`](https://github.com/fastlane/pilot): The best way to manage your TestFlight testers and builds from your terminal
-- [`boarding`](https://github.com/fastlane/boarding): The easiest way to invite your TestFlight beta testers
-- [`gym`](https://github.com/fastlane/gym): Building your iOS apps has never been easier
-- [`scan`](https://github.com/fastlane/scan): The easiest way to run tests of your iOS and Mac app
+- [`deliver`](https://github.com/fastlane/fastlane/tree/master/deliver): Upload screenshots, metadata and your app to the App Store
+- [`snapshot`](https://github.com/fastlane/fastlane/tree/master/snapshot): Automate taking localized screenshots of your iOS app on every device
+- [`frameit`](https://github.com/fastlane/fastlane/tree/master/frameit): Quickly put your screenshots into the right device frames
+- [`pem`](https://github.com/fastlane/fastlane/tree/master/pem): Automatically generate and renew your push notification profiles
+- [`produce`](https://github.com/fastlane/fastlane/tree/master/produce): Create new iOS apps on iTunes Connect and Dev Portal using the command line
+- [`cert`](https://github.com/fastlane/fastlane/tree/master/cert): Automatically create and maintain iOS code signing certificates
+- [`spaceship`](https://github.com/fastlane/fastlane/tree/master/spaceship): Ruby library to access the Apple Dev Center and iTunes Connect
+- [`pilot`](https://github.com/fastlane/fastlane/tree/master/pilot): The best way to manage your TestFlight testers and builds from your terminal
+- [`boarding`](https://github.com/fastlane/boarding): The easiest way to invite your TestFlight beta testers
+- [`gym`](https://github.com/fastlane/fastlane/tree/master/gym): Building your iOS apps has never been easier
+- [`scan`](https://github.com/fastlane/fastlane/tree/master/scan): The easiest way to run tests of your iOS and Mac app
# Need help?
Please submit an issue on GitHub and provide information about your setup
# Code of Conduct
-Help us keep `match` open and inclusive. Please read and follow our [Code of Conduct](https://github.com/fastlane/code-of-conduct).
+Help us keep `match` open and inclusive. Please read and follow our [Code of Conduct](https://github.com/fastlane/fastlane/blob/master/CODE_OF_CONDUCT.md).
# License
This project is licensed under the terms of the MIT license. See the LICENSE file.
> This project and all fastlane tools are in no way affiliated with Apple Inc. This project is open source under the MIT license, which means you have full access to the source code and can modify it to fit your own needs. All fastlane tools run on your own computer or server, so your credentials or other sensitive information will never leave your own computer. You are responsible for how you use fastlane tools.