The Dangerfile
#Writing your Dangerfile
The Danger JS DSL is fully typed via TypeScript. These definitions are shipped with the Danger module. If your text editor supports working with type definitions you will get inline-documentation and auto-completion after you import danger in your Dangerfile. Visual Studio Code will do this by default for you.
If you are using Babel in your project, your Dangerfile will use the same transpilation settings. If you’re using TypeScript + Jest it will work out of the box too, however, if you don’t, you should head over to the transpilation guide.
#Working on your Dangerfile
There are two ways to locally work on your Dangerfile. These both rely on using the GitHub API locally, so you may hit the GitHub API rate-limit or need to have authenticated request for private repos. In which case you can use an access token to do authenticated requests by exposing a token to Danger.
export DANGER_GITHUB_API_TOKEN='xxxx'
# or for BitBucket by username and password
export DANGER_BITBUCKETSERVER_HOST='xxxx' DANGER_BITBUCKETSERVER_USERNAME='yyyy' DANGER_BITBUCKETSERVER_PASSWORD='zzzz'
# or for BitBucket by username and personal access token
export DANGER_BITBUCKETSERVER_HOST='xxxx' DANGER_BITBUCKETSERVER_USERNAME='yyyy' DANGER_BITBUCKETSERVER_TOKEN='zzzz'
# or for BitBucket Cloud by username (from Account Settings page), password (App-password with Read Pull requests, and Read Account Permissions)
export DANGER_BITBUCKETCLOUD_USERNAME='xxxx'
export DANGER_BITBUCKETCLOUD_PASSWORD='yyyy'
# or for BitBucket Cloud by OAuth key, and OAuth secret
# You can get OAuth key from Settings > OAuth > Add consumer, put `https://bitbucket.org/site/oauth2/authorize` for `Callback URL`, and enable Read Pull requests, and Read Account Permissions.
export DANGER_BITBUCKETCLOUD_OAUTH_KEY='xxxx'
export DANGER_BITBUCKETCLOUD_OAUTH_SECRET='yyyy'
Then the danger CLI will use authenticated API calls, which don’t get this by API limits.
#Using danger pr
The command danger pr
expects an argument of a PR url, e.g.
yarn danger pr https://github.com/danger/danger-js/pull/100
.
This will use your local Dangerfile against the metadata of the linked PR. Danger will then output the results into your terminal, instead of inside the PR itself.
This will not post comments. It is for locally testing, see yarn danger pr --help
for more info.
#Using danger
and Faking being on a CI
If you create an appropriately scoped temporary api token for your GitHub account, this can be a good way to see if danger is suitable for you before integrating it into your CI system.
You can manually trigger danger against a pull request on the command line by setting the following environmental variables:
export DANGER_FAKE_CI="YEP"
export DANGER_TEST_REPO='username/reponame'
Then you can run against a local branch that is attached to a pull-request, by running the following:
git checkout branch-for-pr-1234
DANGER_TEST_PR='1234' yarn danger ci
Assuming that your local file-system matches up to that branch on GitHub, this will be a good approximation of how danger will work when you integrate it into your CI system. Note: this will leave a comment on the PR.
#Working with files
Over time, we’ve found it easier to create up-front arrays of files you are interested in - then you can work with these potential arrays of files. For example:
import { danger } from "danger"
const docs = danger.git.fileMatch("**/*.md")
const app = danger.git.fileMatch("src/**/*.ts")
const tests = danger.git.fileMatch("*/__tests__/*")
if (docs.edited) {
message("Thanks - We :heart: our [documentarians](http://www.writethedocs.org/)!")
}
if (app.modified && !tests.modified) {
warn("You have app changes without tests.")
}
#Utils
As the JavaScript library API is relatively limited, the Danger module includes utility functions for work which is
common to most Dangerfiles. These functions can be found in both utils
, and github.utils
for GitHub specific
functions. We’re interested at growing this carefully.
#Finding more info
The CHANGELOG for Danger is kept entirely end-user focused, so if there is an aspect of the Dangerfile that you do not know, or looks confusing and there is nothing in the documentation - check the CHANGELOG. This is where we write-up why a change happened, and how it can affect Danger users.
#Examples
If you’d like to work with some reference material, here are some examples in the wild.
JavaScript:
- Libraries - facebook/react-native, and facebook/react.
- Docs - bamlab/dev-standards
Some TypeScript examples:
- Apps - Artsy/Emission
- Libraries danger/danger-js, apollographql/apollo-client
Got improvements? Help improve this document via sending PRs.