GitHub Actions Integration

Integrate Codeward into GitHub workflows for diff-aware policy gating on every PR.

Quick Start

Create .github/workflows/codeward-scan.yml:

name: Codeward
on:
  pull_request:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: read
      pull-requests: write
      issues: write
    steps:
      - uses: codeward-io/[email protected]
        with:
          event: ${{ github.event_name }}
          repository: ${{ github.repository }}
          current_branch: ${{ github.ref }}
          pr_number: ${{ github.event.number }}
          token: ${{ github.token }}

PR events perform a diff (base vs head). Non-PR events scan the default branch.

Permissions

Permission	Why Needed
contents: read	Checkout repository
packages: read	Pull scanner image from GHCR
pull-requests: write	Post PR comments (remove if not using git:pr)
issues: write	Create/update issues (remove if not using git:issue)

Advanced: Dependency Installation

Installing dependencies enriches vulnerability & license detection.

PR Workflow with Dependency Installs

name: Codeward (PR with deps)
on: pull_request

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with: { ref: "${{ github.base_ref }}", path: main }
      - uses: actions/checkout@v4
        with: { ref: "${{ github.head_ref }}", path: branch }

      - uses: actions/setup-node@v4
        with:
          node-version: '24'
          cache: npm
          cache-dependency-path: |
            main/package-lock.json
            branch/package-lock.json
      - run: npm ci
        working-directory: main
        if: hashFiles('main/package-lock.json') != ''
      - run: npm ci
        working-directory: branch
        if: hashFiles('branch/package-lock.json') != ''

      - run: |
          echo ${{ secrets.GITHUB_TOKEN }} | docker login ghcr.io -u ${{ github.actor }} --password-stdin
          docker pull ghcr.io/codeward-io/scan:v0.3.0
      - run: |
          mkdir -p results cache
          docker run --rm \
            -v ${PWD}/main:/main:rw \
            -v ${PWD}/branch:/branch:rw \
            -v ${PWD}/results:/results:rw \
            -v ${PWD}/cache:/.cache:rw \
            -e CODEWARD_GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }} \
            -e CODEWARD_GITHUB_OWNER=${{ github.repository_owner }} \
            -e CODEWARD_GITHUB_REPOSITORY=${{ github.event.repository.name }} \
            -e CODEWARD_GITHUB_PR_NUMBER=${{ github.event.number }} \
            -e CODEWARD_MODE=diff \
            ghcr.io/codeward-io/scan:v0.3.0

Webhook Secrets

Pass sensitive values for custom webhooks:

- uses: codeward-io/[email protected]
  with:
    webhook_secrets: |
      SLACK_TOKEN=${{ secrets.SLACK_TOKEN }}
      JIRA_API_KEY=${{ secrets.JIRA_API_KEY }}

Scheduled Scans

on:
  schedule:
    - cron: '30 2 * * *'  # Daily at 2:30 AM

Ensure issues: write permission for git:issue destinations.

Recommendations

• Pin action version (@v0.3.0) for reproducibility
• Start with warn actions, promote to block after review
• Use combined JSON + markdown for human + automation channels