@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

npm install @github-actions-workflow-ts/actions
# or
pnpm add @github-actions-workflow-ts/actions

Usage

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.

Diagnostic Codes

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

Configuring Diagnostics

You can configure how these diagnostics are handled in your wac.config.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:

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

Example: Intentionally Using an Older Version

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

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

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:

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:

{
  "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:

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.