Skip to content

Commit b74ba7f

Browse files
vaindclaude
vaind
and
claude
committed
docs: split documentation into dedicated README files
Create separate README files for updater and danger composite actions with complete documentation, examples, and migration guides. Update root README to link to the new documentation structure. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
1 parent 53e7bc2 commit b74ba7f

File tree

3 files changed

+184
-113
lines changed

3 files changed

+184
-113
lines changed

‎README.md‎

Lines changed: 12 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -1,124 +1,23 @@
1-
# Workflows
1+
# GitHub Workflows
22

3-
This repository contains reusable workflows and scripts to be used with GitHub Actions.
3+
This repository contains composite actions and scripts to be used with GitHub Actions.
44

5-
## Updater
5+
## Composite Actions
66

7-
Dependency updater - see [updater.yml](.github/workflows/updater.yml) - updates dependencies to the latest published git tag.
7+
### Updater
88

9-
### Example workflow definition
9+
Dependency updater - updates dependencies to the latest published git tag and creates/updates PRs.
1010

11-
```yaml
12-
name: Update Dependencies
13-
on:
14-
# Run every day.
15-
schedule:
16-
- cron: '0 3 * * *'
17-
# And on on every PR merge so we get the updated dependencies ASAP, and to make sure the changelog doesn't conflict.
18-
push:
19-
branches:
20-
- main
21-
jobs:
22-
# Update a git submodule
23-
cocoa:
24-
uses: getsentry/github-workflows/.github/workflows/updater.yml@v2
25-
with:
26-
path: modules/sentry-cocoa
27-
name: Cocoa SDK
28-
pattern: '^1\.' # Limit to major version '1'
29-
secrets:
30-
api-token: ${{ secrets.CI_DEPLOY_KEY }}
11+
**[📖 View full documentation →](updater/README.md)**
3112

32-
# Update a properties file
33-
cli:
34-
uses: getsentry/github-workflows/.github/workflows/updater.yml@v2
35-
with:
36-
path: sentry-cli.properties
37-
name: CLI
38-
secrets:
39-
api-token: ${{ secrets.CI_DEPLOY_KEY }}
13+
### Danger
4014

41-
# Update using a custom shell script, see updater/scripts/update-dependency.ps1 for the required arguments
42-
agp:
43-
uses: getsentry/github-workflows/.github/workflows/updater.yml@v2
44-
with:
45-
path: script.ps1
46-
name: Gradle Plugin
47-
secrets:
48-
api-token: ${{ secrets.CI_DEPLOY_KEY }}
15+
Runs DangerJS on Pull Requests with a pre-configured set of rules.
4916

50-
# Update a CMake FetchContent dependency with auto-detection (single dependency only)
51-
sentry-native:
52-
uses: getsentry/github-workflows/.github/workflows/updater.yml@v2
53-
with:
54-
path: vendor/sentry-native.cmake
55-
name: Sentry Native SDK
56-
secrets:
57-
api-token: ${{ secrets.CI_DEPLOY_KEY }}
17+
**[📖 View full documentation →](danger/README.md)**
5818

59-
# Update a CMake FetchContent dependency with explicit dependency name
60-
deps:
61-
uses: getsentry/github-workflows/.github/workflows/updater.yml@v2
62-
with:
63-
path: vendor/dependencies.cmake#googletest
64-
name: GoogleTest
65-
secrets:
66-
api-token: ${{ secrets.CI_DEPLOY_KEY }}
67-
```
19+
## Legacy Reusable Workflows (v2)
6820

