English | 日本語

Manage Linux users with your GitHub Organization/Team

octopass brings GitHub's team management to your Linux servers. No more manually managing /etc/passwd or distributing SSH keys — just add users to your GitHub team, and they're ready to SSH into your servers.

🔑 SSH keys from GitHub — Users authenticate with their GitHub SSH keys. No key distribution needed.

👥 Team-based access — Grant server access by GitHub team membership. Add to team = server access.

🔄 Always in sync — User lists and keys are fetched from GitHub API. Remove from team = access revoked.

🛡️ Secure by design — No passwords stored on servers. Authentication via GitHub personal access tokens.

📦 Zero dependencies — Single static binary. No runtime dependencies beyond libc.

octopass works as a NSS (Name Service Switch) module, seamlessly integrating GitHub teams into Linux user management:

• getpwnam() / getpwuid() → Returns GitHub team members as Linux users
• getgrnam() / getgrgid() → Returns GitHub team as a Linux group
• SSH AuthorizedKeysCommand → Fetches user's SSH public keys from GitHub

For RHEL/CentOS/Amazon Linux:

curl -s https://packagecloud.io/install/repositories/linyows/octopass/script.rpm.sh | sudo bash
sudo yum install octopass

For Debian/Ubuntu:

curl -s https://packagecloud.io/install/repositories/linyows/octopass/script.deb.sh | sudo bash
sudo apt-get install octopass

Build from source:

# Requires Zig 0.15+
zig build -Doptimize=ReleaseSafe

# Install the NSS library
sudo cp zig-out/lib/libnss_octopass.so.2.0.0 /usr/lib/x86_64-linux-gnu/
sudo ln -sf libnss_octopass.so.2.0.0 /usr/lib/x86_64-linux-gnu/libnss_octopass.so.2

# Install the CLI
sudo cp zig-out/bin/octopass /usr/bin/

Create /etc/octopass.conf:

# GitHub personal access token (requires read:org scope)
Token = "ghp_xxxxxxxxxxxxxxxxxxxx"

# Your GitHub organization
Organization = "your-org"

# Team to grant access (team slug)
Team = "your-team"

# User configuration
UidStarts = 2000
Gid = 2000
Home = "/home/%s"
Shell = "/bin/bash"

# Cache settings (seconds)
Cache = 300

Edit /etc/nsswitch.conf:

passwd: files octopass
group:  files octopass
shadow: files octopass

Edit /etc/ssh/sshd_config:

AuthorizedKeysCommand /usr/bin/octopass %u
AuthorizedKeysCommandUser root
UsePAM yes
PasswordAuthentication no

Restart SSH:

sudo systemctl restart sshd

# Get SSH keys for a user
octopass alice

# List all users (passwd format)
octopass passwd

# Get specific user entry
octopass passwd alice

# List group entry
octopass group

# PAM authentication (reads token from stdin)
echo $GITHUB_TOKEN | octopass pam alice

Instead of GitHub teams, you can use repository collaborators:

Token = "ghp_xxxxxxxxxxxxxxxxxxxx"
Owner = "your-org"
Repository = "your-repo"
Permission = "write"  # Only collaborators with write access

For shared accounts (like deploy or admin), you can allow any team member to authenticate:

SharedUsers = ["deploy", "admin"]

When someone SSHs as deploy, all team members' SSH keys are accepted.

Configuration can be overridden with environment variables:

• OCTOPASS_TOKEN
• OCTOPASS_ENDPOINT
• OCTOPASS_ORGANIZATION
• OCTOPASS_TEAM
• OCTOPASS_OWNER
• OCTOPASS_REPOSITORY

This is a Zig rewrite of the original C implementation. Benefits:

• Memory safety — Compile-time checks prevent common vulnerabilities
• No dependencies — Zig's stdlib replaces libcurl and jansson
• Easy cross-compilation — Build for any target from any host
• Integrated testing — Built-in test framework
• Readable code — Cleaner than C, without sacrificing performance

MIT