GitHub Actionsでリポジトリのコードをチェックアウトする

以下の記事を参考にGitHub Actionsのworkflowを書いてみたいと思います。

cloudscalr.com

今回はactions/checkout@v3をworkflowのjobで使ってリポジトリのコードをGitHub Actionsのrunnerにチェックアウトするところまでやってみます。

まずGitHubActions_Terraform_Demo_Privateというプライベートリポジトリを作成し、ローカルにgit cloneしました。

README.mdを作成しました。

echo "# GitHubActions_Terraform_Demo_Private" >> README.md

リモートのmainブランチにプッシュしておきます。

git add README.md
git commit -m "first commit"
git branch -M main
git push origin main

続いてローカルで作業用ブランチにチェックアウトします。

git checkout -b feature/add_workflow

GitHub Actionsのworkflowファイルを作成します。

mkdir -p .github/workflows && touch .github/workflows/main.yml

actions/checkout@v3を使ってGitHub Actionsのrunnerにチェックアウトだけ行う目的でmain.ymlは以下のようにしました。

name: "GitHubActions_Terraform_Demo_Private"
on:
  pull_request:
permissions:
  contents: read # this is required to checkout the repository
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Git Checkout
        uses: actions/checkout@v3
      - name: "ls command"
        run: ls -la

これを作業ブランチからリモートリポジトリにプッシュしてみます。

git add .github/workflows/main.yml
git commit -m "add workflow"
git push origin feature/add_workflow

GitHubの画面からプルリクエストを作成します。

GitHub Actionsが実行されました。

All checks have passedになったのでDetailsから処理の詳細を確認してみます。

lsコマンドが実行されて、README.mdなどリポジトリのファイルがcheckoutされていることが確認できました。

checkoutを行うにはcontents: readの権限が必要とどこかで見たのでpermissionsで指定しているのですが、実際に検証まではしてなかったので試しにcontents: readの権限付与をコメントアウトして実行してみました。

.github/workflows/main.yml

name: "GitHubActions_Terraform_Demo_Private"
on:
  pull_request:
# permissions:
#   contents: read # this is required to checkout the repository
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Git Checkout
        uses: actions/checkout@v3
      - name: "ls command"
        run: ls -la

これを作業ブランチからリモートリポジトリにプッシュしてみます。

git add .github/workflows/main.yml
git commit -m "delete contents.read permission"
git push origin feature/add_workflow

するとcontents: readが無くても同じようにチェックアウトが成功していました。

挙動がよくわからなかったので一度ChatGPTに質問してみました。

入力

What does below permission do on github Actions? permissions: contents: read

出力

The permissions field in GitHub Actions workflow file allows you to specify the permissions that your workflow needs to access various resources within your repository.

The contents: read permission in the permissions field grants the workflow read-only access to the contents of your repository, such as files and directories. With this permission, your workflow can access the contents of the repository and read its contents, but it cannot modify or create any new files.

This permission is useful if your workflow needs to read some configuration files, dependencies or other files from the repository without modifying them. It ensures that your workflow can only read the contents of the repository, without being able to make any changes that could potentially affect your project's stability or security.

permissionsフィールドはworkflowがリポジトリ内のリソースにアクセスすることを許可するためのもので、contents:readでリポジトリへread-onlyアクセスを付与するという理解で良さそうです。

contents:read無しの場合はリポジトリをチェックアウトできないということになるのか聞いてみました。

入力

If I don't add contents: read, the workflow can't checkout my repository?

出力

When you create a GitHub Actions workflow, by default the workflow is able to checkout the repository's source code by using the actions/checkout action. This action checks out the repository's source code into the workflow's virtual environment so that you can use it during the workflow.

If you do not specify any permissions in your workflow file, the actions/checkout action will still be able to checkout your repository's source code into the workflow's virtual environment, regardless of the repository's public or private status.

