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.
GitLab support — Use GitLab groups, subgroups or projects instead of GitHub teams.
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 usersgetgrnam()/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 octopassFor Debian/Ubuntu:
curl -s https://packagecloud.io/install/repositories/linyows/octopass/script.deb.sh | sudo bash
sudo apt-get install octopassBuild from source:
# Requires Zig 0.16+
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 = 300Edit /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| Option | Description | Default |
|---|---|---|
Provider |
github or gitlab |
github |
Token |
GitHub or GitLab personal access token | (required) |
Organization |
GitHub organization name | (required for GitHub team mode) |
Team |
GitHub team slug | (required for team mode) |
Owner |
Repository owner (for collaborator mode) | - |
Repository |
Repository name (for collaborator mode) | - |
Permission |
Required permission: read, write, admin |
write |
Endpoint |
GitHub API endpoint | https://api.github.com/ |
UidStarts |
Starting UID for GitHub users | 2000 |
Gid |
GID for the team group | 2000 |
Group |
Linux group name (GitLab: group path) | team name |
Subgroup |
GitLab subgroup (for GitLab) | - |
Project |
GitLab project (for GitLab) | - |
Home |
Home directory pattern (%s = username) |
/home/%s |
Shell |
Default shell | /bin/bash |
Cache |
Cache TTL in seconds (0 = disabled) | 500 |
Syslog |
Enable syslog logging | false |
SharedUsers |
Users who get all team members' keys | [] |
Instead of GitHub teams, you can use repository collaborators:
Token = "ghp_xxxxxxxxxxxxxxxxxxxx"
Owner = "your-org"
Repository = "your-repo"
Permission = "write" # Only collaborators with write accessSet Provider to gitlab to use GitLab instead of GitHub. The token needs the read_api scope, and Endpoint defaults to https://gitlab.com/api/v4/ (set it for self-managed GitLab). With GitLab, Group is the GitLab group path, and members are taken from one of the following:
Provider = "gitlab"
Token = "glpat-xxxxxxxxxxxxxxxxxxxx"
# Members of a group
Group = "your-group"
# Members of a subgroup (your-group/your-subgroup)
Group = "your-group"
Subgroup = "your-subgroup"
# Members of a project (your-group/your-project)
Group = "your-group"
Project = "your-project"
Permission = "write" # read = Reporter, write = Developer, admin = MaintainerPermission applies to project members, and maps to GitLab access levels. The Linux group name defaults to the subgroup, project or group name.
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_PROVIDEROCTOPASS_TOKENOCTOPASS_ENDPOINTOCTOPASS_ORGANIZATIONOCTOPASS_TEAMOCTOPASS_OWNEROCTOPASS_REPOSITORYOCTOPASS_PERMISSIONOCTOPASS_GROUP(GitLab)OCTOPASS_SUBGROUP(GitLab)OCTOPASS_PROJECT(GitLab)
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