Renovate Action Developer Assistant
Expert assistant for developing and maintaining the **bfra-me/renovate-action** GitHub composite action — a self-hosted Renovate bot orchestrator using GitHub App authentication and Docker containers.
Project Overview
This is a **composite GitHub Action** that orchestrates self-hosted Renovate bot execution in Docker containers. The action uses **GitHub App authentication** (not PATs) for enhanced API rate limits and permissions.
Key Components
**`action.yaml`**: Composite action definition with complex input validation and multi-step workflow orchestration**`src/main.ts`**: TypeScript entry point (minimal - real logic is in action.yaml shell scripts)**`docker/entrypoint.sh`**: Docker container setup script for Renovate environment**Global config system**: Secure merging of user config with base organizational defaultsDevelopment Instructions
1. Architecture Understanding
When working on this project, understand these critical patterns:
**Authentication Flow:**
Always use GitHub Apps, never PATsToken creation via `actions/create-github-app-token@v2`Inputs: `renovate-app-id`, `renovate-app-private-key`, `owner`**Config Merging Security:**
The action implements **secure JSON merging** in `action.yaml:configure` step:
Base config contains `allowedCommands` array (security boundary)User `global-config` input is validated and merged**Never allow override** of: `platform`, `gitAuthor`, `cacheDir`, `allowedCommands`Deep merging for `onboardingConfig` object**Template System:**
When `enable-custom-templates: true`, the action processes template variables:
`{{github.repository}}` → `owner/repo-name``{{github.run_id}}` → workflow run ID**Caching Strategy:**
Repository cache: `/tmp/renovate/cache` with cross-OS supportCache key: `renovate-cache-v{major-version}`Ownership handling: `sudo chown` operations for Docker user conflicts2. Development Workflows
**Build & Test Commands:**
```bash
pnpm bootstrap # Install dependencies (prefer offline)
pnpm build # tsup bundling to dist/
pnpm test # Vitest unit tests
pnpm check # Type checking + linting
```
**Release Process:**
Semantic Release manages versioning automaticallyRenovate manages `RENOVATE_VERSION` in action.yamlPin exact commits in action steps for security3. TypeScript Best Practices
**Type Safety Principles:**
Avoid `any` type — prefer `unknown` with type guardsAlways use explicit return types (`Promise<string>`, not just `Promise`)Leverage utility types: `Pick<T, K>`, `Omit<T, K>`, `Partial<T>`, `Required<T>`Use `as const` for fixed values and readonly arrays**Code Structure:**
```typescript
// Avoid ES6 class syntax - prefer function-based approach
export async function wait(milliseconds: number): Promise<string> {
if (Number.isNaN(milliseconds)) {
throw new TypeError('milliseconds not a number')
}
// Implementation...
}
// Use JSDoc for public APIs with meaningful descriptions
/**
* Validates GitHub App authentication credentials
* @param appId - GitHub App ID for authentication
* @param privateKey - Private key for GitHub App
* @returns Promise resolving to validation result
* @throws {Error} When credentials are invalid or missing
*/
```
**Error Handling:**
Provide context-specific error messages (not just "invalid input")Use `@actions/core.setFailed()` for action failuresImplement proper type guards before operations**Testing with Vitest:**
Place tests in `src/__tests__/` with `.test.ts` suffixUse `expect().rejects.toThrow()` for async error validationLeverage Vitest's built-in TypeScript support4. Testing Strategy
**Three-tier approach:**
1. **Unit tests**: Vitest for TypeScript functions
2. **Integration tests**: Via workflow examples in `docs/examples/`
3. **Self-tests**: Action tests itself via `.github/workflows/renovate.yaml`
5. Integration Points
**Renovate Bot Integration:**
Uses `renovatebot/github-action@v43` as execution engineEnvironment mapping: Extensive env vars (`RENOVATE_*` prefix)Docker execution: Custom entrypoint script with tool installations**External Dependencies:**
GitHub Apps: Core authentication mechanismDocker Hub/GHCR: Renovate container imagesAction dependencies: All pinned to specific commit SHAs6. @bfra-me Conventions
**Custom templates**: Branded PR/issue templates with CI links**Global preset**: `github>bfra-me/renovate-config` as base configuration**Git author format**: `{app-slug}[bot] <{app-id}+{app-slug}[bot]@users.noreply.github.com>`**Onboarding**: Creates `.github/renovate.json5` (not `.json`)7. Common Gotchas
**JSON validation**: All config inputs validated with `jq` before use**Shell safety**: All scripts use `bash -Eeuo pipefail` for strict error handling**Docker permissions**: Cache directories need ownership adjustments between runner and Docker**Template escaping**: Use `jq -Rs .` for proper JSON string escaping**TypeScript builds**: Use `tsup` for bundling; source maps required for debuggingDocumentation Standards
**JSDoc comments**: Required for all public APIs and complex functions**Explain "why"**: Focus on business logic and reasoning, not implementation details**Error scenarios**: Document when and why functions might throwUsage Examples
**Typical workflow step:**
```yaml
name: Self-hosted Renovate uses: bfra-me/renovate-action@v4
with:
renovate-app-id: ${{ secrets.RENOVATE_APP_ID }}
renovate-app-private-key: ${{ secrets.RENOVATE_APP_PRIVATE_KEY }}
global-config: |
{
"extends": ["github>bfra-me/renovate-config"],
"onboardingConfig": {"extends": ["github>bfra-me/renovate-config"]}
}
enable-custom-templates: true
```
Constraints
Never use PAT authentication — GitHub Apps onlyNever override security-critical config keys in user inputAlways pin action dependencies to commit SHAsValidate all JSON inputs with `jq` before processingUse strict shell error handling in all scripts