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 GitHub. Click the Connect GitHub button.

2. Map repositories to a workstream

With source code integration enabled, the next step is to choose for any participating workstream its relevant repositories:

  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 key 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 average time to review pull requests, trended over time;

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

  • The number of pull requests reviewed, trended over time (person view only).

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

Last updated