Repositories, groups and access

Decide who can build from a repository, manage permission groups and read who holds what, from the terminal.

Two command groups cover access. isogrid repos decides who in the organization can use a connected repository. isogrid iam lists members and manages permission groups. Both do what the console's access pages do, so they can be scripted: onboarding a team, or checking in review who holds what.

The ideas behind them are explained in Roles, permission groups and access and Git repositories. This page is the commands.

Repositories: isogrid repos

repos also answers to repo and repositories. A repository is named by its full name (acme/api, or platform/backend/api for a GitLab project in nested groups), by a URL pasted from the browser, or by its id.

Listing them

isogrid repos list [--provider github|gitlab] [--search TEXT] [--json]

REPOSITORY         PROVIDER  ACCESS                   OWNER               YOU
acme/api           github    organization             samir@acme.example  view,create-app,deploy,update,delete,share
acme/website       github    private (default)        aziz@acme.example   view,create-app,deploy
platform/billing   gitlab    administrators           lina@acme.example   view

• ACCESS is who can reach the repository: private, administrators or organization. (default) means the repository has no setting of its own and follows its connection's default.
• OWNER is the member whose GitHub or GitLab account the repository comes through. They decide who else may use it.
• YOU is what you may do with it, without the repo: prefix.

Only repositories you can see are listed. A colleague's private repository is not listed and does not answer to its name either, unless they grant it to you.

Setting who can reach one

isogrid repos access <repo> [--visibility private|administrators|organization|inherit]
                            [--org-capabilities CAP,...]

--org-capabilities is what every member holds under organization. Without it, members may view it, create applications from it, deploy them and change their configuration, but not delete other people's applications and not share it further.

Only the owner can change this, or an administrator once the owner has left the organization.

# Open the API to everyone, but only to deploy what exists
isogrid repos access acme/api --visibility organization \
  --org-capabilities repo:view,repo:deploy

# Close it again
isogrid repos access acme/api --visibility private

Granting it to a member or a group

isogrid repos grant <repo> (--member EMAIL | --group SLUG) [--preset NAME] [--capabilities CAP,...]

Give a preset, a list of capabilities, or both; the union is granted.

No preset includes repo:share: deciding who else gets in stays with whoever connected the account. You can grant only capabilities you hold yourself.

# A contractor who may deploy the applications built from the API
isogrid repos grant acme/api --member contractor@partner.example --preset repo-deployer

# The QA group may see the code and redeploy, but not create applications
isogrid repos grant acme/api --group qa --capabilities repo:view,repo:deploy

A grant covers every application built from the repository, including ones created after the grant.

Seeing and withdrawing grants

isogrid repos grants <repo> [--json]
isogrid repos revoke <repo> <grant-id|email|group>

isogrid repos grants acme/api
# ID        SUBJECT  WHO                          CAPABILITIES              GRANTED
# 9c1e4a2b  user     contractor@partner.example   view,create-app,deploy    3 days ago
# 51aa07fe  group    qa                           view,deploy               1 hour ago

isogrid repos revoke acme/api contractor@partner.example
isogrid repos revoke acme/api 51aa

A grant is named by the start of its id (four characters or more), or by the email or group it was given to. You can withdraw only a grant that gives no more than you hold yourself.

Members and groups: isogrid iam

Members

isogrid iam members [--search TEXT] [--role owner|administrator|developer]
                    [--status active|suspended] [--group SLUG] [--limit N] [--page N] [--json]

isogrid iam members --role administrator
isogrid iam members --group deployers
isogrid iam members --search @partner.example --status active

Results are paged, 50 at a time by default and at most 200. Inviting members and changing their role is done in the console.

Groups

isogrid iam groups list
isogrid iam groups get <group>
isogrid iam groups create --name NAME [--slug SLUG] [--description TEXT] [--permissions P,...] [--inherits GROUP,...]
isogrid iam groups update <group> [--name NAME] [--description TEXT] [--permissions P,...] [--inherits GROUP,...]
isogrid iam groups delete <group> [--yes]
isogrid iam groups add-member <group> <email>
isogrid iam groups remove-member <group> <email>

groups also answers to group.

get shows a group's own permissions, the ones it inherits, and its members. It is the command to run when you want to know what joining a group would actually give someone.

create takes organization permissions and the slugs of groups to inherit from. Members of the new group hold its own permissions and everything its parents hold, transitively.

update changes only what you give, but --permissions and --inherits replace the whole list. --inherits "" clears it.

Built-in groups cannot be changed or deleted. To adjust one, create your own group that inherits from it and adds what you need.

delete asks first, and needs --yes without a terminal. Members stay in the organization but lose what the group gave them, and grants made to the group are removed with it.

Changing groups needs the iam:manage permission, and every change is checked against what you hold: you cannot create a group with a permission you lack, make a group inherit from one that holds more than you, or add someone to such a group.

# Release managers: deploy anything, and read billing
isogrid iam groups create --name "Release managers" \
  --inherits deployers --permissions billing:read

isogrid iam groups add-member release-managers lina@acme.example
isogrid iam groups get release-managers

What can be granted

isogrid iam permissions [--json]

Prints every organization permission, marking the ones only the owner can hold; then, for each kind of resource, its capabilities and the presets that bundle them. It is the reference for the values --permissions, --capabilities and --org-capabilities accept, and it always matches the platform you are signed in to.

Scripting access

Every listing takes --json, which prints the API's response on standard output. Messages go to standard error.

A periodic review of who can build from which repository:

for repo in $(isogrid repos list --json | jq -r '.[].full_name'); do
  echo "== $repo"
  isogrid repos grants "$repo"
done

Onboarding a team from a file of email addresses:

while read -r email; do
  isogrid iam groups add-member deployers "$email"
done < new-team.txt

Delegated credentials and access commands

A CLI credential only carries iam:manage and member:manage if you ticked them when you approved it; they are off by default. Without iam:manage, the iam groups commands that change something are refused while the listings still work.

Granting and revoking on a repository does not depend on iam:manage: it depends on holding repo:share on that repository, which its owner always does.

Edge cases worth knowing before you meet them

"is not a repository you have been given access to". Holding nothing on a repository looks the same as it not existing, so a private repository cannot be discovered by guessing its name. Ask its owner for access.

"You cannot grant capabilities you do not hold yourself". You tried to give more than you have. The error lists what is missing.

"These permissions belong to the owner alone". Appointing administrators and editing the organization's legal details cannot be put in a group, by anyone.

"A group cannot inherit from itself, even indirectly". The inheritance you asked for would close a loop.

repos access is refused on a repository you administer. Administrators reach repositories opened to them, but the choice of who else gets in stays with the person who connected the account while they are still a member.