Integrate Workflow with GitHub

[edit on GitHub]

Workflow’s GitHub integration allows you to use GitHub as the canonical git repository for your projects while benefiting from Workflow’s workflow and pipeline automation. When you enable the integration on a project in Workflow, you will be able to:

• Review pull requests and make code comments in the GitHub UI.
• Browse code (including in-flight changes in the Workflow pipeline) using GitHub.
• Have the target branch (usually master) of your GitHub project repository managed by Workflow. When a change is approved in Workflow, it will perform the merge in GitHub.

Workflow’s GitHub integration is designed for use with GitHub.com and GitHub Enterprise 2.x, and supports connecting a Workflow enterprise with a single GitHub server URL.

Setting up integration with GitHub

To enable the GitHub integration, you will need:

1. A Workflow user account with admin role in the Workflow enterprise you wish to connect.

2. The URL for your GitHub instance.

3. A GitHub user to use as the service account. This user must have full access (read/write) to the projects you wish to add to Workflow.

   

4. A Personal Access token generated by your GitHub service account.

To create a token, sign in to GitHub as your service account.

1. Select Settings from the menu at the top right.

   

2. Go to Developer settings and click Personal access tokens.

   

   

3. Click Generate new token.

   

4. Fill in a description of the purpose of this token and select the checkboxes for the following permissions: repo, public_repo, write:public_key, and admin:repo_hook.

   

5. Click Generate token. The next screen will contain the token you need. Make sure to copy it before you leave this screen!

   

Trusting a Self-Signed SSL Certificate

This procedure is only needed when connecting to GitHub Enterprise, and when your GitHub Enterprise server uses a self-signed SSL certificate.

Debian

1. Log into your Workflow Server as root.

2. Change directory to ca-certificates.

   cd /usr/local/share/ca-certificates
   

3. Copy your certificate into the /usr/local/share/ca-certificates directory.

   openssl s_client -showcerts -connect {your-GitHub-server}:443 </dev/null 2>/dev/null|openssl x509 -outform PEM >{your-GitHub-server}.crt
   

4. Update the CA store on the Workflow server.

   update-ca-certificates
   

Rhel/CentOS 6.x and greater

1. Log into your Workflow Server as root.

2. Install the ca-certificates package.

   yum install ca-certificates
   

   Note

   You only need to do this once for 6.x servers.

3. Enable the dynamic CA configuration feature.

   update-ca-trust force-enable
   

   Note

   You only need to do this once for 6.x servers.

4. Change directory to the anchors directory.

   cd /etc/pki/ca-trust/source/anchors/
   

5. Copy your certificate into the /etc/pki/ca-trust/source/anchors/ directory.

   openssl s_client -showcerts -connect {your-GitHub-server}:443 </dev/null 2>/dev/null|openssl x509 -outform PEM >{your-GitHub-server}.crt
   

6. Create or update the generated CA certificate bundle files located in the /etc/pki/ca-trust/extracted directory hierarchy.

   update-ca-trust extract
   

Associating Workflow with your GitHub instance

1. In Workflow’s web UI, click the Admin button in the top navigation.
2. From the left navigation, click SCM Setup.
3. Click the GitHub tab.
4. Fill out the following fields.
   • GitHub URL - The URL for your GitHub instance.
   • GitHub Username - The username of the service account that Workflow will use to interact with GitHub.
   • GitHub Token - Token generated by the service account on GitHub.
5. Submit the form.

Updating the integration with GitHub

If you need to change the GitHub credentials, follow these steps:

1. In Workflow’s web UI, click the Admin button in the top navigation.
2. From the left navigation, click Scm Setup.
3. Click the GitHub tab.
4. Correct the appropriate information.
5. Click the Update button.

Creating a new GitHub-integrated project

You can repeat these steps for each GitHub project you want to add to Workflow.

To begin, you will need:

• A project repository in GitHub with at least one commit.
• A service account used by Workflow that has full access to your GitHub repository.
• Your teams set up with read-only access to this repository. Workflow will manage creation of pull requests and merging of pull requests.

Initializing a new GitHub project in Workflow

1. Create a local clone of the project from GitHub and cd into it.

2. Create a .delivery/cli.toml using delivery setup:

   delivery setup --ent=$AUTOMATE_ENTERPRISE --org=$AUTOMATE_ORG --user=$AUTOMATE_USER_NAME --server=$AUTOMATE_SERVER
   

3. If the desired default pipeline is not master, manually edit .delivery/cli.toml to reflect the desired pipeline.

4. Start the initialization process by running:

   delivery init --github $GITHUB_ORGANIZATION --repo-name $REPOSITORY_NAME
   

   By default, Workflow will use the current directory name as project name. If you want to name the project something else, you may specify the project name as an argument (--project=$AUTOMATE_PROJECT_NAME).

   After importing your code, this command generates a .delivery/config.json file, creates a build cookbook, and submits a change to Workflow that initializes a pipeline for the project. Your browser will open to the change in Workflow. At this point, you should be able to see a corresponding pull request in GitHub.

   Note

   You may also specify a different pipeline than the default (master) by specifying the argument --pipeline=$PIPELINE; however, this will not update the .delivery/cli.toml file.

