Project: treestatus

Contact:Rok Garbas, (backup Release Engineering)

TreeStatus is a relatively simple tool to keep track of the status of the trees at Mozilla.

A tree is a version-control repository, and can generally be in one of three states: open, closed, or approval-required. These states affect the ability of developers to push new commits to these repositories. Trees typically close when something prevents builds and tests from succeeding.

The tree status tool provides an interface for anyone to see the current status of all trees. It also allows “sheriffs” to manipulate tree status.

Start developing

0. Requirements

You’ll need:

  1. A Taskcluster account
  2. Docker installed on your machine

1. Taskcluster secret

Once logged on Taskcluster, please check that you can view the contents of the Taskcluster secret : repo:github.com/mozilla-releng/services:branch:master.

This secret holds the configuration for all the services, you can look at the treestatus/api section for more details.

If you don’t have access to that secret, or you need to make some changes to it, you can create a new secret under the “garbage” namespace (publicly visible to anyone); and use its name everywhere the master secret is mentioned in this documentation.

For example, you can create a secret called garbage/LOGIN/treestatus-api-dev with this value:

common:
  APP_CHANNEL: master
  AUTH_DOMAIN: auth.mozilla.auth0.com
  SECRET_KEY_BASE64: gDs52OnoHp6YPR7KTQCCC7jGK7PfS0Yn
treestatus/api:
  AUTH_REDIRECT_URI: 'https://localhost:8010/login'
  AUTH_CLIENT_ID: dummy
  AUTH_CLIENT_SECRET: dummy

Just replace LOGIN with your username (e.g. michel);

2. Taskcluster client

You need to create a Taskcluster client to access above created secrets.

Use the form to create a new client in your own namespace (the ClientId should be pre-filled with mozilla-auth0/ad|Mozilla-LDAP|login/, simply add an explicit suffix, like treestatus-api-dev)

Add an explicit description, you can leave the Expires setting into the far future.

Add the Taskcluster scope needed to read the secret previously mentioned: secrets:get:repo:github.com/mozilla-releng/services:branch:master (or secrets:get:garbage/michel/treestatus-api-dev if you’re using your own secret).

To summarize, you need to setup your client (if your login is michel), like this:

Key Value
ClientId mozilla-auth0/ad|Mozilla-LDAP|michel/treestatus-api-dev
Description My own treestatus/api dev client
Client Scopes secrets:get:garbage/michel/treestatus-api-dev

Warning

Save the access token provided by Taskcluster after creating your client, it won’t be displayed afterwards.

3. Project shell

Run the following (where XXX is the Taskcluster access token):

./please shell treestatus/api \
  --taskcluster-secret="garbage/michel/treestatus-api-dev" \
  --taskcluster-client-id="mozilla-auth0/ad|Mozilla-LDAP|michel/treestatus-api-dev" \
  --taskcluster-access-token="XXX"

Once the initial build finishes, you should get a green development shell, running in /app/src/treestatus/api.

4. Run project in development mode

Run the following (where XXX is the Taskcluster access token):

./please shell treestatus/api \
  --taskcluster-secret="garbage/michel/treestatus-api-dev" \
  --taskcluster-client-id="mozilla-auth0/ad|Mozilla-LDAP|michel/treestatus-api-dev" \
  --taskcluster-access-token="XXX"

Giving permission/roles to Sherrifs to close/open trees

A common request one administrator of treestatus would receive is to give permission for new

Certain JSON API endpoints are protected by Taskcluster scopes (for details which endpoint is protected by you can look at api.py). Those scopes (permissions) are grouped in two roles:

  1. Admin role

Administrator role has all the permissions (scopes) that are available. Administrator can create, update and remove trees. By default this role is assigned to everybody that is in vpn_sheriff LDAP group.

To assign admin role to certain user/group you need to add assume:project:releng:treestatus/admin scope to that user/group.

Roles / Clients with admin role are listed here.

  1. Sheriff role

Sheriff role the permissions (scopes) to update status of the trees and to revert those updates. This role is usually given to sheriff’s deputies to be able to close/open certain trees.

Roles / Clients with admin role are listed here: https://tools.taskcluster.net/auth/scopes/assume%3Aproject%3Areleng%3Atreestatus%2Fsheriff

Troubleshooting

In case of an incident this five steps that should help you narrow down the problem.

  1. Look at Heroku metrics to get birds view on the running application.
  2. There might be some problems with Heroku. Make sure to also check their status page
  3. Check if there is any unsual high count of errors collected in Sentry.
  4. To see more logs (from the past) look at Papertrail.
  5. Sometimes restarting an application might solve the issue (at least temporary). Once you restart the application also verify that it is working correctly (follow instructions below).

Deploying

treestatus is a Flask application deployed to Heroku. Please follow the Heroku deployment guide how to manually deploy hotfixes.

The architecture

blockdiag URL: https://mozilla-releng.net/treestatus PROJECT: releng-frontend TARGET: AWS S3 URL: https://treestatus.mozilla-releng.net/ PROJECT: treestatus/api on Heroku PostgreSQL TARGET: Heroku

Is TreeStatus working correctly?

To test and verify that treestatus is running correctly please follow the following steps:

  1. Select which environement (production or staging).

    For production:

    $ export URL=https://treestatus.mozilla-releng.net

    For staging:

    $ export URL=https://treestatus.staging.mozilla-releng.net

  2. List all trees

    $ curl $URL/trees
{
   "result": {
     "ash": {
       "message_of_the_day": "MotDs are a nice thing we can't have.",
       "reason": "",
       "status": "open",
       "tree": "ash"
     },
     ...
   }
}

  3. Show details of an existing tree

    $ curl $URL/trees/mozilla-beta
{
  "result": {
    "message_of_the_day": "",
    "reason": "",
    "status": "approval required",
    "tree": "mozilla-beta"
  }
}

  4. Show error for non existing tree (return code: 404)

    $ curl $URL/trees/invalid
{
  "detail": "No such tree",
  "instance": "about:blank",
  "status": 404,
  "title": "404 Not Found: No such tree",
  "type": "about:blank"
}

Develop

To start developing treestatus you would need to:

  1. Install all requirements and read through general guide how to contribute.

  2. Read through python projects guide, how python projects are structured and how to add/update dependencies to a project.

  3. And last you will have to read about conventions we use to write REST endpoints using Flask.

    It is important to know that treestatus uses the following Flask extensions: