GitHub Actions automates repository workflows and provides CI/CD capabilities. For an API project, a pull request can trigger checks on source code and API artifacts before a merge. Automated minimum design review criteria can support, but do not replace, governance-team approval. section 8.4 section 8.3
Define a workflow in a YAML file under `.github/workflows`. Repository events, a schedule, or a manual request can trigger it; triggers can target particular branches. A runner executes its jobs. Each job contains sequential steps, either shell commands or reusable actions. Jobs run in parallel by default unless dependencies are configured. GitHub provides Ubuntu, Windows, and macOS runners; self-hosted runners are also possible. section 8.4
Listing 8.1 The PR build workflow
name: PR build workflow
on:
pull_request:
branches: [main] #1
workflow_dispatch: #2
jobs:
pr-code-build: #3
name: Build and test source code
runs-on: ubuntu-latest #4
steps:
- name: Checkout out pr branch
uses: actions/checkout@v3 #5
- name: Set up JDK 17
uses: actions/setup-java@v3
with:
java-version: '17'
distribution: 'temurin'
cache: maven
- name: Compile
run: |
cd chapter8
mvn --batch-mode clean compile #6
- name: Unit test
run: |
cd chapter8
mvn --batch-mode test
The PR build workflow runs for pull requests against `main` or by manual dispatch. On an Ubuntu runner, it checks out code, sets up JDK 17, then compiles and tests the Java project with Maven. section 8.4
To add source-stage API governance, extend the existing workflow with a separate minimum-review-criteria job. Its planned checks are:
- Require a work-ticket reference in the pull-request title. section 8.5 section 8.5.1
- Lint the API definition and its guide documentation. section 8.5
- Check the API definition for breaking changes. section 8.5
Listing 8.3 Workflow job for minimum API review criteria
…
pr-api-minimum-review-criteria:
name: Minimum API design review criteria
runs-on: ubuntu-latest
steps:
- name: Checkout out pr branch
uses: actions/checkout@v3
with:
path: pr-branch
- name: Check PR title
run: ./pr-branch/chapter8/pr-title.sh
"'${{ github.event.pull_request.title }}'"
The example job checks out the pull-request branch into `pr-branch`, then passes `${{ github.event.pull_request.title }}` to a shell script. It is appended to, not substituted for, the existing build job. section 8.5.1
Test a failing gate
Make `pr-title.sh` executable and have it exit with status 1 when the title lacks a `DEV-` reference followed by four digits. Open a pull request without that reference to see the job fail. Change its title to begin with `[DEV-1234]`, then update the pull request to retrigger the job and confirm it passes. The script checks the title’s pattern; validating that the ticket exists in Jira would require an additional REST API check. section 8.5.1
GitHub Actions can also run later pipeline work that generates and publishes API artifacts. API gateway configuration deployment and implemented-API conformance testing belong to the broader deployment pipeline; they are not performed by the pull-request title job. section 9.0 section 8.5.1
