Typed wrappers for popular GitHub Actions
npm install @github-actions-workflow-ts/actionsTyped wrappers for popular GitHub Actions. Use these with @github-actions-workflow-ts/lib to get full type safety for action inputs and outputs.
``bash`
npm install @github-actions-workflow-ts/actionsor
pnpm add @github-actions-workflow-ts/actions
`typescript
import { Workflow, NormalJob } from '@github-actions-workflow-ts/lib'
import { ActionsCheckoutV4, ActionsSetupNodeV4 } from '@github-actions-workflow-ts/actions'
const checkout = new ActionsCheckoutV4({
name: 'Checkout code',
// fields are validated and typed with descriptions
with: {
'fetch-depth': 0,
},
})
const setupNode = new ActionsSetupNodeV4({
id: 'setup-node',
name: 'Setup Node.js',
with: {
'node-version': '20.x',
cache: 'pnpm',
},
})
// Access typed outputs
console.log(setupNode.outputs['node-version']) // '${{ steps.setup-node.outputs.node-version }}'
console.log(setupNode.outputs['cache-hit']) // '${{ steps.setup-node.outputs.cache-hit }}'
// typical usage
const echoNodeVersion = new Step({
name: 'Echo Node Version',
run: echo "Node version: ${setupNode.outputs['node-version']}",
})
// // will output:
// - name: Echo Node Version
// run: 'echo "Node version: ${{ steps.setup-node.outputs.node-version }}"'
const job = new NormalJob('build', { 'runs-on': 'ubuntu-latest' })
.addStep(checkout)
.addStep(setupNode)
`
When using typed actions, the CLI validates that the action version you specify matches the expected version. For example, if you use ActionsCheckoutV4 but override the uses field to actions/checkout@v3, a warning will be emitted during build.
| Code | Description |
|------|-------------|
| action-version-unverifiable | The action version cannot be verified because the git ref is not a valid semver (e.g., @main, @feature-branch) or the repository doesn't match |action-version-semver-violation
| | The action version doesn't satisfy the expected semver constraint (e.g., using @v3 with a V4 typed action) |
You can configure how these diagnostics are handled in your wac.config.json:
`json`
{
"diagnostics": {
"rules": {
"action-version-unverifiable": "off",
"action-version-semver-violation": "error"
}
}
}
#### Severity Levels
- "off" - Suppress the diagnostic entirely"warn"
- - Emit as a warning (default behavior)"error"
- - Upgrade to an error
#### Advanced: Per-Action Rules
You can suppress diagnostics for specific actions while keeping them enabled for others:
`json`
{
"diagnostics": {
"rules": {
"action-version-semver-violation": {
"severity": "error",
"exclude": [
"actions/checkout@*",
"actions/setup-node@v3"
]
}
}
}
}
The exclude array supports patterns:"actions/checkout@v3"
- Exact match: "actions/checkout@*"
- Wildcard version: (matches any version)"actions/*"
- Wildcard repo: (matches all actions from an org)
If you need to use an older action version for compatibility reasons, you can suppress the warning in two ways:
#### Option 1: In-Code Suppression with suppressWarnings prop
`typescript
import { ActionsCheckoutV4 } from '@github-actions-workflow-ts/actions'
const checkout = new ActionsCheckoutV4({
name: 'Checkout',
uses: 'actions/checkout@v3',
suppressWarnings: ['action-version-semver-violation'],
})
`
#### Option 2: In-Code Suppression with Diagnostics.suppress()
`typescript
import { ActionsCheckoutV4 } from '@github-actions-workflow-ts/actions'
import { Diagnostics } from '@github-actions-workflow-ts/lib'
const checkout = new ActionsCheckoutV4({
name: 'Checkout',
uses: Diagnostics.suppress(
'actions/checkout@v3',
'action-version-semver-violation',
'Using v3 for legacy compatibility' // optional reason
),
})
`
You can also suppress multiple codes:
`typescript`
const checkout = new ActionsCheckoutV4({
uses: Diagnostics.suppress(
'actions/checkout@v3',
['action-version-semver-violation', 'action-version-unverifiable'],
),
})
#### Option 3: Configuration-based Suppression
Add to wac.config.json:
`json`
{
"diagnostics": {
"rules": {
"action-version-semver-violation": {
"exclude": ["actions/checkout@v3"]
}
}
}
}
| Action | Versions | GitHub |
|--------|----------|--------|
| actions/cache | ActionsCacheV3, ActionsCacheV4 | GitHub |ActionsCheckoutV3
| actions/checkout | , ActionsCheckoutV4, ActionsCheckoutV5, ActionsCheckoutV6 | GitHub |ActionsDownloadArtifactV3
| actions/download-artifact | , ActionsDownloadArtifactV4 | GitHub |ActionsGithubScriptV6
| actions/github-script | , ActionsGithubScriptV7, ActionsGithubScriptV8 | GitHub |ActionsSetupNodeV3
| actions/setup-node | , ActionsSetupNodeV4 | GitHub |ActionsSetupPythonV4
| actions/setup-python | , ActionsSetupPythonV5 | GitHub |ActionsUploadArtifactV3
| actions/upload-artifact | , ActionsUploadArtifactV4 | GitHub |AwsActionsAmazonEcrLoginV2
| aws-actions/amazon-ecr-login | | GitHub |AwsActionsAmazonEcsDeployTaskDefinitionV2
| aws-actions/amazon-ecs-deploy-task-definition | | GitHub |AwsActionsAmazonEcsRenderTaskDefinitionV1
| aws-actions/amazon-ecs-render-task-definition | | GitHub |AwsActionsAwsCloudformationGithubDeployV1
| aws-actions/aws-cloudformation-github-deploy | | GitHub |AwsActionsAwsCodebuildRunBuildV1
| aws-actions/aws-codebuild-run-build | | GitHub |AwsActionsConfigureAwsCredentialsV3
| aws-actions/configure-aws-credentials | , AwsActionsConfigureAwsCredentialsV4, AwsActionsConfigureAwsCredentialsV5 | GitHub |DockerBuildPushActionV5
| docker/build-push-action | , DockerBuildPushActionV6 | GitHub |DockerLoginActionV2
| docker/login-action | , DockerLoginActionV3 | GitHub |DockerSetupBuildxActionV2
| docker/setup-buildx-action | , DockerSetupBuildxActionV3 | GitHub |GithubCodeqlActionV2
| github/codeql-action | , GithubCodeqlActionV3 | GitHub |PeaceirisActionsGhPagesV3
| peaceiris/actions-gh-pages | , PeaceirisActionsGhPagesV4 | GitHub |ReleaseDrafterReleaseDrafterV6
| release-drafter/release-drafter | | GitHub |SoftpropsActionGhReleaseV1
| softprops/action-gh-release | , SoftpropsActionGhReleaseV2 | GitHub |
To regenerate types after updating the tracked actions:
`bash`
pnpm run generate-action-types
Edit packages/actions/scripts/config.ts` to add new actions to track, then run the generate command.