@github-actions-workflow-ts/actions

Typed wrappers for popular GitHub Actions. Use these with @github-actions-workflow-ts/lib to get full type safety for action inputs and outputs.

Installation

``bash
npm install @github-actions-workflow-ts/actions


or


pnpm add @github-actions-workflow-ts/actions
`

Usage

`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)
`

Version Validation & Diagnostics

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.

$3

| 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) |

$3

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:
- Exact match: "actions/checkout@v3"
- Wildcard version: "actions/checkout@*" (matches any version)
- Wildcard repo: "actions/*" (matches all actions from an org)

$3

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"]
}
}
}
}
`

Available Actions


| Action | Versions | GitHub |
|--------|----------|--------|
| actions/cache | ActionsCacheV3, ActionsCacheV4 | GitHub |
| actions/checkout | ActionsCheckoutV3, ActionsCheckoutV4, ActionsCheckoutV5, ActionsCheckoutV6 | GitHub |
| actions/download-artifact | ActionsDownloadArtifactV3, ActionsDownloadArtifactV4 | GitHub |
| actions/github-script | ActionsGithubScriptV6, ActionsGithubScriptV7, ActionsGithubScriptV8 | GitHub |
| actions/setup-node | ActionsSetupNodeV3, ActionsSetupNodeV4 | GitHub |
| actions/setup-python | ActionsSetupPythonV4, ActionsSetupPythonV5 | GitHub |
| actions/upload-artifact | ActionsUploadArtifactV3, ActionsUploadArtifactV4 | GitHub |
| aws-actions/amazon-ecr-login | AwsActionsAmazonEcrLoginV2 | GitHub |
| aws-actions/amazon-ecs-deploy-task-definition | AwsActionsAmazonEcsDeployTaskDefinitionV2 | GitHub |
| aws-actions/amazon-ecs-render-task-definition | AwsActionsAmazonEcsRenderTaskDefinitionV1 | GitHub |
| aws-actions/aws-cloudformation-github-deploy | AwsActionsAwsCloudformationGithubDeployV1 | GitHub |
| aws-actions/aws-codebuild-run-build | AwsActionsAwsCodebuildRunBuildV1 | GitHub |
| aws-actions/configure-aws-credentials | AwsActionsConfigureAwsCredentialsV3, AwsActionsConfigureAwsCredentialsV4, AwsActionsConfigureAwsCredentialsV5 | GitHub |
| docker/build-push-action | DockerBuildPushActionV5, DockerBuildPushActionV6 | GitHub |
| docker/login-action | DockerLoginActionV2, DockerLoginActionV3 | GitHub |
| docker/setup-buildx-action | DockerSetupBuildxActionV2, DockerSetupBuildxActionV3 | GitHub |
| github/codeql-action | GithubCodeqlActionV2, GithubCodeqlActionV3 | GitHub |
| peaceiris/actions-gh-pages | PeaceirisActionsGhPagesV3, PeaceirisActionsGhPagesV4 | GitHub |
| release-drafter/release-drafter | ReleaseDrafterReleaseDrafterV6 | GitHub |
| softprops/action-gh-release | SoftpropsActionGhReleaseV1, SoftpropsActionGhReleaseV2 | GitHub |


Development

Regenerating Types

To regenerate types after updating the tracked actions:

`bash
pnpm run generate-action-types
`

Adding New Actions

Edit packages/actions/scripts/config.ts` to add new actions to track, then run the generate command.