GitHub

GitHub only provides an interface to sync data from LDAP, and even then only if using the enterprise version. Since Void is an open source project and isn't using this option, we don't sync data. The organization at github.com/void-linux has very little state, primarily users and groups.

Groups

There are currently three groups that gate access into GitHub resources:

pkg-committers

Members of this group have broad commit access and can generally push to any Void owned repo. The primary reason for people to gain access to this group is to be able to push package templates. Access to this group should be assumed to contain the ability to trigger builds that will eventually be signed for inclusion in the main repo.

void-ops

Membership into this group is highly restricted and should generally not be authorized without a signoff from an infrastructure lead or maldridge@. This group gates access to the infrastructure repo itself, and is restricted to prevent accidental breakage from pushing something that is later pushed by automation that performs change detection against the state of the repo.

doc-writers

Members of this group have access to push changes into the void-docs repository which is responsible for holding all content that appears on our handbook.

Adding and Removing Members

Adding and removing members takes place in github_members.tf. This file contains a stanza for every user and every group they are in. To change membership of a group add or remove a stanza, then apply the state transformation to GitHub.

This file is manually formatted, take care to maintain lexical sort ordering and indentation. For example if a new committer with username voidfu was to be added, a new stanza as follows would be added to the file:

resource "github_team_membership" "pkg-committers_voidfu" {
  team_id = "${github_team.pkg-committers.id}"
  role = "maintainer"
  username = "voidfu"
}

The name placed in the resource line should always be lower case. The name that appears in the username should be an exact match for the username shown on the user's profile page.

Pushing state changes

Pushing a state change can only be done by organization owners. To request a push of terraform state, request action from one of:

* the-maldridge
* gottox
* duncaen

It is very important that only one push be in progress at a time. To this end, anyone making a push should endeavor to determine no other changes are in motion, manual or terraformed.

Authenticating to GitHub for Push

Github needs authentication to authorize the push. This takes the format of a personal access token. The token must contain sufficient permissions to add and remove people from the organization, add and remove repositories, and add and remove groups. The token should be stored in the environment variable GITHUB_TOKEN.

Pushing the Changes

Pushing the changes is done in two phases. The first phase is a planning phase. In this phase call terraform as shown:

$ terraform plan

Verify that the output is sane, it will provide a diff of any action that terraform wants to take. This should be very simple to understand what is going to happen because you shouldn't push large changes, instead prefer to push incremental changes in succession.

When you are satisfied with the planned actions, apply them:

$ terraform apply

You'll be asked to confirm the application of state. If you're satisfied, apply the state. Terraform is not like Ansible, be careful that you don't remove people from the organization or clear permissions that you can't put back without assistance.