Main Page

Access rights

Anonymous users

You'll need to have an account created for you. If you currently have SVN access, then you have an account, but need to have it linked to Labs. We are still working out the account activation process, but hope to have it done soon.

Logged in users

After creating an account, you can:

• Add and manage your public SSH keys

Once you add a key, you'll be able to log into an instance in the main project testlabs. It may take up to 30 minutes for your key to be propagated to all instances.

If you'd like to create instances, you'll need to have an admin add you to a project, and to the sysadmin role in that project.

You can make queries for nova resources; currently Nova instances have semantic properties enabled.

After logging in, you can also access Gerrit; if you wish to do git checkouts of the puppet repositories, you'll need to log into Gerrit, and add your SSH key there as well. Note: it would be nice if Gerrit could use LDAP for its SSH keystore, instead of its database; I've opened a bug for this, if you'd like to help, please add that feature to Gerrit!

Admins

Wiki Admin

If you are a wiki admin, you can:

• Create/delete Nova projects and manage project and project role membership
• Manage global role membership.
• Manage sudo policies.

Net Admins

If you are a NetAdmin, you can:

• Allocate and associate public IP addresses, and add public DNS entries to instances
• Manage security groups and rules.

Sys Admins

If you are a sysadmin, you can:

• Create or manage instances.
• Create or manage volumes.

After creating an instance, you'll get an email notifying you that it is ready to be logged into. If you did not add an SSH key prior to creating the instance, you'll need to wait until your key is propagated to the instances (which can take an additional 30 minutes).

Cloud Admins

In addition to all actions that sysadmins and netadmins, you can:

• Create or manage DNS domains.

Access FAQ

• Q: I was added to a group that gives me access to something in git, but it isn't working, what's wrong?
  • A: Once you have been added to the group, you need to log out of gerrit, then back in. Gerrit pulls its groups from LDAP, but caches them. Logging out, then back in re-synchronizes your groups, and thus clears the cache.

Git/Gerrit and the puppet repositories

Note: Access is currently limited to staff developers and operations engineers. This will change soon.

Set up your ssh key in Gerrit

Log into the web interface for gerrit. Click on Settings then SSH Public Keys then add your key.

Checking out the puppet repositories

We have the following main repositories and branches:

• operations/puppet
  • production (HEAD)
    • used in production
  • test
    • used in the testlabs project
• operations/private
  • master (HEAD)
    • only used in testlabs project

To check out the production branch of the puppet repo, you can clone it like so (if they're different, shell-username is your unix shell name, not the wiki username.):

git clone ssh://<shell-username>@gerrit.wikimedia.org:29418/operations/puppet.git

To check out the test branch of the puppet repo, you can clone it like so:

git clone ssh://<shell-username>@gerrit.wikimedia.org:29418/operations/puppet.git -b test

Git configuration required to commit

Use git-setup

After the initial clone of the git repository, you can use the git-setup script. It will set your user name, email, and will pull hooks required for proper use of gerrit.

...or do initial git configuration manually

First, you should set your name and email address in your local git configuration. The email address and wiki username are the same as what you use to log into this wiki:

git config --global user.email "<email-address>"
git config --global user.name "<wiki-username>"

Next you'll need to add a commit-msg hook to your local repository. This hook is required for pushing changes to the Gerrit server.

curl "https://gerrit.wikimedia.org/r/tools/hooks/commit-msg" > .git/hooks/commit-msg && chmod u+x .git/hooks/commit-msg

Updating your local repository

After you do the initial repository clone, git will automatically set up a remote tracking branch for you. You simply need to fetch/merge or pull:

git fetch
git diff origin/<branch>
git merge origin/<branch>

or:

git pull

Making changes

After cloning the repo, you can make changes the normal git way:

<make changes>
git add <newfiles>
git commit -a

After doing so, you'll need to push the changes for review; for instance, here's how to push to the test branch of the puppet repository:

git push ssh://<username>@gerrit.wikimedia.org:29418/operations/puppet HEAD:refs/for/test

You can shorten that by adding a remote:

git remote add puppet ssh://<username>@gerrit.wikimedia.org:29418/operations/puppet

Now you can push for review like so:

git push puppet HEAD:refs/for/test

You can shorten this further by making an alias:

git config alias.push-for-review-test "push puppet HEAD:refs/for/test"

Now you can push for review like so:

git push-for-review-test

Here's the alias for production:

git config alias.push-for-review-production "push puppet HEAD:refs/for/production"

Also, staff operations members have the ability to (but shouldn't!) skip the review step; to do so, simply do a push:

git push puppet

Here's the remotes and aliases for the private repo:

git remote add private ssh://<username>@gerrit.wikimedia.org:29418/operations private
git config alias.push-for-review-private "push puppet HEAD:refs/for/master"

Review

Review your change (or someone elses!) in Gerrit.

1. Go to https://gerrit.wikimedia.org
   • if it's your own change, you will see it listed on the first screen
   • if it's someone else's, click on 'All' then 'open' to see all unreviewed changes
2. click on the change you want to review
3. click on "Diff all side by side" to examine the diff
   • this will open each changed file in a new tab
4. when you're done reviewing, go back to the parent tab
5. click 'Review'
   1. check +1 Verified
   2. check +2 Reviewed
   3. click "Publish and Submit"

You're done! The change is now merged.

Making the changes live in puppet

Test

Changes merged in the test branch will go live in puppet within a minute.

Production

Public repo

Changes for production need to be pulled manually; this is done for security purposes. Here's the procedure you should use:

cd ~/puppet
# the next command can be pulled from gerrit; look at the patch set,
# under "Download", use "checkout". The refid will look something like: refs/changes/22/22/1
git fetch puppet <refid>
    Example: git fetch puppet refs/changes/22/22/1
git diff HEAD FETCH_HEAD | less
git merge FETCH_HEAD

Private repo

cd ~/private
<make changes>
git add <newfiles>
git commit -a

On commit, the changes will go live.

Merging changes from test into production

Merging specific changes:

git pull
git checkout -b <refid> origin/test
git checkout production
git merge --squash <refid>
git commit -a
git push-for-review-production

Merging everything from test to production:

git pull
git checkout -b test origin/test
git checkout production
git merge --squash origin/test
git commit -a
git push-for-review-production

Books, guides, tutorials, documentation, etc.

• Gerrit documentation
• Community git book
• Git for Subversion users
• Why to fetch/merge instead of pull
• Git workflow