https://github.com/jessehouwing/actions-dependency-submission
Action to automatically report versions for pinned action dependencies
https://github.com/jessehouwing/actions-dependency-submission
dependabot dependency-submission github github-actions github-advanced-security
Last synced: 14 days ago
JSON representation
Action to automatically report versions for pinned action dependencies
- Host: GitHub
- URL: https://github.com/jessehouwing/actions-dependency-submission
- Owner: jessehouwing
- License: mit
- Created: 2025-12-03T14:44:01.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-01-10T13:25:01.000Z (16 days ago)
- Last Synced: 2026-01-11T04:05:02.369Z (15 days ago)
- Topics: dependabot, dependency-submission, github, github-actions, github-advanced-security
- Language: TypeScript
- Homepage: https://github.com/marketplace/actions/github-actions-dependency-submission
- Size: 7.58 MB
- Stars: 3
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Codeowners: CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# GitHub Actions Dependency Submission
A GitHub Action that scans your repository's workflow files and submits action
dependencies to GitHub's Dependency Graph with fork traversal support.
## Features
- 🔍 **Automatic Workflow Scanning**: Scans `.github/workflows` directory for
GitHub Actions dependencies
- 📦 **Composite Actions**: Recursively scans local composite actions for nested
dependencies
- 🔄 **Callable Workflows**: Detects and processes callable workflows referenced
from workflows
- 🎯 **Additional Paths**: Supports scanning custom directories for composite
actions and callable workflows
- 🐳 **Docker Image Detection** (Experimental, opt-in): Detects Docker images
from:
- Job-level containers (`jobs..container.image`)
- Service containers (`jobs..services..image`)
- Step-level Docker actions (`uses: docker://image:tag`)
- Docker-based action.yml files (`runs.using: docker`)
- Dockerfile base images (`FROM` instructions)
- 🔀 **Fork Traversal**: Detects forked actions and submits both the fork and
original repository as dependencies
- 🔗 **GitHub API Integration**: Uses GitHub's fork relationship to find
original repositories
- 🎯 **Regular Expression Pattern Matching**: Supports custom regular expression
patterns for repositories without fork relationships (e.g., EMU or GitHub-DR)
- 📊 **Dependency Graph Integration**: Submits dependencies to GitHub's
Dependency Graph for security advisory tracking
## Usage
### Basic Usage
```yaml
name: Submit Dependencies
on:
push:
branches: [main]
schedule:
- cron: '0 0 * * 0' # Weekly
jobs:
submit-dependencies:
runs-on: ubuntu-latest
permissions:
contents: write # Required for dependency submission
steps:
- uses: actions/checkout@v6
- uses: jessehouwing/actions-dependency-submission@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
```
### With Fork Organization Support
If your enterprise uses forked actions (e.g., `myenterprise/actions-checkout` as
a fork of `actions/checkout`):
```yaml
- uses: jessehouwing/actions-dependency-submission@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
fork-organizations: 'myenterprise,myorg'
```
This will submit both `myenterprise/actions-checkout` and the original
`actions/checkout` as dependencies, ensuring security advisories for the
original repository also apply to your fork.
### With Custom Regular Expression Pattern
For cases where fork relationships don't exist (e.g., EMU or GitHub-DR
environments):
```yaml
- uses: jessehouwing/actions-dependency-submission@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
fork-organizations: 'myenterprise'
fork-regex: '^myenterprise/(?[^_]+)_(?.+)'
```
The regular expression must contain named captures `org` and `repo` to identify
the original repository. In this example:
- `myenterprise/actions_checkout` would resolve to `actions/checkout`
- This is useful when forks follow a naming convention but don't have GitHub
fork relationships
### With Additional Paths for Composite Actions
If you store composite actions or callable workflows in custom directories:
```yaml
- uses: jessehouwing/actions-dependency-submission@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
additional-paths: |
.github/actions
custom/workflows
shared/actions
```
This will:
- Scan the specified directories for composite actions (identified by
`runs.using: composite`)
- Recursively extract dependencies from those composite actions
- Include dependencies from callable workflows (identified by
`on.workflow_call`)
- Process local action references (e.g., `uses: ./local-action`) in workflows
### For EMU, GitHub-DR, or GHES Environments
If you're running on GitHub Enterprise Managed Users (EMU), GitHub Disaster
Recovery (GitHub-DR), or GitHub Enterprise Server (GHES), and your workflows
reference actions from public GitHub that aren't mirrored to your instance:
```yaml
jobs:
submit-dependencies:
runs-on: ubuntu-latest
permissions:
contents: write # Required for dependency submission
steps:
- uses: actions/checkout@v6
- uses: jessehouwing/actions-dependency-submission@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
fork-organizations: 'myenterprise'
public-github-token: ${{ secrets.PUBLIC_GITHUB_TOKEN }}
```
This configuration:
- Uses `token` to access your local GitHub instance and submit dependencies
- Uses `public-github-token` to look up actions on public GitHub
(api.github.com) when they're not found on your local instance
- Automatically determines whether each action lives on your local instance or
public GitHub
- Caches the location decision to minimize API calls
- Resolves fork relationships and SHA-to-version mappings from the appropriate
source
**Note:** The `public-github-token` requires `contents: read` permission for
accessing public repositories on GitHub.com. See the
[environment-specific documentation](#environment-specific-documentation) for
detailed setup instructions for different token types.
### Configuring Transitive Dependency Reporting
By default, all dependencies (including transitive dependencies from composite
actions and original repositories from forks) are reported as "direct"
dependencies. This ensures that GitHub's Dependency Graph will report
vulnerabilities for all dependencies.
If you want to distinguish between direct and transitive dependencies:
```yaml
- uses: jessehouwing/actions-dependency-submission@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
report-transitive-as-direct: false
```
With `report-transitive-as-direct: false`:
- Dependencies directly referenced in your workflows are marked as "direct"
- Dependencies from composite actions are marked as "indirect"
- Original repositories (when using forked actions) are marked as "indirect"
**Note:** GitHub's Dependency Graph only reports vulnerabilities for "direct"
dependencies. Setting this to `false` means you won't receive vulnerability
alerts for transitive dependencies and original repositories.
### Detecting Docker Image Dependencies (Experimental)
**Note:** Docker dependency detection is experimental and opt-in. Enable with
`detect-docker: true`.
The action can detect and report Docker image dependencies from your workflows:
```yaml
- uses: jessehouwing/actions-dependency-submission@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
detect-docker: true
```
This will extract Docker images from:
- **Job containers**: `jobs..container.image`
- **Service containers**: `jobs..services..image`
- **Step-level Docker actions**: `uses: docker://alpine:latest`
- **Docker-based action.yml**: `runs.using: docker`, `image: docker://node:18`
- **Dockerfile base images**: FROM instructions in Dockerfiles referenced by
action.yml
**Example workflow with Docker dependencies:**
```yaml
jobs:
test:
runs-on: ubuntu-latest
container: node:18-alpine
services:
postgres:
image: postgres:15
steps:
- uses: actions/checkout@v6
- uses: docker://alpine:latest
with:
args: echo "Hello from Alpine"
```
Docker images are reported using the
[PURL (Package URL) standard](https://github.com/package-url/purl-spec) format:
- `pkg:docker/library/node@18-alpine` (Docker Hub official images)
- `pkg:docker/owner/image@v1.0.0?repository_url=ghcr.io` (GHCR)
- `pkg:docker/library/postgres@sha256:abc123...` (with digest)
**Benefits:**
- 🔒 Get Dependabot alerts for vulnerable Docker images
- 🛡️ Use Dependency Review to block PRs with vulnerable container images
- 📦 Track Docker image versions across workflows
- 🐳 Discover Dockerfile base images used in custom actions
- 📋 Generate complete SBOMs including all container dependencies
**Note:** Docker detection is currently experimental. Please report any issues
or unexpected behavior.
## Inputs
| Input | Description | Required | Default |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------- |
| `token` | GitHub token for API access and dependency submission | Yes | `${{ github.token }}` |
| `repository` | Repository to submit dependencies for (owner/repository format) | No | `${{ github.repository }}` |
| `workflow-directory` | Directory containing workflow files to scan | No | `.github/workflows` |
| `additional-paths` | Additional paths to scan for composite actions and callable workflows (comma-separated or newline-separated) | No | - |
| `fork-organizations` | Comma-separated list of organization names that contain forked actions | No | - |
| `fork-regex` | Regular expression pattern to transform forked repository names. Must contain named captures `org` and `repo` | No | - |
| `public-github-token` | GitHub token for accessing public GitHub (api.github.com) when running on EMU, GitHub-DR, or GHES. Used to look up actions not on local instance | No | - |
| `report-transitive-as-direct` | Whether to report transitive dependencies as direct. When `true` (default), all dependencies are reported as direct to enable vulnerability reporting. When `false`, transitive dependencies are indirect. | No | `true` |
| `detect-docker` | **(Experimental)** Enable Docker image dependency detection. Extracts images from containers, services, docker:// steps, and Dockerfile base images. When `false` (default), only GitHub Actions dependencies are reported. This is an opt-in experimental feature. | No | `false` |
## Outputs
| Output | Description |
| ------------------ | -------------------------------------------------------- |
| `dependency-count` | Number of dependencies submitted to the Dependency Graph |
## How It Works
1. **Workflow Scanning**: The action scans all `.yml` and `.yaml` files in the
specified workflow directory
1. **Dependency Extraction**: Parses each workflow file to extract `uses:`
statements that reference GitHub Actions
1. **Local Action Processing**: Detects local action references (e.g.,
`uses: ./local-action`):
- Resolves the path relative to the workflow file
- Checks if it's a composite action
- Recursively extracts dependencies from the composite action
1. **Callable Workflow Processing**: Detects callable workflow references (e.g.,
`uses: ./workflow.yml` at job level):
- Processes the callable workflow
- Extracts all action dependencies from it
1. **Additional Paths Scanning**: If specified, scans additional directories for
composite actions:
- Finds all YAML files in the specified paths
- Processes composite actions found there
- Recursively extracts their dependencies
1. **Fork Detection**: For actions from organizations in the
`fork-organizations` list:
- First tries to apply the `fork-regex` pattern if provided
- Falls back to checking GitHub's fork relationship via the API
1. **EMU/DR/GHES Support**: When `public-github-token` is provided:
- Determines whether each action repository exists on the local GitHub
instance or public GitHub
- Caches this decision to avoid redundant API calls
- Uses the appropriate API endpoint for all subsequent operations on that
repository
- Enables looking up fork relationships and SHA-to-version mappings from
public GitHub when needed
1. **Dependency Submission**: Submits all dependencies to GitHub's Dependency
Graph:
- For forked actions, submits both the fork and original repository
- Uses Package URL (purl) format: `pkg:github/{owner}/{repo}@{ref}`
1. **Security Advisories**: GitHub automatically matches submitted dependencies
against its security advisory database
## Why Use This Action?
When you use forked GitHub Actions in your workflows, GitHub's Dependabot and
security advisories only track the fork, not the original repository. This
means:
- Security vulnerabilities in the original action won't trigger alerts for your
fork
- You won't be notified when the original action has security updates
This action solves this problem by submitting both repositories as dependencies,
ensuring you receive security advisories for both the fork and the original.
## Example Use Case
Your enterprise has forked `actions/checkout` to `myenterprise/actions-checkout`
for additional security controls. Your workflows use:
```yaml
- uses: myenterprise/actions-checkout@v4
```
Without this action, you only get security advisories for
`myenterprise/actions-checkout`. With this action configured, you'll receive
advisories for both:
- `myenterprise/actions-checkout@v4`
- `actions/checkout@v6`
## Combining with Dependency Review
Once dependencies are submitted to the Dependency Graph, you can use the
[Dependency Review Action](https://github.com/actions/dependency-review-action)
to block pull requests that introduce vulnerable or unwanted action
dependencies.
### Quick Setup
First, ensure the dependency submission action runs on both `push` and
`pull_request` events (required for comparison):
```yaml
# .github/workflows/submit-dependencies.yml
name: Submit Dependencies
on:
push:
branches: [main]
pull_request:
schedule:
- cron: '0 0 * * 0' # Weekly
jobs:
submit-dependencies:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v6
- uses: jessehouwing/actions-dependency-submission@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
```
Then add the dependency review workflow:
```yaml
# .github/workflows/dependency-review.yml
name: Dependency Review
on: pull_request
jobs:
dependency-review:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v6
- uses: actions/dependency-review-action@v4
```
### Enforcing Dependency Review
To ensure all pull requests pass dependency review before merging:
1. Configure a **branch ruleset** with required status checks
2. Add the dependency review job as a required check
For detailed configuration options including license policies, vulnerability
severity thresholds, and branch protection setup, see the
[Dependency Review Guide](docs/dependency-review.md).
## Permissions
The action requires the following permissions:
```yaml
jobs:
submit-dependencies:
runs-on: ubuntu-latest
permissions:
contents: write # Required for dependency submission
steps:
# ... your steps
```
**Important Notes:**
- Always define permissions at the **job level**, not at the workflow level, to
follow the principle of least privilege
- The primary `token` requires `contents: write` permission to submit
dependencies
- If your workflows reference **private or internal actions** in other
repositories, you must configure repository access settings. See
[Allowing access to components in a private repository](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-a-private-repository)
- The optional `public-github-token` (for EMU/DR/GHES) requires `contents: read`
permission for public repositories on GitHub.com
For detailed guidance on token permissions for different environments, see the
[Environment-Specific Documentation](#environment-specific-documentation).
## Environment-Specific Documentation
For detailed configuration instructions, token setup, and best practices
specific to your environment, please refer to the appropriate guide:
- **[GitHub Public / GitHub Enterprise Cloud](docs/github-public.md)** -
Standard GitHub.com and GHEC environments
- **[GitHub Enterprise Managed Users (EMU)](docs/github-emu.md)** - EMU
environments with forked actions
- **[GitHub Disaster Recovery (GitHub-DR)](docs/github-dr.md)** - GitHub-DR
environments with action synchronization
- **[GitHub Enterprise Server (GHES)](docs/github-ghes.md)** - Self-hosted GHES
instances
- **[Dependency Review Integration](docs/dependency-review.md)** - Enforce
security policies on pull requests
Each guide covers:
- ✅ Using workflow tokens (`GITHUB_TOKEN`)
- ✅ Using GitHub App tokens (recommended for cross-repository access)
- ✅ Using personal access tokens (with security warnings)
- ✅ Required permissions for each token type
- ✅ Handling private and internal actions
- ✅ Complete working examples
- ✅ Advantages and disadvantages of each approach
- ✅ Environment-specific considerations
## Development
### Setup
1. Install dependencies:
```bash
npm install
```
1. Run tests:
```bash
npm test
```
1. Bundle the action:
```bash
npm run bundle
```
### Testing
The action includes comprehensive unit tests for:
- Workflow file parsing
- Fork resolution via GitHub API
- Regular expression pattern matching
- Dependency submission
Run tests with coverage:
```bash
npm run all
```
## License
MIT
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.