GitHub Services Integration

CA Agile Central's GitHub Services integration creates changeset information in CA Agile Central associated with the workspace and SCMRepository of your choice. In CA Agile Central, when looking at an artifact, you can see detail on changesets associated with commits from GitHub push activities. CA Agile Central also provides reports that use the artifact, changeset, and change information to provide insight into files which get changed frequently or that are associated with higher than normal defect rates and other useful metrics-based reports.

The integration scans for tokens in the commit message that conform to a CA Agile Central artifact's FormattedID format. These tokens are validated against CA Agile Central so that a reference to a valid artifact ( user story, defect, task ) results in the association of the artifact to the changeset posted in CA Agile Central performed by this integration. However, unlike the GitHub VCS connector, this GitHub integration does not allow for the changing of an artifact's state .

This integration is Open Source and is located here.

Known limitation: SSO is not supported with this GitHub integration.

Setup Overview

The following items are required information needed to configure your GitHub services:

  • Server
    The hostname of the CA Agile Central server. You do not need to provide the domain name portion of the server if it is a CA Agile Central SaaS server, such as rally1, trial, or demo. If you are using the CA Agile Central On-Premises product, you will need to provide the fully qualified hostname.
  • User name
    The user name for your CA Agile Central subscription . Be sure to specify the user name (and not the DisplayName, FirstName, LastName, or Email).
  • Password
    The password associated with the above user name.
  • Workspace
    The name of your CA Agile Central workspace. This is where the target SCMRepository resides.
  • Repository
    The name of your CA Agile Central SCMRepository. All CA Agile Central Changeset objects belong to a CA Agile Central SCMRepository object. If not provided, the name used for this will be the same as your GitHub repository name. If this CA Agile Central SCMRepository does not already exist, it will be created.

You can verify your CA Agile Central login capability of the above user name and Password by going here.

Connect CA Agile Central and GitHub

The web site http://www.github.com is home to a free cloud service where you can register an account and then create repositories for the source code of your pet projects. These repositories can be accessed by the general public, unless you register for a private account (check here for current pricing).

As well as being a place for storing the source code of your projects, GitHub services can be used to update a specified CA Agile Central artifact (such as a user story or defect) each time you perform a push (not a commit) of your local source code that commits to one of your GitHub repositories.

The command window used in these steps is a MacOS 10.8 (Mountain Lion) terminal.

Use the following steps to connect CA Agile Central and GitHub:

  1. Configure Your CA Agile Central Workspace
  2. Create a CA Agile Central Defect
  3. Create a Free GitHub Account
  4. Create a GitHub Repository
  5. Create a Local Repository on Your Computer
  6. Push Your Local Commits to GitHub
  7. Make Local Source Modifications and Push Them to GitHub
  8. View the Source Changes on GitHub
  9. View the New Changesets Created in CA Agile Central

Configure Your CA Agile Central Workspace

Verify that your target WorkspaceConfiguration object has BuildandChangesetEnabled set to true.

Your CA Agile Central Workspace administrator needs to enable this for your target Workspace. If it is not enabled, the connector will work, but you will nott be able to see any of the Changeset/Change information that is associated with your CA Agile Central work items (Story, Defect, Task, and so on).

Procedure: The Workspace administrator must edit the workspace and perform these steps:

  1. Select Setup (near top right of screen).
  2. Select the Workspaces & Projects tab .
  3. Find the desired Workspace in the list and select it.
  4. Select the Workspace link in the left column.
  5. Select Actions (near top right) and select Edit.
  6. Scroll down and check the box labeled Enable Build and Changeset.
  7. Select Save & Close (at the bottom of window).

Create a CA Agile Central Defect

