CI/CD Pipeline

Relevant source files

• .github/actions/rl-scanner/action.yml
• .github/workflows/codeql.yml
• .github/workflows/docs.yml
• .github/workflows/publish.yml
• .github/workflows/rl-scanner.yml
• .github/workflows/snyk.yml

Purpose and Scope

This document provides an overview of the GitHub Actions-based CI/CD pipeline for the auth0-python SDK. It covers the workflow architecture, trigger conditions, job dependencies, and the relationship between different automation workflows. The pipeline handles continuous testing, security scanning, documentation deployment, and package publication to PyPI.

For detailed information about specific pipeline components, see:

• Testing workflows and matrix configurations: Testing Workflow
• Security scanning tools (Snyk, CodeQL, Semgrep, RL-Scanner): Security Scanning
• Documentation build and deployment process: Documentation Deployment
• Release creation and PyPI publication: Release Process

CI/CD Architecture Overview

The auth0-python SDK uses GitHub Actions for all CI/CD automation. The pipeline consists of five primary workflows, each triggered by different events and serving distinct purposes:

Workflow File	Primary Trigger	Purpose	Status Check
test.yml (referenced)	Pull requests, pushes	Multi-version Python testing	Required
snyk.yml	Pull requests, scheduled	Dependency vulnerability scanning	Required
codeql.yml	Pull requests, scheduled	Static code security analysis	Required
semgrep.yml (referenced)	Pull requests	Security pattern detection	Required
docs.yml	Push to master	Documentation build and deploy	Not required
publish.yml	Release branch merge	Package publication to PyPI	Not required

The workflows are independent but coordinated through branch protection rules and environment gates. All required workflows must pass before pull requests can be merged.

Sources: .github/workflows/snyk.yml1-40 .github/workflows/codeql.yml1-54 .github/workflows/docs.yml1-60 .github/workflows/publish.yml1-91

Workflow Trigger Matrix

Diagram: Workflow Trigger Relationships

The trigger configuration uses GitHub Actions event filters to control when each workflow executes:

• Pull Request Workflows: snyk.yml line 6-9 and codeql.yml line 5-8 use types: [opened, synchronize] to run on new PRs and subsequent commits
• Scheduled Scans: snyk.yml line 13-14 runs bi-weekly (cron: '30 0 1,15 * *'), codeql.yml line 12-13 runs weekly on Mondays
• Release Gate: publish.yml line 27 only triggers on merged PRs where startsWith(github.event.pull_request.head.ref, 'release/')
• Master Branch: docs.yml line 4-6 deploys documentation on every push to master

Sources: .github/workflows/snyk.yml3-14 .github/workflows/codeql.yml3-13 .github/workflows/docs.yml3-6 .github/workflows/publish.yml3-27

Concurrency Control

Workflows use GitHub Actions concurrency groups to prevent redundant job executions and optimize resource usage:

This configuration .github/workflows/snyk.yml19-21:

• Groups jobs by workflow name and PR number (or branch ref)
• Cancels in-progress jobs for non-master branches when new commits are pushed
• Allows master branch jobs to complete to ensure accurate historical data

The docs.yml workflow uses a simpler group .github/workflows/docs.yml13-15: group: "documentation" with cancel-in-progress: true since documentation builds are idempotent.

Sources: .github/workflows/snyk.yml19-21 .github/workflows/codeql.yml20-22 .github/workflows/docs.yml13-15

Release Publication Pipeline

The publish.yml workflow orchestrates the complete release process with a multi-stage pipeline:

Diagram: Release Pipeline Job Flow

rl-scanner Job

The rl-scanner job .github/workflows/publish.yml14-25 is invoked as a reusable workflow from rl-scanner.yml. It serves as a security gate that must pass before publication:

1. Build Preparation: Sets up Python 3.10 and installs Poetry 1.4.2 with the poetry-dynamic-versioning plugin .github/workflows/rl-scanner.yml44-54
2. Artifact Creation: Builds the package with poetry build and creates a tarball containing all repository files .github/workflows/rl-scanner.yml56-62
3. Security Scan: Executes the RL-Scanner custom action .github/workflows/rl-scanner.yml68-80 which analyzes the binary artifact for vulnerabilities
4. Gate Decision: If the scan fails, the workflow terminates; if it passes, the publish-pypi job is allowed to run

