Skip to content
This repository was archived by the owner on Mar 13, 2025. It is now read-only.

Home

Jump to bottom
Justin Gasper edited this page Aug 16, 2018 · 19 revisions

How to use Topcoder-X

This document will describe how to use Topcoder-X as a copilot.

Topcoder-X Goal

Topcoder-X is an application that allows a copilot or Topcoder customer to manage work directly through Gitlab or Github. When an issue is created in a Gitlab or Github project set up in Topcoder-X, Topcoder-X will create a Topcoder challenge to mirror the Gitlab or Github issue, and it will ensure that the challenge has the correct prize, copilot, assignee, description, and title.

As the Gitlab or Github issue is updated, Topcoder-X will ensure that the Topcoder challenge associated with the issue is updated appropriately. When the Gitlab or Github issue is closed, Topcoder-X will activate and close the Topcoder challenge, ensuring that the members (submitter and copilot) get paid as expected.

General flow

Topcoder-X monitors Gitlab and Github repositories, looking at issues created. Gitlab and Github repositories will need to be configured with a webhook callback for Topcoder-X so that Topcoder-X is "aware" of changes made to issues on a repo. Topcoder-X can create this webhook for you.

When Topcoder-X performs specific actions to the Topcoder challenge that is associated with a Github / Gitlab ticket, Topcoder-X will create comments on the issue in Github / Gitlab explaining the update and where to find the Topcoder challenge.

Setup

When you first login to Topcoder-X, you will see a screen like this:

Link Github and Gitlab

Topcoder-X first needs to know about your Github and Gitlab username. It will use this to map your Github and Gitlab user to your Topcoder handle, as well as make comments to issues on your behalf on Gitlab and Github.

  • Click your username in the upper right
  • Select Settings

You will now see a screen where Github and Gitlab can be setup:

Click Setup for both Gitlab and Github and authorise Topcoder-X to have access to your repo.

Once done, you should see checkmarks next to both Gitlab and Github.

Add a project

A project in Topcoder-X maps a Topcoder Direct project ID to a git repo. When you first launch Topcoder-X, you won't have any projects set up:

You can set up a project by clicking Add a Project on the Project Management tab.

Fields

  • Project Name - Anything you want to use as the project name. This can be anything memorable
  • Direct ID - This is the Topcoder Direct ID for the project. This should be a 5 digit number. You can retrieve this by pulling the projectId value from the end of the URL when you visit the project in Topcoder Direct. For example: https://www.topcoder.com/direct/projectOverview?formData.projectId=17159 has a Direct ID of 17159
  • Repo URL - This is the URL to the repository in either Gitlab or Github. This should be the link to the actual repository that houses code. This is not the group or parent of the repository.

Here's an example:

Setup of labels and webhooks

Once a repository has been added as a project, you can see it in the list of current projects.

You can click the Edit button for a project to go to the Edit a Project screen

On the Edit a Project screen, you will see two buttons:

  • Add Labels
  • Add Webhook

Add Labels

The Add Labels button will add a default set of labels to either a Gitlab or Github repository. These labels can be applied to tickets to indicate different states of a ticket.

The labels added are:

  • tcx_OpenForPickup
  • tcx_Assigned
  • tcx_ReadyForReview
  • tcx_Paid
  • tcx_Feedback
  • tcx_FixAccepted

Add Webhook

When Add Webhook is clicked, the webhook callback will be automatically added to the Gitlab or Github repository. This webhook is called whenever an issue is updated on the repository, ensuring that Topcoder-X is "aware" of the changes made in real time. Topcoder-X will ignore any projects that don't have a webhook set up properly

Current vs. Archived project

A current project is one you are working right now and that is active for members to be able to access. We prioritise those in the UI. An archived project is one that isn't currently active for members or that has completed. Archived projects are still available in the UI, for historical purposes, but they aren't currently monitored by Topcoder-X. A project can be moved from current to archived and back again without any side effects. You can edit whether or not a project is archived using the Archived checkbox on the Edit a Project screen.

Git access control

One of the quirks of Topcoder-X is that most members have different usernames between Github / Gitlab and Topcoder. We have to have a mapping of a user's Github / Gitlab username to their Topcoder handle to ensure that payments process correctly. We also need a way to ensure that members can gain access to repositories automatically, without a copilot or PM having to grant explicit access to each member.

The Git access control link on the left side menu handles both the mapping and access grant functionality.

For each team in Github and Gitlab there will be a Get Link button that will generate a URL that can be shared to members.

When a member accesses this link, it will take them through two flows:

  1. Authorization of Topcoder-X for either Gitlab or Github, depending on the team type
  2. Authorization to Topcoder to gain their member details

The flow will:

  • Grant the user access to the git group (assuming the copilot / PM has owner group access)
  • Add a user mapping into the Topcoder-X database so that the system can map between different user account names

Git access link best practice

For each repository / project, you should have the members that need to work on the project use the Topcoder-X Git access control link. This will ensure that their accounts are properly set up in the system to allow for automatic payments, and it will also ensure they have access to the necessary code location.

For this to work, you need to have a reasonable team setup, so please plan your teams appropriately. For instance, if a project involves both a backend and a front end and they are split into separate repos, they should both be under the same Github / Gitlab team, instead of under separate teams.

Clone this wiki locally