However, if you specify any permissions in your workflow file, you need to make sure that the specified permissions are sufficient to allow the actions/checkout action to checkout the repository's source code. For example, if you specify contents: read permission, this will allow the actions/checkout action to read the contents of the repository's files and checkout the repository's source code into the workflow's virtual environment. If you do not specify contents: read permission, the actions/checkout action may not be able to checkout the repository's source code and your workflow may fail.

So to answer your question, if you do not specify any permissions in your workflow file, the actions/checkout action will still be able to checkout your repository's source code without any issues, regardless of the presence of contents: read permission. However, if you do specify permissions, you need to ensure that the actions/checkout action has sufficient permissions to checkout the repository's source code.

どうやらcontents:read無しでもactions/checkout@v3はリポジトリをチェックアウトできるようです。 要するにcontents:readを指定するべきかどうかを聞いてみました。

入力

Sorry I think I don't understand the point you make. Should I specify contents: read or not when I want to checkout my code to GitHub Actions runner machine.

出力

No problem, I apologize for any confusion. To answer your question, you do not need to explicitly specify contents: read in your GitHub Actions workflow file to checkout your repository's source code into the runner machine.

By default, the actions/checkout action that is commonly used to checkout a repository's source code in GitHub Actions already has the necessary permissions to read the contents of your repository. Therefore, even if you do not include a permissions section in your workflow file, the actions/checkout action will still be able to checkout your repository's code.

In summary, if your goal is simply to checkout your repository's code into a GitHub Actions runner machine, you do not need to specify contents: read in your workflow file as it is not necessary.

リポジトリのコードをrunnerにチェックアウトするという目的を果たすだけならcontents:readは必ず必要という感じではないみたいです。

それではcontents:readは単に冗長なコードということになるのかと思いましたので追加で質問してみました。

Okay. I understand I don't need to specify contents: read. So, why some developers specify it on their workflows? Is there any use case that is not executed without specify contents: read? Or, is it just redundant code?

出力

Good question. While specifying contents: read in a GitHub Actions workflow file may not be necessary to checkout your repository's source code into the runner machine, it can be useful in certain situations.

For example, if your workflow needs to access certain files within your repository (such as configuration files, build scripts, or test data), you may want to explicitly specify the contents: read permission to ensure that your workflow can read these files. Without this permission, your workflow may fail if it cannot access the necessary files.

Similarly, if you have multiple workflows that need to access the same set of files within your repository, you can specify the contents: read permission in each workflow file, or you can specify it once in a separate YAML file (e.g., permissions.yml) and then reference it in your workflow files. This can make your workflow files more concise and easier to maintain.

In summary, while specifying contents: read in a GitHub Actions workflow file may not always be necessary, it can be a useful way to ensure that your workflow has the necessary permissions to read files within your repository, and it can make your workflow files more maintainable in certain situations.

contents:read無しでもリポジトリをチェックアウトできるけど、明示的に書くことで持っている権限を確認しやすく、保守性が上がるよ、という感じで理解しました。 個人的にもデフォルトの権限を常に把握しておくのは大変なので、挙動に違いはなくても明示的に権限を書いておくのは良いことに感じました。 この辺りは現場ではチームの方針に合わせる感じで良いと思います。

公式ドキュメントは下記にあるので、必要に応じて読んでみます。

docs.github.com

あと、チェックアウトをしない場合のrunnerの状態も確認してみました。 チェックアウトでリポジトリのコードを取得するということなので、チェックアウトしない場合は空になる想定です。

.github/workflows/main.ymlを以下のようにしました。

name: "GitHubActions_Terraform_Demo_Private"
on:
  pull_request:
permissions:
  contents: read # this is required to checkout the repository
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    #   - name: Git Checkout
    #     uses: actions/checkout@v3
      - name: "ls command"
        run: ls -la

リモートブランチにプッシュします。

git add .github/workflows/main.yml
git commit -m "remove checkout"
git push origin feature/add_workflow

GitHub Actionsのジョブを確認すると、想定通りlsコマンドを実行してもREADME.mdなどのファイルが無いことがわかりました。

actions/checkout@v3のリポジトリは以下にありました。TypeScriptで実装されてて、読んでいくと色々面白そうでした。

github.com