Github Actions Self-Hosted Runner: Cannot Access /usr/local/lib/ Directory

[john-bullwinkle]

Why are you starting this discussion?

Question

What GitHub Actions topic or product is this about?

Actions Runner

Discussion Details

I am using self-hosted github actions runner and it is trying to access a 3rd party library (libexanic) stored under "/usr/local/lib/".
The exact error I got is /usr/bin/ld: cannot find -lexanic: No such file or directory collect2: error: ld returned 1 exit status, which after digging, the linker complains about unable to find libexanic stored under /usr/local/lib/ due to permission denied. Running CMake build in my local vscode does trigger this issue, as myself user is added to the group "exanic-user" and have the full access to /usr/local/lib.

There are 3 paths I could tackle the problem:

1. [My current struggling] Add the "runner" to a group "exanic-user", which by default has the access to /usr/local/lib/. However I could not add the "runner" to this group. I tried the addition step in run.sh and it just add myself instead of the runner to the group. In the workflow it simply cannot find the group. My commands in the worflow yml and the console responses are listed below:

$ whoami
runner

$ ls -l /etc/group || echo "unable to access /etc/group"
-rw-r--r-- 1 root root 1010 Sep 7 22:09 /etc/group

$ cat /etc/group | grep exanic-user || echo "unable to access exanic-user group info"
unable to access exanic-user group info

$ sudo usermod -a -G exanic-user $(whoami) || echo "unable to add user to exanic-user group"
usermod: group 'exanic-user' does not exist
unable to add user to exanic-user group

It seems the runner is created in this github actions sandbox environment, and cannot access the group info outside it. I suppose there are some config file that can pre-load some settings when creating the runner, but could not locate them.

2. Lots of people (and chatbots) suggest to chmod the /usr/local/lib to allow everyone to access it, but since this is a shared utility folder, which is also used by others with some delicate permission level separations. Allowing everyone to access it might create some unwanted consequences and break this delicate permission design.

3. Copy over the linked file to the repo, and try to make the build succeed. This just adds extra libraries that should not be tracked in the repo, and creates extra dependencies as any update to exanic code needs to be manually pulled into the repo. Therefore, I am hesitate to do that.

Please suggest how to go from here, especially for the path #1. Any help is appreciated, thank you!

[malewicz1337]

Self-hosted runner operates in an isolated environment and cannot see the exanic-user group because:

1. The runner process itself runs under a specific user context (typically created during runner setup)
2. Group membership changes require the user session to be restarted to take effect
3. The runner user may not have been properly configured with system group access

Recommended Solutions

Option 1: Add Runner User to Group During Runner Installation

When you initially set up the self-hosted runner, the installation creates a user. You need to add this user to the group before starting the runner service.

# Find the runner user (usually 'runner' or your username)
whoami

# Stop the runner service
sudo ./svc.sh stop

# Add the runner user to the exanic-user group
sudo usermod -a -G exanic-user runner

# Verify the addition
groups runner

# Restart the runner service
sudo ./svc.sh start

Important: Group membership changes only take effect after the user logs out and back in, or the service restarts.

Option 2: Modify Linker Search Path in Your Workflow

Instead of changing permissions, tell the linker where to find the library:

- name: Build with CMake
  run: |
    export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
    cmake --build build
  env:
    LDFLAGS: "-L/usr/local/lib"

Or set it in your CMakeLists.txt:

link_directories(/usr/local/lib)

Option 3: Use Sudo in Workflow (If Runner Has Sudo Access)

If your runner user has sudo privileges without password:

- name: Build with library access
  run: |
    sudo -E cmake --build build

The -E flag preserves environment variables.

Option 4: Grant Read-Only Access to Specific Files

Instead of opening up the entire /usr/local/lib, create a symbolic link or grant specific read access:

# As root or with sudo
sudo setfacl -m u:runner:rx /usr/local/lib
sudo setfacl -m u:runner:r /usr/local/lib/libexanic.*

This uses ACLs to grant only the runner user read/execute permissions without changing the overall directory permissions.

Debugging Steps

Check the runner's actual user and group memberships:

- name: Debug runner context
  run: |
    whoami
    id
    groups
    ls -la /usr/local/lib/ | grep exanic || echo "Cannot access library"
    getent group exanic-user || echo "Group not visible"

Why Your Current Approach Doesn't Work

The commands in your workflow run inside the runner's process, which already has its groups assigned. Running usermod in the workflow can't change the groups of an already-running process.

My Recommendation

Use Option 1 + Option 2 combined:

1. Properly configure the runner user with group membership during installation
2. Add library path configuration to your workflow as a safety measure

[john-bullwinkle]

Thanks for the reply, here are my results, and it seems none of the options worked out.

