From ce0a46fc506189149cd84bf5177c630bc39a75bf Mon Sep 17 00:00:00 2001 From: "Daniel (dB.) Doubrovkine" Date: Tue, 30 Dec 2025 11:06:37 -0500 Subject: [PATCH 1/4] Improve install script documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Clarify which workflow files are overwritten with --force flag - Add explicit example command for using --force option - Improve documentation readability and structure 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5e44865..310a858 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,13 @@ From your repository root: curl -fsSL https://raw.githubusercontent.com/numbata/danger-pr-comment/main/scripts/install-workflows.sh | bash ``` -Use `--force` to overwrite existing workflow files. To target a specific directory: +Use `--force` to overwrite existing workflow files `.github/workflows/danger.yml` and `.github/workflows/danger-comment.yml`: + +```bash +curl -fsSL https://raw.githubusercontent.com/numbata/danger-pr-comment/main/scripts/install-workflows.sh | bash -s -- --force +``` + +To target a specific directory: ```bash curl -fsSL https://raw.githubusercontent.com/numbata/danger-pr-comment/main/scripts/install-workflows.sh | bash -s -- --root /path/to/repo From 1b5199fc8d0f5b3df31906a92307b87cc6e38c18 Mon Sep 17 00:00:00 2001 From: "Daniel (dB.) Doubrovkine" Date: Tue, 30 Dec 2025 11:08:37 -0500 Subject: [PATCH 2/4] Update workflow references to use v0.1.0 tag MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Change workflow references from @main to @v0.1.0 for stability - Update both README.md examples and install script - Pin to specific version for reproducible installations 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- README.md | 4 ++-- scripts/install-workflows.sh | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 310a858..c0fee46 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ on: jobs: danger: - uses: numbata/danger-pr-comment/.github/workflows/danger-run.yml@main + uses: numbata/danger-pr-comment/.github/workflows/danger-run.yml@v0.1.0 secrets: inherit ``` @@ -68,7 +68,7 @@ permissions: jobs: comment: - uses: numbata/danger-pr-comment/.github/workflows/danger-comment.yml@main + uses: numbata/danger-pr-comment/.github/workflows/danger-comment.yml@v0.1.0 secrets: inherit ``` diff --git a/scripts/install-workflows.sh b/scripts/install-workflows.sh index 19d5ce9..7e6ee0b 100755 --- a/scripts/install-workflows.sh +++ b/scripts/install-workflows.sh @@ -69,7 +69,7 @@ on: jobs: danger: - uses: numbata/danger-pr-comment/.github/workflows/danger-run.yml@main + uses: numbata/danger-pr-comment/.github/workflows/danger-run.yml@v0.1.0 secrets: inherit EOF @@ -87,6 +87,6 @@ permissions: jobs: comment: - uses: numbata/danger-pr-comment/.github/workflows/danger-comment.yml@main + uses: numbata/danger-pr-comment/.github/workflows/danger-comment.yml@v0.1.0 secrets: inherit EOF From 66902a9793bd1b4425aaf53b5cc6f649b7f50964 Mon Sep 17 00:00:00 2001 From: "Daniel (dB.) Doubrovkine" Date: Tue, 30 Dec 2025 11:24:04 -0500 Subject: [PATCH 3/4] Improve README organization and add prerequisites section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add Prerequisites section with example Gemfile and Dangerfile setup - Reorganize Requirements into Implementation Details section - Move Dangerfile report examples into dedicated JSON Report Output section - Improve Inputs section structure with clearer subsection headers - Enhance documentation flow for easier onboarding 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- README.md | 63 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 41 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index c0fee46..f96bfb6 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,36 @@ Reusable GitHub Actions workflows for running Danger and posting a PR comment fr ## Usage +### Prerequisites + +Setup [Danger](https://github.com/danger/danger) in your repository. + +For example, the following `Gemfile` and `Dangerfile` install danger with the [danger-changelog plugin](https://github.com/dblock/danger-changelog). + +```ruby +group :development, :test do + gem 'danger' + gem 'danger-changelog' + gem 'danger-pr-comment', require: false +end +``` + +``` +# frozen_string_literal: true + +danger.import_dangerfile(gem: 'danger-pr-comment') + +changelog.check! +``` + +Run `bundle install` and `bundle exec danger` to make sure it works. + +```bash +bundle exec danger + +Could not find the type of CI for Danger to run on. +``` + ### Quick Install From your repository root: @@ -72,28 +102,13 @@ jobs: secrets: inherit ``` -## Requirements - -- Your repository must run `bundle exec danger` successfully. -- Your Dangerfile must write a JSON report to `ENV['DANGER_REPORT_PATH']` (for example, via a custom `at_exit` hook or a shared Dangerfile). -- The `Danger Comment` workflow requires explicit permissions. Reusable workflows cannot grant permissions to their callers. Required: `actions: read` (download artifacts from the Danger run), `issues: write` and `pull-requests: write` (create/update PR comments). +## Implementation Details -### Dangerfile report example - -If you want a shared Dangerfile, add the gem and import it: - -```ruby -# Gemfile -gem 'danger-pr-comment', require: false -``` +Using danger-pr-comment solves the problem of needing special permissions to post a PR comment from contributions from forks. This is implemented by producing a JSON report during the PR, and reading the report in a separate workflow. -```ruby -# Dangerfile -# Import danger-pr-comment for automatic danger report export -danger.import_dangerfile(gem: 'danger-pr-comment') -``` +### JSON Report Output -Or add this to your project's `Dangerfile` (or a shared Dangerfile) to emit the JSON report yourself: +Your Dangerfile must write a JSON report to `ENV['DANGER_REPORT_PATH']` (for example, via a custom `at_exit` hook or a shared Dangerfile). ```ruby # Dangerfile @@ -129,9 +144,13 @@ at_exit do end ``` -## Inputs +### Permissions + +The `Danger Comment` workflow requires explicit permissions. Reusable workflows cannot grant permissions to their callers. Required: `actions: read` (download artifacts from the Danger run), `issues: write` and `pull-requests: write` (create/update PR comments). + +### Inputs -`danger-run.yml` inputs: +#### `danger-run.yml` - `ruby-version`: Ruby version for `ruby/setup-ruby`. Leave empty to use `.ruby-version`/`.tool-versions`. - `bundler-cache`: Enable Bundler caching (default `true`). @@ -139,7 +158,7 @@ end - `report-artifact-name`: Artifact name for the report (default `danger-report`). - `report-file`: Report filename (default `danger-report.json`). -`danger-comment.yml` inputs: +#### `danger-comment.yml` - `report-artifact-name`: Artifact name to download (default `danger-report`). - `report-file`: Report filename inside the artifact (default `danger-report.json`). From 1409be49e36b2d6f3a8c82b519d19d6e495c5e35 Mon Sep 17 00:00:00 2001 From: "Daniel (dB.) Doubrovkine" Date: Tue, 30 Dec 2025 12:03:47 -0500 Subject: [PATCH 4/4] Add example workflow inputs to danger-run.yml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add example `with` block showing ruby-version and bundler-cache configuration - Update both README.md example and install script - Help users understand how to customize workflow inputs 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- CHANGELOG.md | 1 + README.md | 28 ++++++++++++++++++++++---- scripts/install-workflows.sh | 3 +++ spec/scripts/install_workflows_spec.rb | 4 ++-- 4 files changed, 30 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fbcfc21..7d3081f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - [#6](https://github.com/numbata/danger-pr-comment/pull/6): Setup danger workflows as an example - [@numbata](https://github.com/numbata). - [#1](https://github.com/numbata/danger-pr-comment/pull/1): Add comprehensive test suite with RSpec, Rubocop, and CI - [@dblock](https://github.com/dblock). +* [#4](https://github.com/numbata/danger-pr-comment/pull/4): Improve install script documentation - [@dblock](https://github.com/dblock). ### Fixed diff --git a/README.md b/README.md index f96bfb6..0d219d2 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,17 @@ Reusable GitHub Actions workflows for running Danger and posting a PR comment fr ## Table of Contents - [Usage](#usage) + - [Prerequisites](#prerequisites) - [Quick Install](#quick-install) - [Manual Setup](#manual-setup) -- [Requirements](#requirements) - - [Dangerfile report example](#dangerfile-report-example) -- [Inputs](#inputs) +- [Implementation Details](#implementation-details) + - [JSON Report Output](#json-report-output) + - [Shared Dangerfile](#shared-dangerfile) + - [Custom at_exit Hook](#custom-at_exit-hook) + - [Permissions](#permissions) + - [Inputs](#inputs) + - [danger-run.yml](#danger-runyml) + - [danger-comment.yml](#danger-commentyml) - [License](#license) ## Usage @@ -80,6 +86,9 @@ jobs: danger: uses: numbata/danger-pr-comment/.github/workflows/danger-run.yml@v0.1.0 secrets: inherit + with: + ruby-version: '3.4' + bundler-cache: true ``` Create `.github/workflows/danger-comment.yml` in your repository: @@ -108,7 +117,18 @@ Using danger-pr-comment solves the problem of needing special permissions to pos ### JSON Report Output -Your Dangerfile must write a JSON report to `ENV['DANGER_REPORT_PATH']` (for example, via a custom `at_exit` hook or a shared Dangerfile). +Your Dangerfile must write a JSON report to `ENV['DANGER_REPORT_PATH']`. + +#### Shared Dangerfile + +```ruby +# Import danger-pr-comment for automatic danger report export to JSON +danger.import_dangerfile(gem: 'danger-pr-comment') +``` + +See [Dangerfile](Dangerfile) for implementation details. + +#### Custom `at_exit` Hook ```ruby # Dangerfile diff --git a/scripts/install-workflows.sh b/scripts/install-workflows.sh index 7e6ee0b..583203d 100755 --- a/scripts/install-workflows.sh +++ b/scripts/install-workflows.sh @@ -71,6 +71,9 @@ jobs: danger: uses: numbata/danger-pr-comment/.github/workflows/danger-run.yml@v0.1.0 secrets: inherit + with: + ruby-version: '3.4' + bundler-cache: true EOF write_file "$workflows_dir/danger-comment.yml" <<'EOF' diff --git a/spec/scripts/install_workflows_spec.rb b/spec/scripts/install_workflows_spec.rb index f7b030b..417152f 100644 --- a/spec/scripts/install_workflows_spec.rb +++ b/spec/scripts/install_workflows_spec.rb @@ -66,7 +66,7 @@ def danger_comment_yml_path it 'uses the reusable workflow' do content = File.read(danger_yml_path) - expect(content).to include('uses: numbata/danger-pr-comment/.github/workflows/danger-run.yml@main') + expect(content).to include('uses: numbata/danger-pr-comment/.github/workflows/danger-run.yml@v0.1.0') end it 'inherits secrets' do @@ -94,7 +94,7 @@ def danger_comment_yml_path it 'uses the reusable workflow' do content = File.read(danger_comment_yml_path) - expect(content).to include('uses: numbata/danger-pr-comment/.github/workflows/danger-comment.yml@main') + expect(content).to include('uses: numbata/danger-pr-comment/.github/workflows/danger-comment.yml@v0.1.0') end it 'inherits secrets' do