Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update documentation #513

Closed
wants to merge 3 commits into from
Closed

Update documentation #513

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5443ca2
Make shell examples easier to copy
iinuwa Dec 28, 2020
1c5f53d
Explicitly document environment variables
iinuwa Dec 28, 2020
252afdb
Document generic script execution.
iinuwa Dec 28, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 87 additions & 40 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,10 @@ probably want [Dependabot][dependabot] itself.

## Setup and usage

* `rbenv install` (Install Ruby version from `.ruby-version`)
* `bundle install`
```shell
rbenv install # (Install Ruby version from ./.ruby-version)
bundle install
```

### Native helpers

Expand All @@ -20,10 +22,12 @@ To install the native helpers, export an environment variable that points to the
directory into which the helpers should be installed and add the relevant bins
to your PATH:

* `export DEPENDABOT_NATIVE_HELPERS_PATH="$(pwd)/native-helpers"`
* `mkdir -p $DEPENDABOT_NATIVE_HELPERS_PATH/{terraform,python,dep,go_modules,hex,composer,npm_and_yarn}`
* `export PATH="$PATH:$DEPENDABOT_NATIVE_HELPERS_PATH/terraform/bin:$DEPENDABOT_NATIVE_HELPERS_PATH/python/bin:$DEPENDABOT_NATIVE_HELPERS_PATH/go_modules/bin:$DEPENDABOT_NATIVE_HELPERS_PATH/dep/bin"`
* `export MIX_HOME="$DEPENDABOT_NATIVE_HELPERS_PATH/hex/mix"`
```shell
export DEPENDABOT_NATIVE_HELPERS_PATH="$(pwd)/native-helpers"
mkdir -p $DEPENDABOT_NATIVE_HELPERS_PATH/{terraform,python,dep,go_modules,hex,composer,npm_and_yarn}
export PATH="$PATH:$DEPENDABOT_NATIVE_HELPERS_PATH/terraform/bin:$DEPENDABOT_NATIVE_HELPERS_PATH/python/bin:$DEPENDABOT_NATIVE_HELPERS_PATH/go_modules/bin:$DEPENDABOT_NATIVE_HELPERS_PATH/dep/bin"
export MIX_HOME="$DEPENDABOT_NATIVE_HELPERS_PATH/hex/mix"
```

Copy the relevant helpers from the gem source to the new install location

