Skip to content

Run Docker in Rootless Mode to Prevent Permission Errors

License

Notifications You must be signed in to change notification settings

ScribeMD/rootless-docker

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Repository files navigation

rootless-docker

GitHub Action: Try Me Rootless Docker Test Workflow Status Copy/Paste: 0%

Automated Updates: Renovate Package Management: Poetry Git Hooks: pre-commit Commit Style: Conventional Commits Releases: Semantic Versioning Code Style: Prettier Code Style: EditorConfig Editor: Visual Studio Code

Run Docker in Rootless Mode to Prevent Permission Errors

GitHub-hosted (and many self-hosted) runners use rootful Docker, but the runner itself does not run as root. As described in actions/runner#434, files created by Docker containers are hence owned by root, resulting in permission errors when the runner attempts to clean up checked out repositories. This action efficiently prevents those permission errors by running Docker in rootless mode so that all files are owned by the runner user. This approach has many benefits as it is:

  • safer than elevating the runner to root
  • less brittle than changing the ownership/permissions of or deleting files
  • simpler than other ways of running rootless Docker
  • and fast (~15 seconds on GitHub-hosted runner ubuntu-22.04)

Docker's documentation discusses rootless mode in detail. If you are running a supported Linux distribution locally, you can follow the steps there to use rootless mode. If you aren't sure, you can ask Docker whether it is in rootless mode:

docker info --format "{{ .ClientInfo.Context }}"

Usage

  • Add the following step before your first use of Docker:

    - name: Use Docker in rootless mode.
      uses: ScribeMD/rootless-docker@0.2.2

Supported Runners

  • Tested on ubuntu-22.04
  • Probably works on ubuntu-18.04 and ubuntu-20.04
  • May work on future versions of Linux
  • Definitely doesn't work on Windows or macOS since Docker only offers rootless mode on Linux

Permissions

No permissions are required.

Changelog

Please refer to CHANGELOG.md.