Get Started with Danger

So, you’re ready to get set up?

There are 5 steps involved in getting Danger running:

Installing Danger Locally.
Creating a Dangerfile and add a few simple rules.
Creating an account for Danger to use.
Setting up an access token for Danger with that account.
Setting up Danger to run on your CI.

#Including Danger

We recommend you install Danger via Swift Package Manager. Though you can use homebrew also. Using Swift PM means you safely lock your versions, making your tooling more reliable.

#Installation

#Swift PM

You’ll need to be using Xcode 10 or above. We need to create a package definition, so create a Package.swift in the root of your folder:

// swift-tools-version:4.2
import PackageDescription

let package = Package(
    name: "Eigen",
    dependencies: [
      .package(url: "https://github.com/danger/swift.git", from: "1.0.0")
    ],
    targets: [
        // This is just an arbitrary Swift file in our app, that has
        // no dependencies outside of Foundation, the dependencies section
        // ensures that the library for Danger gets build also.
        .target(name: "eigen", dependencies: ["Danger"], path: "Artsy", sources: ["Stringify.swift"]),
    ]
)

This is working around the system a little bit here, we create a SwiftPM build target that requires Danger (to ensure it gets compiled correctly) by adding Danger as a dependency. Next we create a build target that references a random Swift file in your app. This is so that libDanger will be created and because you have to have at least one build target in a Swift Package. Two birds, one bath.

You’ll have to find a file like this in your codebase, something that just imports Foundation is enough.

Run swift build to verify your setup.

From this point on you can use swift run danger-swift [cmd] to run Danger locked correctly to your project.

#Homebrew

This is good for quick experiments, and is macOS only. Install homebrew, then run brew install danger/tap/danger-swift.

Now you have a globally installed version of danger that’s available via danger-swift [cmd] on your computer.

This won’t be version locked, so you’ll always be using the latest version of Danger Swift (and Danger JS) which is kinda risky. We’re good with testing builds etc, but SemVer breaks in either project will probably occur and you won’t have a choice but to migrate at the same time or face failing builds.

#Creating a Dangerfile

Run [swift run] danger edit - this will create a default Dangerfile.swift and open an Xcode project

To get yourself started, add this to the Dangerfile.swift in the Xcode project:

let editedFiles = danger.git.modifiedFiles + danger.git.createdFiles
message("These files have changed: \(editedFiles.joined(separator: ", "))")

It will output the list of modified files for a PR, which we’ll test next. For a deeper understanding of how to write a Dangerfile, see the guide The Dangerfile.

#Testing locally

Let’s try to run your new Dangerfile.swift against an existing PR. If you’re interested in why, see this doc.

You can now test your current Dangerfile against an existing PR by running: [swift run] danger-swift pr [url_of_pr]. It will only leave messages in your terminal, not on the PR. This will run un-authenticated so it won’t work with private repos, if you need a public PR to test, try: [swift run] danger-swift pr https://github.com/danger/swift/pull/146.

#Creating a bot account for Danger to use

This is optional. Pragmatically, you want to do this though.

#GitHub

In order to get the most out of Danger, we recommend giving it the ability to post comments in your Pull Requests. This is a regular GitHub account, but depending on whether you are working on a private or public project, you will want to give different levels of access to this bot. You are allowed to have one bot per GitHub account.

To get started, open https://github.com in a private browser session.

#OSS Projects

Do not add the bot to your repo or to your organization.

#Closed Source Projects

Add the bot to your repo or to your organization. The bot requires permission level “Write” to be able to set a PR’s status. Note that you should not re-use this bot for OSS projects.

#Setting up an Access Token

Here’s the link, you should open this in the private session where you just created the new GitHub account. Again, the rights that you give to the token depend on the openness of your projects. You’ll want to save this token for later, when you add a DANGER_GITHUB_API_TOKEN to your CI.

#Tokens for OSS Projects

We recommend giving the token the smallest scope possible. This means just public_repo, this scope is still ideally too much but this account shouldn’t have any access to other repos or organizations - so malicious use of the token is scoped to making new repos on it, or writing comments on other OSS projects. Because the token can be quite easily be extracted from the CI environment, this minimizes the chance for bad actors to cause chaos with it.

#Tokens for Closed Source Projects

We recommend giving access to the whole repo scope, and its children.

#Enterprise GitHub

You can work with GitHub Enterprise by setting 2 environment variables:

DANGER_GITHUB_HOST to the host that GitHub is running on.
DANGER_GITHUB_API_BASE_URL to the host that the GitHub Enterprise API is reachable on.