A CA Agile Central defect can have CA Agile Central changesets associated with it. Each git push to your GitHub repository can trigger the creation of a new CA Agile Central changeset (a nice audit trail of changes).

  1. In a browser window, login to your CA Agile Central subscription (for example, https://rally1.rallydev.com).
  2. From the Quality tab, select Defects.
  3. On the Defects summary page , select Actions, New Defect.
  4. Enter a name and any other required fields for your new defect.
  5. Select Save (do not select Save & Close).
  6. Take note of the new defect's ID.
  7. Select Save & Close.

Create a Free GitHub Account

  1. In a browser, navigate to https://github.com/signup/free.
  2. Create an account.

Note: Sometimes having two GitHub accounts (for example, personal and work) leads to unnecessary confusion. We recommend using one account until setup is finished.

Create a GitHub repository

  1. In a browser, navigate to https://github.com/login, and login.
  2. Select New repository.
  3. Enter My-Demo-Repo-GitHub in these two fields: Repository name and Description.
  4. Leave the Public field selected.
  5. Select Create repository.
  6. Select the settings icon (a wrench and a screwdriver) in the bottom of the right column of icons.
  7. In the left column, under Options, select Service Hooks.
  8. Scroll down the list of Available Service Hooks and select Rally.
  9. Scroll back up and fill in the fields as follows:
    • Server: rally1 (or you can enter rally1.rallydev.com)
    • User name: Your Rallyusername
    • Workspace: YourRallyworkspacename
    • Repository: YourRallySCMrepository

      The CA Agile Central data model has a SCMRepository object. Every changeset object created in CA Agile Central is associated to one of these SCMRepository objects. If you want to give this CA Agile Central SCMRepository object a name, enter the value in this box. If there is a CA Agile Central SCMRepository by this name, it will be used. If it does not exist, it will be created. If this box is left blank, the name used will be the same name used for your GitHub repository name. There is not a place in the CA Agile Central GUI to view a list of your SCMRepositories. To do so, go here and select the Query button: https://rally1.rallydev.com/slm/doc/webservice/objectModel.sp#SCMRepository.

    • Password: YourRallypassword
    • Active: This box must be checked, otherwise nothing will be sent to CA Agile Central.
  10. Select Update settings.
  11. Scroll down the list of Available Service Hooks and verify there is a green checkmark to the right of the CA Agile Central (Rally) entry.

GitHub services for CA Agile Central is now defined for this GitHub repository and ready to connect to CA Agile Central as needed.

Mapping SCMRepositories to VCS Repositories

The VCS Connector was designed to operate where this is a one-to-one relationship between a CA AgileCentral SCMRepository and a VCS repository (Git, GitHub, Subversion, Mercurial, and so on). When run, the VCS Connector creates a CA Agile Central SCMRepository item for the value specific in the connector config file if it does not already exist. This removes a small amount of administrative burden in that you do not have to create the CA Agile Central SCMRepository item before you run a configuration mentioning a new repository. A one-to-many mapping can create performance issues.

For each repository, there is a config file and a timefile. The timefile records the timestamp of the second-to-last commit for the repository. For example, you have an Apricot repository that had some flurry of commits last fall but nothing since and you also have a Banana repository that has had activity with the last couple of months. When commits for these two repositories get poured into a single CA Agile Central SCMRepository, it has the following effect. When processing the config for the Apricot repository, it is searching for recent Changeset records in CA Agile Central where recent is defined as the value in the timefile for Apricot. Since the last commit to that repository was last fall, there is going to be an excessive amount of information read-out of the single SCMRepository (because it is looking at all Changesets since last fall, not just the ones for Apricot).

Create a Local Repository on Your Computer

  1. Install Git on your computer, if it is not already present.
  2. Enter the following commands at a command prompt (note the output):
    • mkdir My-Demo-Repo-Local # (no output)
    • cd My-Demo-Repo-Local # (no output)
    • touch README.md # (no output)
    • git init

      OUTPUT:
      Initialized empty Git repository in /Users/yourname/My-Demo-Repo-Local/.git/

    • git add README.md # (no output)
    • git commit -m "our first commit for DE307"
    • OUTPUT:
      [master (root-commit) a944e47] our first commit for DE307
      0 files changed
      create mode 100644 README.md

Push your local commits to GitHub

  1. Enter these commands at a command prompt (note output):
  • git remote add origin https://github.com/yourname/My-Demo-Repo-GitHub.git # (no output)
  • git push -u origin master
  • OUTPUT:
    user name for 'https://github.com': [email protected]
    Password for 'https://[email protected]@github.com': ********
    Counting objects: 3, done.
    Writing objects: 100% (3/3), 226 bytes, done.
    Total 3 (delta 0), reused 0 (delta 0)
    To https://github.com/yourname/My-Demo-Repo-GitHub.git
    * [new branch] master -> master
    Branch master set up to track remote branch master from origin.

  • In a browser, go to https://github.com/login, and login.
  • Verify your new source code resides in your repository at GitHub:
  • Select yourname/My-Demo-Repo-GitHub in the upper-left.
  • Under the Files tab, select the file name README.md. It should display the source code though it should be empty.
  • Add a file or a modified file to a local repo, use the following commit: git add

    Make Local Source Modifications and Push Them to GitHub

    Enter these commands at a command prompt (note output):

    • echo "My first code change" >> README.md # (no output)
    • git add README.md # (no output)
    • git commit -m 'second commit for DE307'

      OUTPUT:
      [master 502468d] second commit for DE307
      1 file changed, 1 insertion(+)

    • git push -u origin master

      OUTPUT:
      user name for 'https://github.com': [email protected]
      Password for 'https://[email protected]@github.com': ********
      Counting objects: 5, done.
      Writing objects: 100% (3/3), 269 bytes, done.
      Total 3 (delta 0), reused 0 (delta 0)
      To https://github.com/yourname/My-Demo-Repo-GitHub.git
      a944e47..502468d master -> master
      Branch master set up to track remote branch master from origin.

    Now the local changes to our source code should be in our GitHub repository; they can be viewed in the web browser.

    Also, CA Agile Central Defect DE307 should have a new changeset object.

    View the Source Changes on GitHub

    1. Login to http://github.com.
    2. On the right side of the page, under Your repositories (x), select yourname/My-Demo-Repo-GitHub.
    3. Select commits in the upper-left corner.
    4. The second commit should display, select it to see the source code changes.

    View the New Changesets Created in CA Agile Central

    1. Login to CA Agile Central.
    2. Select the Quality tab, then select Defects.
    3. In the search field, enter DE307.
    4. Select DE307 to navigate to the defect.
    5. Select the Changesets tab at the top right hand side of the screen
    6. Do one or both of the following :
      • Select the Name column link to open a new browser window that displays the changes to your source code on GitHub.
      • Select the Changes column link to open a new browser window that displays the entire source module with its changes.

    In summary, you should have:

    • A free GitHub account on the GitHub website.
    • A free GitHub public repository on the GitHub website, where you can store the source code of your project.
    • A local Git repository on your computer.
    • Real source code from your local project, pushed up to your GitHub repository (only a README.md so far).
    • A defect, created in CA Agile Central, with changesets which are associated with some CA Agile Central SCMRepository object.

    Feedback

    Need more help? The CA Agile Central Community is your one-stop shop for self-service and support. To submit feedback or cases to CA Agile Central Support, find answers, and collaborate with others, please join us in the CA Agile Central Community.