69-
### Inputs
21+
> ⚠️ **Deprecated**: Reusable workflows have been converted to composite actions in v3. Please migrate to the composite actions above.
7022
71-
* `path`: Dependency path in the source repository. Supported formats:
72-
* Submodule path
73-
* Properties file (`.properties`)
74-
* Shell script (`.ps1`, `.sh`)
75-
* CMake file with FetchContent:
76-
* `path/to/file.cmake#DepName` - specify dependency name
77-
* `path/to/file.cmake` - auto-detection (single dependency only)
78-
* type: string
79-
* required: true
80-
* `name`: Name used in the PR title and the changelog entry.
81-
* type: string
82-
* required: true
83-
* `pattern`: RegEx pattern that will be matched against available versions when picking the latest one.
84-
* type: string
85-
* required: false
86-
* default: ''
87-
* `changelog-entry`: Whether to add a changelog entry for the update.
88-
* type: boolean
89-
* required: false
90-
* default: true
91-
* `changelog-section`: Section header to attach the changelog entry to.
92-
* type: string
93-
* required: false
94-
* default: Dependencies
95-
* `runs-on`: GitHub Actions virtual environment name to run the udpater job on.
96-
* type: string
97-
* required: false
98-
* default: ubuntu-latest
99-
* `pr-strategy`: How to handle PRs.
100-
Can be either of the following:
101-
* `create` (default) - create a new PR for new dependency versions as they are released - maintainers may merge or close older PRs manually
102-
* `update` - keep a single PR that gets updated with new dependency versions until merged - only the latest version update is available at any time
103-
104-
### Secrets
105-
106-
* `api-token`: GH authentication token to create PRs with & push.
107-
If you provide the usual `${{github.token}}`, no followup CI will run on the created PR.
108-
If you want CI to run on the PRs created by the Updater, you need to provide custom user-specific auth token.
109-
110-
## Danger
111-
112-
Runs DangerJS on Pull Reqeusts in your repository. This uses custom set of rules defined in [this dangerfile](danger/dangerfile.js).
113-
114-
```yaml
115-
name: Danger
116-
117-
on:
118-
pull_request:
119-
types: [opened, synchronize, reopened, edited, ready_for_review, labeled, unlabeled]
120-
121-
jobs:
122-
danger:
123-
uses: getsentry/github-workflows/.github/workflows/danger.yml@v2
124-
```
23+
For v2 migration guide and breaking changes, see [CHANGELOG.md](CHANGELOG.md#3.0.0).

‎danger/README.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Danger Composite Action
2+
3+
Runs DangerJS on Pull Requests in your repository. This uses custom set of rules defined in [dangerfile.js](dangerfile.js).
4+
5+
## Usage
6+
7+
```yaml
8+
name: Danger
9+
10+
on:
11+
pull_request:
12+
types: [opened, synchronize, reopened, edited, ready_for_review, labeled, unlabeled]
13+
14+
jobs:
15+
danger:
16+
runs-on: ubuntu-latest
17+
steps:
18+
- uses: getsentry/github-workflows/danger@v3
19+
```
20+
21+
## Inputs
22+
23+
* `api-token`: Token for the repo. Can be passed in using `${{ secrets.GITHUB_TOKEN }}`.
24+
* type: string
25+
* required: false
26+
* default: `${{ github.token }}`
27+
28+
## Outputs
29+
30+
* `outcome`: Whether the Danger run finished successfully. Possible values are `success`, `failure`, `cancelled`, or `skipped`.
31+
32+
## Migration from v2 Reusable Workflow
33+
34+
If you're migrating from the v2 reusable workflow, see the [changelog migration guide](../CHANGELOG.md#unreleased) for detailed examples.
35+
36+
Key changes:
37+
- Add `runs-on` to specify the runner
38+
- No need for explicit `actions/checkout` step (handled internally)
39+
- Optional `api-token` input (defaults to `github.token`)
40+
41+
## Rules
42+
43+
The Danger action runs the following checks:
44+
45+
- **Changelog validation**: Ensures PRs include appropriate changelog entries
46+
- **Action pinning**: Verifies GitHub Actions are pinned to specific commits for security
47+
- **Conventional commits**: Validates commit message format and PR title conventions
48+
- **Cross-repo links**: Checks for proper formatting of links in changelog entries
49+
50+
For detailed rule implementations, see [dangerfile.js](dangerfile.js).

‎updater/README.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# Updater Composite Action
2+
3+
Dependency updater - updates dependencies to the latest published git tag and creates/updates PRs.
4+
5+
## Usage
6+
7+
```yaml
8+
name: Update Dependencies
9+
on:
10+
# Run every day.
11+
schedule:
12+
- cron: '0 3 * * *'
13+
# And on every PR merge so we get the updated dependencies ASAP, and to make sure the changelog doesn't conflict.
14+
push:
15+
branches:
16+
- main
17+
18+
jobs:
19+
# Update a git submodule
20+
cocoa:
21+
runs-on: ubuntu-latest
22+
steps:
23+
- uses: getsentry/github-workflows/updater@v3
24+
with:
25+
path: modules/sentry-cocoa
26+
name: Cocoa SDK
27+
pattern: '^1\.' # Limit to major version '1'
28+
api-token: ${{ secrets.CI_DEPLOY_KEY }}
29+
30+
# Update a properties file
31+
cli:
32+
runs-on: ubuntu-latest
33+
steps:
34+
- uses: getsentry/github-workflows/updater@v3
35+
with:
36+
path: sentry-cli.properties
37+
name: CLI
38+
api-token: ${{ secrets.CI_DEPLOY_KEY }}
39+
40+
# Update using a custom shell script, see updater/scripts/update-dependency.ps1 for the required arguments
41+
agp:
42+
runs-on: ubuntu-latest
43+
steps:
44+
- uses: getsentry/github-workflows/updater@v3
45+
with:
46+
path: script.ps1
47+
name: Gradle Plugin
48+
api-token: ${{ secrets.CI_DEPLOY_KEY }}
49+
50+
# Update a CMake FetchContent dependency with auto-detection (single dependency only)
51+
sentry-native:
52+
runs-on: ubuntu-latest
53+
steps:
54+
- uses: getsentry/github-workflows/updater@v3
55+
with:
56+
path: vendor/sentry-native.cmake
57+
name: Sentry Native SDK
58+
api-token: ${{ secrets.CI_DEPLOY_KEY }}
59+
60+
# Update a CMake FetchContent dependency with explicit dependency name
61+
deps:
62+
runs-on: ubuntu-latest
63+
steps:
64+
- uses: getsentry/github-workflows/updater@v3
65+
with:
66+
path: vendor/dependencies.cmake#googletest
67+
name: GoogleTest
68+
api-token: ${{ secrets.CI_DEPLOY_KEY }}
69+
```
70+
71+
## Inputs
72+
73+
* `path`: Dependency path in the source repository. Supported formats:
74+
* Submodule path
75+
* Properties file (`.properties`)
76+
* Shell script (`.ps1`, `.sh`)
77+
* CMake file with FetchContent:
78+
* `path/to/file.cmake#DepName` - specify dependency name
79+
* `path/to/file.cmake` - auto-detection (single dependency only)
80+
* type: string
81+
* required: true
82+
* `name`: Name used in the PR title and the changelog entry.
83+
* type: string
84+
* required: true
85+
* `pattern`: RegEx pattern that will be matched against available versions when picking the latest one.
86+
* type: string
87+
* required: false
88+
* default: ''
89+
* `changelog-entry`: Whether to add a changelog entry for the update.
90+
* type: boolean
91+
* required: false
92+
* default: true
93+
* `changelog-section`: Section header to attach the changelog entry to.
94+
* type: string
95+
* required: false
96+
* default: Dependencies
97+
* `pr-strategy`: How to handle PRs.
98+
Can be either of the following:
99+
* `create` (default) - create a new PR for new dependency versions as they are released - maintainers may merge or close older PRs manually
100+
* `update` - keep a single PR that gets updated with new dependency versions until merged - only the latest version update is available at any time
101+
* `api-token`: Token for the repo. Can be passed in using `${{ secrets.GITHUB_TOKEN }}`.
102+
If you provide the usual `${{ github.token }}`, no followup CI will run on the created PR.
103+
If you want CI to run on the PRs created by the Updater, you need to provide custom user-specific auth token.
104+
* type: string
105+
* required: true
106+
107+
## Outputs
108+
109+
* `prUrl`: The created/updated PR's URL.
110+
* `baseBranch`: The base branch name.
111+
* `prBranch`: The created/updated PR branch name.
112+
* `originalTag`: The original tag from which the dependency was updated from.
113+
* `latestTag`: The latest tag to which the dependency was updated to.
114+
115+
## Migration from v2 Reusable Workflow
116+
117+
If you're migrating from the v2 reusable workflow, see the [changelog migration guide](../CHANGELOG.md#unreleased) for detailed examples.
118+
119+
Key changes:
120+
- Add `runs-on` to specify the runner
121+
- Move `secrets.api-token` to `with.api-token`
122+
- No need for explicit `actions/checkout` step (handled internally)

0 commit comments

Comments
 (0)