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 }}
          axe_linter_url: $AXE_LINTER_URL

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

Axe DevTools Linterのオンプレミスバージョンでは、APIキーは必要ありませんが、GitHubワークフローがネットワーク接続を介してAxe DevTools Linterのインスタンスに到達可能である必要があります。

コミット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
• .html
• .vue
• .md
• .markdown
• .liquid

制限事項

ファイル数

プルリクエストイベントでは、アクションは変更されたすべてのファイルをスキャンします。プッシュイベントでは、GitHub APIは変更されたファイルのリストを300ファイルに制限します。プッシュに300を超えるファイルが含まれる場合、アクションは一部のファイルがスキャンされなかったことを示す警告を記録します。

ファイルサイズ

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

次のステップ

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