The RL-Scanner custom action .github/actions/rl-scanner/action.yml1-72 integrates with Reversing Labs' security service using AWS credentials and proprietary scanning tools.

publish-pypi Job

The publish-pypi job .github/workflows/publish.yml26-91 handles the actual package distribution:

1. Version Extraction: The get-version action .github/workflows/publish.yml41-42 parses the version from the branch name (e.g., release/5.1.0 → 5.1.0)
2. Prerelease Detection: The get-prerelease action .github/workflows/publish.yml45-48 determines if the version is a prerelease based on version string patterns (e.g., 5.1.0-beta.1)
3. Release Notes: The get-release-notes action .github/workflows/publish.yml52-58 generates release notes from commit messages between tags
4. GitHub Release: The release-create action .github/workflows/publish.yml61-68 creates a GitHub Release with the extracted version, notes, and prerelease flag
5. Build: Poetry builds both wheel and sdist distributions .github/workflows/publish.yml85-87
6. PyPI Publication: The official pypa/gh-action-pypi-publish@release/v1 action .github/workflows/publish.yml89-91 publishes to PyPI using OIDC Trusted Publishing (no API tokens required)

Job Dependencies: The publish-pypi job uses needs: rl-scanner .github/workflows/publish.yml30 to enforce sequential execution and gate publication on security scan results.

Sources: .github/workflows/publish.yml14-91 .github/workflows/rl-scanner.yml27-83 .github/actions/rl-scanner/action.yml1-72

Documentation Deployment Workflow

The docs.yml workflow .github/workflows/docs.yml1-60 automates documentation publication to GitHub Pages:

Diagram: Documentation Deployment Flow

The workflow splits documentation deployment into two jobs:

1. build: Generates HTML documentation from source files using Sphinx .github/workflows/docs.yml18-48

   • Uses sphinx-build command with flags: --keep-going (continue on errors), -n (nitpicky mode), -a (rebuild all), -b html (HTML builder)
   • Uploads the ./docs/build directory as a GitHub Pages artifact

2. deploy: Publishes the artifact to GitHub Pages .github/workflows/docs.yml49-60

   • Uses the github-pages environment which may have protection rules
   • Outputs the deployment URL via ${{ steps.deployment.outputs.page_url }}

Concurrency: The workflow uses group: "documentation" with cancel-in-progress: true .github/workflows/docs.yml13-15 to cancel redundant builds when multiple commits are pushed rapidly.

Sources: .github/workflows/docs.yml1-60

Permissions Model

GitHub Actions workflows in this repository use fine-grained permissions following the principle of least privilege:

Security Scanning Workflows

Both snyk.yml and codeql.yml request minimal permissions:

• contents: read .github/workflows/snyk.yml17 allows checking out repository code
• security-events: write .github/workflows/codeql.yml18 allows CodeQL to upload security findings to GitHub Security tab

The snyk.yml workflow only needs contents: read .github/workflows/snyk.yml16-17 since it reports findings through the Snyk dashboard, not GitHub Security.

Documentation Workflow

The docs.yml workflow requires GitHub Pages-specific permissions:

• pages: write .github/workflows/docs.yml10 enables deploying to GitHub Pages
• id-token: write .github/workflows/docs.yml11 allows OIDC authentication for the Pages deployment action

Release Publication Workflow

The publish.yml workflow requires the most extensive permissions:

• contents: write .github/workflows/publish.yml10 enables creating GitHub Releases and tags
• id-token: write .github/workflows/publish.yml11 enables OIDC Trusted Publishing to PyPI without API tokens

The workflow also uses a protected release environment .github/workflows/publish.yml31 which can enforce manual approval requirements before publication.

Sources: .github/workflows/snyk.yml16-17 .github/workflows/codeql.yml15-18 .github/workflows/docs.yml8-11 .github/workflows/publish.yml9-11