For example:

DANGER_GITHUB_HOST=git.corp.evilcorp.com
DANGER_GITHUB_API_BASE_URL=https://git.corp.evilcorp.com/api/v3

#BitBucket Server

To use Danger Swift with BitBucket Server, you’ll need to create a new account for Danger to use, then set the following environment variables on your CI:

DANGER_BITBUCKETSERVER_HOST = The root URL for your server, e.g. https://bitbucket.mycompany.com.
DANGER_BITBUCKETSERVER_USERNAME = The username for the account used to comment.
DANGER_BITBUCKETSERVER_PASSWORD = The password for the account used to comment.

This account is then used to provide feedback on your PRs.

#Continuous Integration

Continuous Integration is the process of regularly running tests and generating metrics for a project. It is where you can ensure that the code you are submitting for review is passing on all of the tests. You commonly see this as green or red dots next to commits.

Danger is built to run as a part of this process, so you will need to have this set up as a pre-requisite.

#Setting up Danger to run on your CI

CI Setup

To make Danger run, add following lines to the appcenter-pre-build.sh file:

- cd $APPCENTER_SOURCE_DIRECTORY
- npm install -g danger
- swift build
- swift run danger-swift ci

Token Setup

Add the DANGER_GITHUB_API_TOKEN to your environment variables.

CI Setup

Install dependencies and add a danger step to your bitbucket-pipelines.yml. For improving the performance, you may need to cache node_modules.

image: node:10.15.0
pipelines:
pull-requests:
"**":
- step:
caches:
- node
script:
- export LANG="C.UTF-8"
- yarn install
- yarn danger ci
definitions:
caches:
node: node_modules

Token Setup

You can either add DANGER_BITBUCKETCLOUD_USERNAME, DANGER_BITBUCKETCLOUD_PASSWORD

or add `DANGER_BITBUCKETCLOUD_OAUTH_KEY`, `DANGER_BITBUCKETCLOUD_OAUTH_SECRET`

CI Setup

Install dependencies and add a danger step to your bitbucket-pipelines.yml. For improving the performance, you may need to cache node_modules.

image: node:10.15.0
pipelines:
pull-requests:
"**":
- step:
caches:
- node
script:
- export LANG="C.UTF-8"
- yarn install
- yarn danger ci
definitions:
caches:
node: node_modules

Token Setup

You can either add DANGER_BITBUCKETCLOUD_USERNAME, DANGER_BITBUCKETCLOUD_PASSWORD

or add `DANGER_BITBUCKETCLOUD_OAUTH_KEY`, `DANGER_BITBUCKETCLOUD_OAUTH_SECRET`

CI Setup

With BuildKite you run the server yourself, so you will want to run it as a part of your build process. It is common to have build steps, so we would recommend adding this to your script:

echo "--- Running Danger"
[swift run] danger-swift ci

Token Setup

GitHub

As this is self-hosted, you will need to add the API tokens to your build user's ENV. The alternative is to pass in the token as a prefix to the command DANGER_GITHUB_API_TOKEN="123" [swift run] danger-swift ci.

CI Setup

For setting up Circle CI, we recommend turning on "Only Build pull requests." in "Advanced Setting." Without this enabled, it is really tricky for Danger to know whether you are in a pull request or not, as the environment metadata isn't reliable.

Add some build steps to make Danger Swift work:

- run:
name: Installing Danger JS
command: npm install -g danger
- run:
name: Compiling Danger
command: swift build
- run:
name: Running Danger Swift
command: swift run danger-swift ci

We'd also recommend adding both .build and ~/.danger-swift to your build cache too.

Token Setup

There is no difference here for OSS vs Closed, add your DANGER_GITHUB_API_TOKEN to the Environment variable settings page.

CI Setup

You need to edit your .cirrus.yml to add a script like this:

danger_script:
- yarn danger ci

Token Setup

You need to add the DANGER_GITHUB_API_TOKEN environment variable, to do this, go to your repo's settings, by clicking the gear at https://cirrus-ci.com/github/[user]/[repo]. Generate the encrypted value, and add it to your env block.

Once you have added it, trigger a build.

CI Setup

To set up Danger on Codefresh, create a freestyle step in your Codefresh yaml configuration:

Danger:
title: Run Danger
image: node:latest
working_directory: ${{main_clone}}
entry_point: '/bin/bash'
cmd:
- '-ce'
- |
npm install -g yarn
yarn add danger --dev
yarn danger ci --failOnErrors
when:
steps:
- name: main_clone
on:
- success

