Axe DevTools Linter GitHubアクションの使用

この記事では、DequeのAxe DevTools Linter GitHubアクションを使用して、GitHubのプルリクエストを作成するときにコードのアクセシビリティエラーをチェックする方法を紹介します。アクションが実行されると、プルリクエストにはコミットされたファイルのアクセシビリティエラーを示すコメントが含まれます。

以下のセクションでは、このGitHubアクションをリポジトリに設定する手順を示します。

ステップ1: APIキーの取得 (SaaSのみ)

Axe DevTools Linter SaaSを使用する場合、APIキーを取得する必要があります。Axe DevTools Linter SaaS APIキーの取得の手順に従って取得することができます。また、Axeアカウントの設定ページから既存のAPIキーを使用することもできます。APIキーの取得に問題がある場合は、Dequeのヘルプデスクに連絡してください。

ステップ2: リポジトリシークレットの作成 (SaaSのみ)

Axe DevTools Linter SaaSを使用する場合、APIキーをリポジトリのシークレットに追加する必要があります。これは、GitHubのリポジトリの設定ページに移動することで行えます。詳細については、GitHub Docsのリポジトリの暗号化されたシークレットの作成をご覧ください。

次のステップで例示されるワークフローについて、シークレットは次の名前であるべきです:

• APIキーのAXE_LINTER_API_KEY

ステップ3: ワークフローの作成

次に、ファイルがアクセシビリティエラーをチェックするためのワークフローを作成する必要があります。リポジトリの.github/workflowsディレクトリにaxe-linter.ymlという名前のファイルを作成できます。

このファイルは、リポジトリのウェブページのアクションタブで新しいワークフローとしてオンラインで作成するか、ローカルで作成してリポジトリにコミットできます（アクションページのトップセクションのGitHub Actionsを始めるの下にある自分でワークフローを設定をクリック）。

axe-linter-actionは、プルリクエストが作成されたときにワークフローで呼び出されます（on: [pull_request]）。ワークフローは2つの依存関係を使用します。

• actions/checkout@v4
• dequelabs/axe-linter-action@v2.0.0

次のセクションでは、Axe DevTools LinterのSaaSまたはオンプレミスバージョンに使用できる.github/workflows/axe-linter.ymlの例を示します。

SaaSの場合

ワークフローのSaaSバージョンにはapi_keyパラメータが含まれていますが、axe_linter_urlパラメータは含まれていません。

name: Linting for accessibility issues