Option 1: Add Runner User to Group During Runner Installation
This option does not seem to be working. I modified the run.sh in github actions script and try to run it. Under $ whoami it prints my user name rather than the runner. Subsequently, the script could not add the runner user to the exanic-user group as it could not find the runner user, only my user name. I run the github action via this command, please let me know if there is something I could do.

$ ./config.sh --url https://github.com/{my_github_action_link & token} 
$ ./run.sh

Option 2: Modify Linker Search Path in Your Workflow
The same error occurs when adding the extra LDFLAGS with the cmake build. It seems like runner cannot access this directory.

Option 3: Use Sudo in Workflow (If Runner Has Sudo Access)
I don't think runner should have any sudo access... It's main task is to build the project properly

Option 4: create a symbolic link
/usr/bin/ld: cannot find -lexanic: No such file or directory
collect2: error: ld returned 1 exit status

[ashmeet07]

✅ Solution for Runner Permission and Group Access (Path #1)

You are absolutely correct: the core of the problem is that group membership is assigned to a user/process upon login or service start. Running usermod inside a running GitHub Actions workflow step cannot change the groups of the already-running runner process.

The recommended solution for Path #1 is to change the runner user's group membership externally and then restart the runner service.

Step 1: Add the Runner User to the Group (External to Workflow)

These steps must be performed on the self-hosted machine's console where the runner is installed, not in a GitHub Actions workflow .yml file.

1. Stop the Runner Service:

   sudo ./svc.sh stop

2. Verify the exanic-user group exists (if it doesn't, you must create it first, assuming it wasn't visible due to context):

   getent group exanic-user
   # If the group doesn't exist, create it:
   # sudo groupadd exanic-user

3. Add the Runner User to the Group: (Assuming your runner user is named runner or the name of the user who executed ./run.sh to install the service):

   RUNNER_USER=$(whoami) # Use the user who runs the runner service
   sudo usermod -a -G exanic-user $RUNNER_USER

4. Verify the User's New Groups:

   groups $RUNNER_USER
   # You should now see 'exanic-user' listed in the output.

5. Restart the Runner Service: This step is crucial, as it forces the runner process to start with the new group membership.

   sudo ./svc.sh start

Step 2: Ensure the Linker Can Find the Library (Workflow Configuration)

Even after fixing permissions, the linker (ld) might not check /usr/local/lib by default. You should ensure the library path is correctly specified in your build step to resolve the original error:

- name: Build with CMake
  run: |
    # Add the library directory to the linker search path
    export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
    
    # Run your build command
    cmake --build build --config Release
  
  # Or use LDFLAGS/CXXFLAGS if your build system honors them
  env:
    LDFLAGS: "-L/usr/local/lib"
    # CXXFLAGS: "-I/usr/local/include" # if you also had include path issues

By combining the external permission fix (Step 1) with the explicit linker path configuration (Step 2), you ensure the runner has both the necessary access and the correct path information to complete the build successfully.

[john-bullwinkle]

Thanks for the reply, here are my results, and it seems neither of the option worked out... Sadly.

Option 1: Add Runner User to Group During Runner Installation
This option does not seem to be working. I modified the run.sh in github actions script and try to run it. Under $ whoami it prints my user name rather than the runner. Subsequently, the script could not add the runner user to the exanic-user group as it could not find the runner user, only my user name. I run the github action via this command, please let me know if there is something I could do.

$ ./config.sh --url https://github.com/{my_github_action_link & token} 
$ ./run.sh

Option 2: Modify Linker Search Path in Your Workflow
The same error occurs when adding the extra LDFLAGS with the cmake build. It seems like runner cannot access this directory.

[github-actions[bot]]

🕒 Discussion Activity Reminder 🕒

This Discussion has been labeled as dormant by an automated system for having no activity in the last 60 days. Please consider one the following actions:

1️⃣ Close as Out of Date: If the topic is no longer relevant, close the Discussion as out of date at the bottom of the page.

2️⃣ Provide More Information: Share additional details or context — or let the community know if you've found a solution on your own.

3️⃣ Mark a Reply as Answer: If your question has been answered by a reply, mark the most helpful reply as the solution.

Note: This dormant notification will only apply to Discussions with the Question label. To learn more, see our recent announcement.

Thank you for helping bring this Discussion to a resolution! 💬

[mom231086-commits]

What's wrong with this ??? Obed.. what is this

[github-actions[bot]]

🕒 Discussion Activity Reminder 🕒

This Discussion has been labeled as dormant by an automated system for having no activity in the last 60 days. Please consider one the following actions:

1️⃣ Close as Out of Date: If the topic is no longer relevant, close the Discussion as out of date at the bottom of the page.

2️⃣ Provide More Information: Share additional details or context — or let the community know if you've found a solution on your own.

3️⃣ Mark a Reply as Answer: If your question has been answered by a reply, mark the most helpful reply as the solution.

Note: This dormant notification will only apply to Discussions with the Question label. To learn more, see our recent announcement.

Thank you for helping bring this Discussion to a resolution! 💬