Dependabot and Merge Queue Optimization

Security scanning workflows include logic to skip unnecessary runs for automated dependency updates and merge queues:

This pattern .github/workflows/snyk.yml31-32 .github/workflows/codeql.yml35-36 appears in both snyk.yml and codeql.yml. It:

1. Checks if the workflow was triggered by Dependabot or as part of a merge queue
2. Exits successfully (exit code 0) without running actual scans
3. Artificially marks the check as passed for branch protection purposes

Rationale: Dependabot PRs and merge queue validation already run these scans on the source branches. Re-running them is redundant and wastes CI resources. By exiting successfully, the checks satisfy branch protection rules without actual execution.

Sources: .github/workflows/snyk.yml31-32 .github/workflows/codeql.yml35-36

Workflow Action Dependencies

The workflows utilize both official GitHub Actions and custom local actions:

Official Actions

Action	Purpose	Used In
actions/checkout@v5	Repository checkout	All workflows
actions/setup-python@v6	Python environment setup	All workflows
actions/configure-pages@v5	GitHub Pages configuration	docs.yml
actions/upload-pages-artifact@v4	Upload Pages content	docs.yml
actions/deploy-pages@v4	Deploy to Pages	docs.yml
pypa/gh-action-pypi-publish@release/v1	PyPI publication	publish.yml
github/codeql-action/init@v4	Initialize CodeQL	codeql.yml
github/codeql-action/autobuild@v4	Auto-build for CodeQL	codeql.yml
github/codeql-action/analyze@v4	Perform CodeQL analysis	codeql.yml
snyk/actions/python@9adf32b1121593767fc3c057af55b55db032dc04	Snyk Python scanning	snyk.yml
aws-actions/configure-aws-credentials@v1	AWS authentication	RL-Scanner action

Custom Local Actions

The repository includes custom actions in .github/actions/:

• get-version .github/workflows/publish.yml42: Extracts version from branch name
• get-prerelease .github/workflows/publish.yml45: Determines prerelease status
• get-release-notes .github/workflows/publish.yml52: Generates release notes from commits
• release-create .github/workflows/publish.yml61: Creates GitHub Release
• rl-scanner .github/actions/rl-scanner/action.yml1: Executes Reversing Labs security scan

Note: Comments in publish.yml line 6-7 indicate these custom actions are planned for migration to a shared dx-sdk-actions repository when it becomes public.

Sources: .github/workflows/docs.yml22-59 .github/workflows/publish.yml35-90 .github/workflows/codeql.yml39-51 .github/workflows/snyk.yml38 .github/actions/rl-scanner/action.yml1-72

Environment Configuration

The publish-pypi job uses a GitHub environment named release .github/workflows/publish.yml31:

GitHub environments provide:

• Protection Rules: Optional manual approval gates before job execution
• Secrets Scoping: Environment-specific secrets that are only accessible to jobs running in that environment
• Deployment History: Tracking of all deployments to the environment in the GitHub UI

Similarly, the documentation deployment uses the github-pages environment .github/workflows/docs.yml53:

This environment automatically tracks GitHub Pages deployments and displays the deployment URL in pull requests and the deployments dashboard.

Sources: .github/workflows/publish.yml31 .github/workflows/docs.yml52-54

Secrets Management

The CI/CD pipeline uses GitHub Secrets for sensitive credentials. The RL-Scanner workflow requires six secrets:

These secrets .github/workflows/publish.yml19-25 .github/workflows/rl-scanner.yml12-24 are passed from the publish.yml workflow to the reusable rl-scanner.yml workflow, which then provides them to the custom RL-Scanner action.

The Snyk workflow uses a single secret:

This token .github/workflows/snyk.yml40 authenticates the workflow with the Snyk service.

OIDC Authentication: The PyPI publication uses OIDC Trusted Publishing instead of API tokens, eliminating the need to store PyPI credentials as secrets. This is enabled by the id-token: write permission .github/workflows/publish.yml11

Sources: .github/workflows/publish.yml19-25 .github/workflows/rl-scanner.yml12-24 .github/workflows/snyk.yml39-40