Multiple pipelines

If multiple pipelines are desired:

1. Push the desired branch to the Workflow server using git push delivery $BRANCH_NAME.
2. Navigate to the project’s page (/$ENT_NAME/organizations/$ORG_NAME/projects/$PROJECT_NAME) in the Workflow web UI and click the Pipelines tab.
3. Click Add A New Pipeline on the top of the page.
4. Give pipeline a descriptive name and input the base branch.

Integrating an existing project with GitHub

You will need:

• A project repository in GitHub with at least one commit.
• A service account used by Workflow that has full access to your GitHub repository.
• Your teams set up with read-only access to this repository. Workflow will manage creation of pull requests and merging of pull requests.

Do the following steps:

1. In Workflow’s web UI, click the Workflow button in the top navigation.
2. Select Workflow Orgs from the left navigation.
3. Click the organization you want to add a project to.
4. Click the pencil button of the project you wish to update.
5. Click the GitHub tab.
6. Fill in the project key and repository name.
7. Click Save & Close.

Updating GitHub information for a project

1. In Workflow’s web UI, click the Workflow button in the top navigation.
2. Select Workflow Orgs from the left navigation.
3. Click the organization you want to add a project to.
4. Click the pencil button of the project you wish to update.
5. Click the GitHub tab.
6. Update your project key and/or repo name with updated information.
7. Click Save & Close.

Removing GitHub integration from an existing project

1. Merge or close all open changes for the project.
2. In Workflow’s web UI, click the Workflow button in the top navigation.
3. Select Workflow Orgs from the left navigation.
4. Click the organization you want to add a project to.
5. Click the pencil button of the project you wish to update.
6. Click the Chef Delivery tab.
7. Click Save & Close.

Removing GitHub integration from Workflow

1. Remove GitHub integrations for existing projects.
2. In Workflow’s web UI, click the Admin button in the top navigation.
3. From the left navigation, click Scm Setup.
4. Click the GitHub tab.
5. Click the Remove Link button.

Workflow workflow with GitHub

This section describes the setup and workflow that a member of a team would use to interact with a project using Workflow’s GitHub integration. Here we assume that the initial project creation, import, and pipeline setup has already occurred.

Configure your Delivery CLI and clone your project’s code

1. In your command shell, create or navigate to a directory where you will store project repositories. Use delivery setup with arguments as shown below to create a .delivery/cli.toml file:

   delivery setup --ent=$AUTOMATE_ENTERPRISE --org=$AUTOMATE_ORG --user=$AUTOMATE_USER --server=$AUTOMATE_SERVER
   

2. Create a local clone of the project repository.

   delivery clone $PROJECT
   

   Note

   If you clone from GitHub instead (or make use of a pre-existing clone), you will need to add a delivery remote. The Workflow clone URL can be found on the project’s page in the Workflow UI. To create the remote, run the following:

   git remote add delivery $AUTOMATE_CLONE_URL
   

Creating a Change (Pull Request)

1. Create and check out a topic branch for your change, based on the current state of your project’s pipeline (usually ‘master’). For example, git checkout -b great-feature.
2. Make and commit changes to your project as you normally do.
3. Submit your change to Workflow with the command delivery review. If you desire to target a pipeline other than the default one, add the pipeline flag --pipeline=$PIPELINE. This command will output a URL to view the details and progress of the change through Workflow; the Verify phase will begin automatically and a corresponding Pull Request will be opened in GitHub.

Code Review

You may conduct a code review using either Workflow or GitHub; however, the merging of a pull request is handled by Workflow and occurs when a change in Workflow is approved.

To perform code review using Workflow:

1. Use the URL created by delivery review to go directly to the change, or browse to the change from the Workflow Dashboard or from the link provided in the first comment of your GitHub pull request.
2. Click the Review tab.
3. Browse the changes and make comments.

Approving a Change (Merging a Pull Request)

When the Verify phase has passed in Workflow and the code has been reviewed and is ready to be merged, approve the change in Workflow; the pull request will be merged and closed in GitHub. The feature branch will also be deleted in GitHub.

1. Use the URL created by delivery review to go directly to the change, or browse to the change from the Delivery Dashboard or from the link provided in the first comment of your GitHub pull request.
2. Click the Review tab.
3. Click Approve.

Deleting a Change (Declining a Pull Request)

When the Verify phase has passed in Workflow and the code has been reviewed and it is decided the change should never be approved, delete the change in Workflow; the pull request will be declined and closed in GitHub. The feature branch will also be deleted in GitHub.

1. Use the URL created by delivery review to go directly to the change, or browse to the change from the Workflow Dashboard or from the link provided in the first comment of your GitHub pull request.
2. Click the Review tab.
3. Click Delete.