Integration
Overview
Use Axiom to manage just in time access to your GitHub repositories (repos), instead of maintaining permanent privileged access. Axiom does not manage GitHub organization roles.
Users use Axiom to:
Request to be assigned a role for one or more repos.
Request to be assigned to an existing GitHub team.
Once a request’s duration expires, Axiom automatically revokes the assigned permission.
You can also use Axiom to have a GitHub team be assigned a role for a repo, but this is more of an edge case when using Axiom (learn why).
Note!
With Axiom, you can have more than one role for a repo. Your actual access level will be that of the most privileged role:
Read -> Triage -> Write -> Maintain -> Admin.
Learn more about how Axiom manages GitHub permissions.
Notes for Axiom admins!
Axiom does not modify the roles a user has been assigned outside of Axiom. This means that even though a request was made (and approved) using Axiom, the user may in fact have more elevated permissions.
Learn about using Axiom’s Access Explorer to identify GitHub users', and teams' actual permissions.
Read more best practices.
Supported GitHub roles
Axiom supports only GitHub’s built-in roles ⬈: Read, Triage, Write, Maintain, and Admin. Axiom does not currently support GitHub custom roles.
Requesting repository-level access
Note: you will only see the repos and roles for which you have scope.
Choose GitHub as the System, and for Target choose the GitHub repo you want to access
From the Principal selector, choose the user or team that should receive the role for this repo.
Note: Axiom is not able to auto-select you as the Principal if GitHub does not expose your email, and/or if the email is not identical to the one with which you’re signed-in to Axiom.
From the Permission field, select the role that should be granted to the Principal
Note: any role already assigned to you through Axiom will be grayed out and disabled.
Press Submit, and wait for your request to be approved (by a human, or an automated Axiom workflow).
Once the request is approved, the selected user will be added to the Axiom-managed team that has this role; once the request expires, the user will be removed from that team. Learn more
Requesting to be added to a GitHub team
Choose GitHub as the System, and for Target choose the GitHub organization that contains the team you want to be added to
From the Principal selector, choose the user that should be added to the GitHub team
From the Permission field, select the GitHub team the user is to be added to
Press Submit, and wait for your request to be approved (by a human, or an automated Axiom workflow).
Once the request is approved, the selected user will be added to the selected team; once the request expires, the user will be removed from the selected team.
Github and Axiom scopes
When you select a GitHub organization as the Target in scopes, then users will be allowed to request/ approve requests for the organization, and all repos in that organization (you control whether a user is a requester or an approver via the *Assignments section of the scopes form).
How Axiom manages GitHub permissions
This section describes the inner workings of how Axiom actually manages the requested roles. It is intended for the technically curious, and is not a must-read in order to use the feature.
When you request a role for a repo (and that request is approved)
Axiom adds the defined Principal (the user or team for which the role was requested) to an Axiom-managed GitHub team that already has that role assigned to it.
For example, if you are approved for the Maintain role, then Axiom adds you to the axiom-maintain team.
The Axiom-managed teams are set as hidden, and are visible only to members of the team and to owners.
When the Duration of the request ends (the request expires), Axiom removes the Principal from that team.
Note!
You should never modify the Axiom-managed teams directly!
Do not add/ remove users, change the team’s roles, or its name.
Because approved requests grant access by addition to teams, you can have multiple active (approved) requests at the same time for the same repo, each with its own role. This allows you to have long standing permissions for the basic privilege that you actually require regularly, and to easily receive short-lived elevated role when you need. Once the request that provided the elevated role expires, you will still have the role provided by your non-expired long-term request.
When you request to be added to a GitHub team (and that request is approved)
Axiom adds the defined Principal to that team.
When the request expires, Axiom removes the Principal from that team.
Important!
If you were already assigned to the team prior to Axiom adding you to that team, then upon expiry you will no longer be a member of that team!
Best practices for using Axiom for managing GitHub permissions
Before you start using Axiom for GitHub permissioning, your GitHub users probably have standing (permanent) privileges assigned to them through a mixture of direct role assignments, and membership in teams that have role assignments.
Once you start using Axiom, you may discover that you and your users find it hard to maintain a clear mental model of who has what permissions when.
Example 1:
A user has a pre-existing direct assignment of Admin role for repo X.
S/he is then granted a temporary admin role for repo X through Axiom.
When the temporary Axiom-managed role expires, the user still has an Admin role.
This happens because Axiom does not directly assign roles to users, and because Axiom does not remove users’ existing pre-existing roles.
Example 2:
A user has a pre-existing membership in GitHub teams A, and B.
S/he is then granted a temporary membership in team B through Axiom.
When the temporary Axiom-managed team-membership expires, the user still has membership in team A, but does not have membership in team B.
This happens because Axiom does not remove users’ existing pre-existing group-memberships, but does remove Axiom-manage team memberships.
How to achieve true just in time least privilege using Axiom
The final model you will achieve is:
All role assignments are managed through Axiom.
All users have a long term Axiom-managed minimal role that they need for each repo (the baseline).
Users use Axiom to request elevated roles just in time as needed. When these roles expire, they continue having their baseline roles.
In order to achieve this, you will need to remove users’ existing GitHub-managed privileges. While this may sound daunting and/ or disruptive, it is actually not hard to achieve if done using small steps, as described here.
Start by focusing on the Admins in one team. You will first need to identify them. You can do this using the Axiom Access Explorer, with this predefined filter to start. Use the “See details” option from the three-dot menu to learn more about each finding.
Record which repos these users should be admins in, and proceed to remove these users from all teams through which they gain admin role to all repos, and remove all their direct admin role assignments for these repos. You will do this using GitHub’s built in tools.
Now, immediately create requests in Axiom (you can do it in a single bundle) for these users to be admins on these repos, and set the duration to 30 days. This step assumes you have set up scopes for them.
Approve the requests you created in the previous step. You have now replaced the permanent admins of one team to be Axiom-managed instead of GitHub-managed.
You can now educate these users that in 30 days their admin privilege will expire, and that after that they should request it just in time when they need it, using Axiom. You can also create automated Workflows for handling these requests (for instance, something like “if user is X, Y, or Z, and role is admin, and repo is A or B, then auto-approve but set duration to max 1 day”).
You can now repeat this process for other teams, and lesser roles.
If you haven’t already, be sure to read how Axiom manages GitHub permissions.