diff --git a/doc/build/README.md b/doc/build/README.md
index d6ddfd0d4..792e86a61 100644
--- a/doc/build/README.md
+++ b/doc/build/README.md
@@ -1,5 +1,6 @@
 * [Overview](overview.md)
 * [Variables](env.md)
+* [Secrets](secrets.md)
 * [Cache](cache.md)
 * [Clone](clone.md)
 * [Build](build.md)
diff --git a/doc/build/env.md b/doc/build/env.md
index 9b1a55ceb..2970dc2c0 100644
--- a/doc/build/env.md
+++ b/doc/build/env.md
@@ -1,37 +1,43 @@
 # Variables
 
-The build environment has access to the following environment variables:
+Drone injects the following namespaced environment variables into every build:
 
-* `CI=true`
 * `DRONE=true`
 * `DRONE_REPO` - repository name for the current build
-* `DRONE_BUILD` - build number for the current build
 * `DRONE_BRANCH` - branch name for the current build
 * `DRONE_COMMIT` - git sha for the current build
 * `DRONE_DIR` - working directory for the current build
+* `DRONE_BUILD_NUMBER` - build number for the current build
+* `DRONE_PULL_REQUEST` - pull request number fo the current build
+* `DRONE_JOB_NUMBER` - job number for the current build
+
+Drone also injects `CI_` prefixed variables for compatibility with other systems:
+
+* `CI=true`
+* `CI_NAME=drone`
+* `CI_REPO` - repository name of the current build
+* `CI_BRANCH` - branch name for the current build
+* `CI_COMMIT` - git sha for the current build
+* `CI_BUILD_NUMBER` - build number for the current build
+* `CI_PULL_REQUEST` - pull request number fo the current build
+* `CI_JOB_NUMBER` - job number for the current build
+* `CI_BUILD_DIR` - working directory for the current build
+* `CI_BUILD_URL` - url for the current build
 
 
-## Private Variables
+## Injecting
 
-You may also store encrypted, private variables in the `.drone.yml` and inject at runtime. Private variables are encrypted using RSA encryption with OAEP (see [EncryptOAEP](http://golang.org/pkg/crypto/rsa/#EncryptOAEP)). You can generate encrypted strings from your repository settings screen.
+A subset of variables may be injected directly into the Yaml at runtime using the `$$` notation:
 
-Once you have an ecrypted string, you can add the encrypted variable to the `secure` section of the `.drone.yml`. These variables are decrypted and injected into the `.drone.yml` at runtime using the `$$` notation.
+* `$$COMMIT` git sha for the current build, `--short` format
+* `$$BRANCH` git branch for the current build
+* `$$REPO` repository full name (in `owner/name` format)
 
-An example `.drone.yml` expecting the `HEROKU_TOKEN` private variable:
+This is useful when you need to dynamically configure your plugin based on the current build. For example, we can alter an artifact name to include the branch:
 
-```yaml
-build:
-  image: golang
-  commands:
-    - go get
-    - go build
-    - go test
-
-deploy:
-  heroku:
-    app: pied_piper
-    token: $$HEROKU_TOKEN
-
-secure:
-  HEROKU_TOKEN: <encrypted string>
+```
+publish:
+  s3:
+    source: ./foo.tar.gz
+    target: ./foo-$$BRANCH.tar.gz
 ```
diff --git a/doc/build/secrets.md b/doc/build/secrets.md
new file mode 100644
index 000000000..560e5e11e
--- /dev/null
+++ b/doc/build/secrets.md
@@ -0,0 +1,57 @@
+# Secret Variables
+
+Drone allows you to store secret variables in an encrypted `.drone.sec` file in the root of your repository. This is useful when your build requires sensitive information that should not be stored in plaintext in your `.drone.yml` file.
+
+An example `.drone.sec` yaml file, prior to being encryped:
+
+```
+checksum: f63561783e550ccd21663d13eaf6a4d252d84147
+environment:
+  - HEROKU_TOKEN=pa$$word
+```
+
+To encrypt the above yaml file
+
+* navigate to your repository settings
+* click the section labeled secret variables
+* enter the plaintext yaml string in the textarea
+* click the encrypt button
+
+An encrypted string is returned to the browser. This string should be copied and pasted into a `.drone.sec` file in the root of your repository, alongside your `.drone.yml` file.
+
+## Environment
+
+The `environment` section of the `.drone.sec` file is a list of secret variables that get injected into your `.drone.yml` file at runtime using the `$$` notation. Secret variables are not injected as environment variables. Instead, we use a simple find and replace algorithm.
+
+An example `.drone.yml` expecting the `HEROKU_TOKEN` private variable:
+
+```yaml
+build:
+  image: golang
+  commands:
+    - go get
+    - go build
+    - go test
+
+deploy:
+  heroku:
+    app: pied_piper
+    token: $$HEROKU_TOKEN
+```
+
+## Pull Requests
+
+Secret variables are **not** injected into to the build section of the `.drone.yml` if your repository is **public** and the build is a **pull request**. This is for security purposes to prevent a malicious pull request from leaking your secrets.
+
+Please note that you may still want secrets available to plugins when building a pull request. This is possible if you include a checksum of the `.drone.yml` file in your `.drone.sec` file.
+
+## Checksum
+
+The `checksum` field in the `.drone.yml` is a sha of your `.drone.yml` file. It is optional, but highly recommended. The `checksum` is used to verify the integrity of your `.drone.yml` file. If the checksum does not match, secret variables are not injected into your Yaml.
+
+Generate a checksum on OSX or Linux:
+
+```
+$ shasum -a 256 .drone.yml
+f63561783e550ccd21663d13eaf6a4d252d84147  .drone.yml
+```