There are four advantages to connecting Socratic with your source code management:

  1. Automated task workflow. Tasks automatically move from phase to phase based on the git events you choose.

  2. Even more accurate automated estimates. With tasks moving according to their associated code activity, Socratic's automatically generated estimates will reflect very nearly your actual, historical average coding time required to complete tasks.

  3. Enrich tasks with code activity. With source code integration, Socratic surfaces any and all code activity for each task. This includes showing on workstream boards all tasks with open pull requests, as well as the ability to filter tasks by those with open PRs.

  4. Code analytics. Socratic Trends shows how long it takes to merge code (as compared to historical averages for any time period you choose), which types of work had the most code activity, as well as merge throughput over time.

Set up

1. Connect Socratic

To activate for your org:

  1. Click the Socratic icon at top left, and choose Integrations.

  2. Click on GitLab.

You’ll need to create an OAuth app in GitLab. This OAuth app yields the client ID and client secret that are required as inputs for integration. Steps are as follows:

  1. In GitLab, navigate to the landing page for the group containing the repositories you wish to integrate with Socratic.

  2. In the contextual menu for your group, navigate to Settings -> Applications. If you don't see these items, you may not have sufficient permissions:

  1. The new view should look something like below, and you should see any existing applications listed at the bottom of the page:

  1. To create the app:

  • Enter a Name of your choice.

  • Enter our redirect URL:

  • Select Confidential.

  • Select a Scope level of api

  1. Once successfully created, you should see some of the information you previously provided, as well as an Application ID and Secret.

2. Map repositories to a workstream

With source code integration enabled, Socratic now has reference to all projects from your GitLab group, and any child groups. The next step is to map the relevant repositories to their workstream(s).

  1. Open the workstream and click the equalizer icon in the upper-right.

  2. Choose the Git Repositories tab. From here you'll select the specific repositories you want to connect to the workstream. You can always add or remove repositories later as well.

The same repository may be mapped to multiple workstreams.

3. Automate task moves (optional)

Automate task movement based on git actions

Simply by mapping repositories to a workstream, Socratic will begin surfacing a range of enriched work activity data (see below).

You may also optionally choose to have Socratic tasks move automatically, based on a corresponding code action. To do so:

  1. Open the workstream and click the equalizer icon in the upper-right.

  2. Choose the Git Workflow tab. Here, you specify the task action that you want to occur, based on a corresponding code event for a given code branch. For example:

    On Branch created in Default Branch move task to phase Doing

Code activity can only ever move tasks forward, not backward. Backward movement of tasks remains manual.

4. Map your Git user name to your Socratic profile

Doing this will automatically show your avatar next to any of your code activity in Socratic.

  1. Click your avatar in the lower-left of the app.

  2. Select your Git user name.

Linking to tasks

To automatically link your code action to the relevant Socratic task, simply include the task ID in any of the following:

  • Branch name

  • Commit title

  • Pull request title

Task ID is not case sensitive. Say you're committing code for task PROD-99. Any of PROD-99 or prod-99 or Prod-99 will be matched to the right task. Note that we do expect a hyphen (-). To copy the task key for your branch name, simply click the pull icon in the upper right of task detail:

How to see and use your enriched work activity data

In addition to automatically moving tasks according to code actions, source code integration activates several new or expanded views to surface code activity alongside task activity:

Workstream board

See at a glance all tasks with open pull requests. Filter the board to see only those tasks.

Task detail

Task detail has an additional tab to show code activity for the task.

Code analytics

With Socratic’s git integration, you can also see coding trends over time. Click the relevant Trends to see:

  • The average time to merge pull requests, trended over time;

  • The number of pull requests merged, trended over time.

In each case, you can click to see all pull requests and repositories involved.

Last updated