Expand All @@ -49,60 +53,103 @@ Build the helpers you want to use (you'll also need the corresponding language i
| PHP | `$DEPENDABOT_NATIVE_HELPERS_PATH/composer/helpers/build $DEPENDABOT_NATIVE_HELPERS_PATH/composer` |
| JS | `$DEPENDABOT_NATIVE_HELPERS_PATH/npm_and_yarn/helpers/build $DEPENDABOT_NATIVE_HELPERS_PATH/npm_and_yarn` |

### Running `update-script.rb`
### Environment Variables

The update scripts are configured using environment variables. The available
variables are listed in the table below. (See
[./generic-update-script.rb][generic-script] for more context.)

Variable Name | Default | Notes
:------------ | :--------------- | :----
`DIRECTORY_PATH ` | `/` | Directory where the base dependency files are.
`PACKAGE_MANAGER` | `bundler` | Valid values: `bundler`, `cargo`, `composer`, `dep`, `docker`, `elm`, `go_modules`, `gradle`, `hex`, `maven`, `npm_and_yarn`, `nuget`, `pip` (includes pipenv), `submodules`, `terraform`
`PROJECT_PATH` | None. Required. | Path to repository. Usually in the format `<namespace>/<project>`.
`PULL_REQUEST_ASSIGNEE` | None. Optional. | User to assign to the created pull request.

There are other variables that you must pass to your container that will depend on the Git source you use:

**Github**

Variable | Default
:------- | :------
GITHUB_ACCESS_TOKEN | None. Required.

**Github Enterprise**

Variable | Default
:------- | :------
GITHUB_ENTERPRISE_ACCESS_TOKEN | None. Required.
GITHUB_ENTERPRISE_HOSTNAME | None. Required.

**Gitlab**

Variable | Default
:------- | :------
GITLAB_ACCESS_TOKEN | None. Required.
GITLAB_AUTO_MERGE | None. Optional.
GITLAB_HOSTNAME | `gitlab.com`
GITLAB_ASSIGNEE_ID | None. Deprecated. Use `PULL_REQUEST_ASSIGNEE` instead.

**Azure DevOps**

Variable | Default
:------- | :------
AZURE_ACCESS_TOKEN | None. Required.
AZURE_HOSTNAME | `dev.azure.com`

Also note that the `PROJECT_PATH` variable should be in the format: `organization/project/_git/package-name`.

* `bundle exec irb`
* Edit the variables at the top of the script you're using, or set the corresponding environment variables.
* Copy and paste the script into the Ruby session to see how Dependabot works.
### Running dependabot

There are a few ways of running the script:
* interactively with `./update-script.rb`,
* non-interactively with `./generic-update-script.rb`,
* and non-interactively using Docker.

#### Running `update-script.rb` (GitHub only)

1. `bundle exec irb`
2. Edit the variables at the top of the script you're using, or set the corresponding [environment variables](#environment-variables).
3. Copy and paste the script into the Ruby session to see how Dependabot works.

If you run into any trouble with the above please create an issue!

#### Running `generic-update-script.rb`

1. Configure your shell with the correct [environment variables](#environment-variables).
2. Execute the script with Bundler:
```shell
bundle exec ruby ./generic-update-script.rb
```
#### Running script with Docker

If you don't want to setup the machine where the script will be executed, you could run the script within
a `dependabot/dependabot-core` container.
In order to do that, you'll have to pull the image from Docker Hub and mount your working directory into the container.
You'll also have to set several environment variables to make the script work with your configuration,
as specified in the documentation.

You'll also have to set several [environment variables](#environment-variables) to make the script work with your configuration, as specified above.
(You can find how to pass environment variables to your container in [Docker run reference](https://docs.docker.com/engine/reference/run/#env-environment-variables).)


Steps:

1. Pull dependabot-core Docker image

```shell
$ docker pull dependabot/dependabot-core
```
```shell
$ docker pull dependabot/dependabot-core
```

2. Install dependencies

```shell
docker run -v "$(pwd):/home/dependabot/dependabot-script" -w /home/dependabot/dependabot-script dependabot/dependabot-core bundle install -j 3 --path vendor
```
```shell
docker run -v "$(pwd):/home/dependabot/dependabot-script" -w /home/dependabot/dependabot-script dependabot/dependabot-core bundle install -j 3 --path vendor
```

3. Run dependabot

```shell
docker run -v "$(pwd):/home/dependabot/dependabot-script" -w /home/dependabot/dependabot-script -e ENV_VARIABLE=value dependabot/dependabot-core bundle exec ruby ./generic-update-script.rb
```

You'll have to pass the right environment variables to make the script work with your configuration. You can find how to pass environment variables to your container in [Docker run reference](https://docs.docker.com/engine/reference/run/#env-environment-variables).

You'll have to set some mandatory variables like `PROJECT_PATH` and `PACKAGE_MANAGER` (see [script](https://github.com/dependabot/dependabot-script/blob/master/generic-update-script.rb) to know more).
There are other variables that you must pass to your container that will depend on the Git source you use:

* Github
* GITHUB_ACCESS_TOKEN
* Github Enterprise
* GITHUB_ENTERPRISE_HOSTNAME
* GITHUB_ENTERPRISE_ACCESS_TOKEN
* Gitlab
* GITLAB_HOSTNAME: default value `gitlab.com`
* GITLAB_ACCESS_TOKEN
* Azure DevOps
* AZURE_HOSTNAME: default value `dev.azure.com`
* AZURE_ACCESS_TOKEN
* PROJECT_PATH: `organization/project/_git/package-name`

```shell
docker run -v "$(pwd):/home/dependabot/dependabot-script" -w /home/dependabot/dependabot-script -e ENV_VARIABLE=value dependabot/dependabot-core bundle exec ruby ./generic-update-script.rb
```

If everything goes well you should be able to see something like:

Expand Down