The failOnErrors option is required in order to ensure that the step fails properly when Danger fails. If you don't want this behavior, you can remove this option.

Don't forget to add the DANGER_GITHUB_API_TOKEN variable to your pipeline settings so that Danger can properly post comments to your pull request.

CI Setup

To make Danger run, add a new step to the codeship-steps.yml file:

- type: parallel:
...
- name: danger
service: web
command: [swift run] danger-swift ci

If you're using Codeship Classic, add [swift run] danger-swift ci to your 'Test Commands'

Token Setup

You'll want to edit your codeship-services.yml file to include a reference to the Danger authentication token: DANGER_GITHUB_API_TOKEN.

project_name:
...
environment:
- DANGER_GITHUB_API_TOKEN=[my_token]

If you're using Codeship Classic, add DANGER_GITHUB_API_TOKEN to your 'Environment' settings.

Concourse CI Integration

https://concourse-ci.org/

CI Setup

With Concourse, you run the docker images yourself, so you will want to add [swift run] danger-swift ci within one of your build jobs.

build:
image: golang
commands:
- ...
- [swift run] danger-swift ci

Environment Variable Setup

As this is self-hosted, you will need to add the CONCOURSE environment variable export CONCOURSE=true to your build environment, as well as setting environment variables for PULL_REQUEST_ID and REPO_SLUG. Assuming you are using the github pull request resource https://github.com/jtarchie/github-pullrequest-resource the id of the PR can be accessed from git config --get pullrequest.id.

Token Setup

Once again as this is self-hosted, you will need to add DANGER_GITHUB_API_TOKEN environment variable to the build environment. The suggested method of storing the token is within the vault - https://concourse-ci.org/creds.html

CI Setup

You'll want to add danger to your existing Dockerfile.test (or whatever you have chosen as your sut Dockerfile.)

...

CMD ["swift", "run", "danger-swift", "ci"]

Token Setup

GitHub

Your DANGER_GITHUB_API_TOKEN will need to be exposed to the sut part of your docker-compose.yml. This looks similar to:

sut:
...
environment:
- DANGER_GITHUB_API_TOKEN=[my_token]

CI Setup

With Drone, you run the docker images yourself, so you will want to add [swift run] danger-swift ci at the end of your .drone.yml.

build:
image: golang
commands:
- ...
- [swift run] danger-swift ci

Token Setup

As this is self-hosted, you will need to add the DANGER_GITHUB_API_TOKEN to your build user's ENV. The alternative is to pass in the token as a prefix to the command DANGER_GITHUB_API_TOKEN="123" yarn danger ci.

CI Setup

There are two ways to use Danger with GitHub Actions. If you include Danger as a dependency, then you can call danger directly as another build-step after your tests:

name: CI
on: [pull_request]
jobs:
build:
runs-on: macos-latest

steps:
- uses: actions/checkout@master
- name: Build
run: swift build

- name: Test
run: swift test

- name: Danger
run: danger-swift ci
env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

If don't want to include the dependency then you can use Danger Swift via an action.

name: "Danger Swift"
on: [pull_request]

jobs:
build:
name: Danger JS
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v1
- name: Danger
uses: danger/swift@2.0.1
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Note it's likely the version number should change, but you get the point. This will run Danger self-encapsulated inside a GitHub action.

You can pass additional CLI to Danger via an action via the args:

- uses: danger/...
with:
args: "--dangerfile artsy/peril-settings/org/allPRs.ts"

This runs the file org/allPRs.ts from the repo artsy/peril-settings. This gives you the ability to have Danger acting on non-pull-requests via GitHub Actions.

Token Setup

You need to make sure that the secret "GITHUB_TOKEN" is enabled in your workspace. This is so that Danger can connect to GitHub.

- name: Danger JS
uses: danger/danger-js@9.1.6
env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

GitHub automatically creates a GITHUB_TOKEN secret to use in your workflow. You can use the GITHUB_TOKEN to authenticate in a workflow run. Using this token will post the danger comment as the github-actions app user.

Note: secrets.GITHUB_TOKEN will not be available for PRs from forks. This is a GitHub security constraint, if you have an OSS app, we recommend using a personal token like below.

Using Personal Tokens

If you need to post the danger comment as some particular user or for some other reason you need to use a personal token for danger then you can provide it in env as DANGER_GITHUB_API_TOKEN.

- name: Danger JS
uses: danger/danger-js@9.1.6
env: DANGER_GITHUB_API_TOKEN: ${{ secrets.DANGER_GITHUB_API_TOKEN }}

OSS Tokens