on: [pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: dequelabs/axe-linter-action@v2.0.0
        with:
          api_key: ${{ secrets.AXE_LINTER_API_KEY }}          github_token: ${{ secrets.GITHUB_TOKEN }}

オンプレの場合

オンプレミス版のワークフローにはaxe_linter_urlパラメータが含まれ、api_keyにプレースホルダー値が設定されます。

name: Linting for accessibility issues

on: [pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: dequelabs/axe-linter-action@v2.0.0
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          api_key: on-prem-no-key-required          axe_linter_url: $AXE_LINTER_URL

この例でのaxe_linter_urlの値は、AXE_LINTER_URLとしてシェル環境から読み込まれます。

Axe DevTools Linterのオンプレミス版ではAPIキーは不要です。オンプレミスサーバーは独自のライセンスキーで認証されており、api_keyの値を検証しません。しかし、axe-linter-action``v2.0.0以降、api_keyは必須入力項目となるため、（上記のon-prem-no-key-requiredのような）空でないプレースホルダー値を指定しないとアクションがInput required and not supplied: api_keyエラーで失敗します。Axe DevTools Linterのインスタンスは、ネットワーク接続を介してGitHubのワークフローからアクセス可能である必要があります。

コミットSHAへのピン留め

v2.0.0から、axe-linter-actionはGitHub不変リリースを使用します。これは、@v2.0.0が公開された後に異なるコードに静かにリダイレクトされることができないことを意味します。

さらに防御を強化するために、バージョンタグではなく、完全長のコミットSHAにピン留めすることができます。これにより、タグインフラ自体がバイパスされても、元々レビューしたコミットを正確に参照し続けることができます。

- uses: dequelabs/axe-linter-action@67f0f5c49a4171cb9171213a2e2ae877386b9a80 # v2.0.0

任意のバージョンのコミットSHAはaxe-linter-actionリリースページで確認できます。Dependabotを使用すると、固定されたSHAを自動的に最新の状態に保つことができます。詳細については、GitHub DocsのGitHub Actionsのセキュリティ強化を参照してください。

GitHubアクションのパラメータ

dequelabs/axe-linter-actionは次のパラメータを使用します（上記のサンプル内のwith句で指定されています）。

ワークフローの結果

次のスクリーンショットは、アクセシビリティエラーのあるファイルでプルリクエストを作成した結果を示しています。ファイルbad-file.mdには、見出しレベルが1から3までジャンプしており、レベル2をスキップしているため、これはアクセシビリティエラーです。

トラブルシューティング

GitHubアクションでの問題のデバッグは、エラーメッセージがしばしば根本的な問題を正確に表していないため、困難な場合があります。このセクションには、見られる可能性のあるエラーの例がいくつか含まれています。

シークレット名の間違い（SaaSのみ）

APIキーシークレットの名前がワークフロー内の名前と一致しない場合、キーが定義されていないというエラーではなく、コマンドが欠落しているというエラーを受け取る可能性があります:

... line 41: Missing: command not found

権限エラー

GitHubアクションには、権限が誤って設定される可能性のある場所が多くあります。たとえば、公開されていないリポジトリをuses句で参照すると、リポジトリが見つからなかった、ではなくアクセスできないというエラーがよく発生します。

fatal: repository 'name' not found

Error: Resource not accessible by integration

ワークフローがエラー、Resource not accessible by integrationで実行に失敗した場合は、次の権限をワークフローに追加して修正することができます。

permissions:
  contents: read
  pull-requests: read 

完全なワークフローは次のようになります:

on: [pull_request]

permissions:
  contents: read
  pull-requests: read

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: dequelabs/axe-linter-action@v2.0.0
        with:
          api_key: ${{ secrets.AXE_LINTER_API_KEY }}
          github_token: ${{ secrets.GITHUB_TOKEN }}

アクションでチェックされるファイル

次の拡張子を持つファイルは、アクセシビリティエラーがないかどうかチェックされます:

• .js
• .jsx
• .tsx
• .esm
• .html
• .htm
• .vue
• .md
• .markdown
• .liquid

他の拡張子を持つファイルは無視されます。また、プルリクエストやプッシュで削除されたファイルや、内容が空白のみのファイルも無視されます。

このアクションはまた、パスにドットから始まるセグメントを含むファイルもスキップします（.）。 .githubや.storybookのようなディレクトリ内のものや、ドットファイルはリンターに送られません。

制限事項

ファイル数

axe-linter-action v2.0.0 から始めて、プルリクエストは、プルリクエストに含まれるファイルの数に関係なく、変更されたすべてのファイルをリントします。以前のバージョンでは、GitHub APIからの変更ファイルの最初のページのみをリクエストしていたため、それぞれの実行が約最初の30ファイルに制限されていました。その制限は通知がされなかったため、残りのファイルにあるアクセシビリティエラーは報告されずにアクションを通過することができました。まだv1.xを使用している場合は、プルリクエスト全体をリントするためにv2.0.0にアップグレードしてください。

プッシュイベントは異なります。このアクションは2つのコミットを比較し、GitHub APIは最大で300ファイルを比較で返します。プッシュが300以上のファイルを変更した場合、アクションはスキャンされていないファイルがあることを示す警告をログに記録します。このページの例にあるように、pull_requestイベントでアクションを実行することが、すべての変更されたファイルを確認する方法です。

パスの除外

このアクションにはパスを除外するためのパラメータはありません。サポートされている拡張子を持つ変更されたすべてのファイルがリントされ、チェックインされたnode_modulesのようなベンダーディレクトリ内のファイルも含まれます。リポジトリがサードパーティのコードをコミットしている場合、プルリクエストがそれらのファイルを変更するたびに、それらのファイルもリントされ、その分実行時間が長くなることを期待してください。

どのパスをリントするかを正確に制御する必要がある場合は、Axe DevTools Linter Connectorを使用して、お好きなファイルやディレクトリを指定できます。

ファイルサイズ

約900キロバイト（900,000バイト）を超えるファイルはスキップされ、警告として記録されます。Axe DevTools Linter APIは1MBのリクエストサイズ上限があるため、リクエストエラーを防ぐためにサイズオーバーのファイルは除外されます。

次のステップ

Axe DevTools Linterがコードをチェックするために使用するルールについての情報はアクセシビリティルールを参照してください。Gitへのコミットからアクセシビリティエラーのあるファイルを防ぐ方法について詳しく知りたい場合は、Gitプリコミットフックの使用をご覧ください。