The security models for GitHub actions means that you cannot use secrets.GITHUB_TOKEN in PRs from forks. This cna be tricky with OSS contributions. In these cases, create a new GitHub account and set up your .yml like this:

- name: Set danger env
run: echo "DANGER_GITHUB_API_TOKEN=$(echo FIRST_HALF + SECOND_HALF)" >> $GITHUB_ENV

- name: Run Danger
run: yarn danger ci
env:
DANGER_GITHUB_API_TOKEN: ${{ env.DANGER_GITHUB_API_TOKEN }}

Advanced

If you understand the security ramifications, Danger JS can run on a pull_request_target workflow, instead of a pull_request. You should thoroughly read the docs first.

on:
pull_request_target:
types: [assigned, opened, synchronize, reopened]

jobs:
build:
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v1
- uses: actions/setup-node@v1
- run: yarn install

- run: yarn danger ci
env:
DANGER_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Note that when using Danger in this way, you will not have the file-system set up for the PR, so you cannot use fs to read a file (use danger.github.utils.fileContents instead) but the usual PR metadata and DSL will act the same.

CI Setup

Install dependencies and add a danger step to your screwdriver.yaml:

jobs:
danger:
requires: [~pr, ~commit]
steps:
- setup: yarn install
- danger: yarn danger ci
secrets:
- DANGER_GITHUB_API_TOKEN

Token Setup

Add the DANGER_GITHUB_API_TOKEN to your pipeline env as a build secret

CI Setup

Here's an example of the optimal travis setup, handling caching correctly:

os: osx
osx_image: xcode10.1

cache:
directories:
# General SwiftPM
# Danger Swift plugins, like Yams
- .build
- ~/.danger-swift

install:
# Grab the latest Danger JS from npm
- npm install -g danger
# Compile the Danger runtime
- swift build

script:
# Run the Dangerfile.swift
- swift run danger-swift ci
# Test my app...
- [your other commands]

Token Setup

You need to add the DANGER_GITHUB_API_TOKEN environment variable, to do this, go to your repo's settings, which should look like: https://travis-ci.org/[user]/[repo]/settings.

If you have an open source project, you should ensure "Display value in build log" enabled, so that PRs from forks work.

#Verify Installation

You should be able to verify that you have successfully integrated Danger by either re-building your CI or pushing your new commits.

#What now?

There are a few of places you can go from here. We’d recommending opening tabs on all these articles:

Then depending on the type of project you are working on, checking out Danger + iOS App. These should give you good overview of what is possible from here, then it’s really up to you to find how you can codify some aspects of your team’s culture.

Good luck!

Got improvements? Help improve this document via sending PRs.

Get Started with Danger

#Including Danger

#Installation

#Swift PM

#Homebrew

#Creating a Dangerfile

#Testing locally

#Creating a bot account for Danger to use

#GitHub

#OSS Projects

#Closed Source Projects

#Setting up an Access Token

#Tokens for OSS Projects

#Tokens for Closed Source Projects

#Enterprise GitHub

#BitBucket Server

#Continuous Integration

#Setting up Danger to run on your CI

CI Setup

Token Setup

CI Setup

Token Setup

or add DANGER_BITBUCKETCLOUD_OAUTH_KEY, DANGER_BITBUCKETCLOUD_OAUTH_SECRET

CI Setup

Token Setup

or add DANGER_BITBUCKETCLOUD_OAUTH_KEY, DANGER_BITBUCKETCLOUD_OAUTH_SECRET

CI Setup

Token Setup

CI Setup

Token Setup

GitHub

CI Setup

CI Setup

Token Setup

GitHub

CI Setup

Token Setup

CI Setup

Token Setup

CI Setup

CI Setup

Token Setup

CI Setup

Environment Variable Setup

Token Setup

CI Setup

Token Setup

GitHub

CI Setup

Token Setup

CI Setup

Token Setup

Using Personal Tokens

OSS Tokens

Advanced

CI Setup

GitHub

GitLab

BitBucket Server

Pipeline

Token Setup

GitHub

CI Setup

CI Setup

Token Setup

CI Setup

Token Setup

CI Setup

Token Setup

CI Setup

CI Setup

Token Setup

CI Setup

Token Setup

#Verify Installation

#What now?

or add `DANGER_BITBUCKETCLOUD_OAUTH_KEY`, `DANGER_BITBUCKETCLOUD_OAUTH_SECRET`

or add `DANGER_BITBUCKETCLOUD_OAUTH_KEY`, `DANGER_BITBUCKETCLOUD_OAUTH_SECRET`