Best practices for securing your NiFi CI/CD workflow with NiPyAPI Actions.

The NiFi GitHub Flow Registry Client requires a Personal Access Token (PAT). The automatic GITHUB_TOKEN provided by GitHub Actions does not work because:

• GITHUB_TOKEN is an app installation token, not a user token
• NiFi's client calls GitHub's /user API endpoint for authentication
• This endpoint requires user authentication, which GITHUB_TOKEN cannot provide

Error you'll see if using GITHUB_TOKEN:

"Resource not accessible by integration"

For the best security posture, use a fine-grained PAT with minimal permissions:

1. Go to GitHub Settings then Developer settings then Personal access tokens then Fine-grained tokens

2. Click Generate new token

3. Configure:

4. Set permissions:

Note on read-write access: Read-only is sufficient for these GitHub Actions (deploying and testing flows). If you also want to use the same token for versioning flows directly from NiFi's UI (committing flow changes back to GitHub), you'll need Contents: Read and write instead.

5. Generate and securely store the token

• Minimal permissions: Read-only access means token cannot modify code (for CI use)
• Scoped access: Limited to specific repositories
• Audit trail: GitHub logs token usage
• Expiration: Tokens can have mandatory expiration dates
• Revocable: Easy to revoke if compromised

If you cannot use fine-grained tokens (e.g., GitHub Enterprise Server older than 3.10):

1. Go to Settings then Developer settings then Personal access tokens then Tokens (classic)
2. Generate with repo scope (or public_repo for public repositories)

Note: Classic PATs are less secure as they grant broader access.

Repository secrets are available to all workflows in your repository:

1. Go to Repository then Settings then Secrets and variables then Actions
2. Click New repository secret
3. Add your secrets:

Use environment secrets when you need approval workflows for deployments:

1. Create an environment (e.g., production)
2. Configure protection rules (required reviewers, wait timer)
3. Add secrets to the environment
4. Reference in workflow:

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production  # Requires approval
    steps:
      - uses: Chaffelson/nipyapi-actions@main
        with:
          command: deploy-flow
          nifi-api-endpoint: ${{ secrets.NIFI_URL }}
          # Uses environment-scoped secrets

For secrets shared across multiple repositories:

1. Go to Organization then Settings then Secrets and variables then Actions
2. Add secrets and configure repository access
3. Reference the same way as repository secrets

GitHub automatically protects against secret leakage:

• Fork PRs: Secrets are NOT available to workflows triggered by fork PRs
• Branch PRs: Only PRs from branches within the same repo can access secrets
• Pull request approval: Require approval before running workflows on fork PRs

1. Enable branch protection on main:

   • Require pull request reviews
   • Require status checks to pass
   • Restrict who can push

2. Configure workflow permissions:

   permissions:
     contents: read

3. Use pull_request_target carefully: This event has access to secrets even for fork PRs. Avoid it unless you fully understand the security implications.

4. Limit workflow triggers:

   on:
     pull_request:
       branches: [main]  # Only run on PRs to main

For development and testing, NiFi's single-user mode is simplest:

nifi-username: ${{ secrets.NIFI_USERNAME }}
nifi-password: ${{ secrets.NIFI_PASSWORD }}

Development (self-signed):

nifi-verify-ssl: 'false'
nipyapi-suppress-ssl-warnings: 'true'

Production:

• Use proper CA-signed certificates
• Keep nifi-verify-ssl: 'true' (default)
• Mount CA bundle if using internal CA

1. Generate new PAT before old one expires
2. Update repository secret
3. Verify workflows succeed
4. Revoke old PAT

1. Update password in NiFi
2. Update repository secret
3. Verify workflows succeed

• Review workflow runs for unexpected behavior
• Secrets are automatically masked in logs
• Failed authentication attempts are logged

• NiFi logs all API access
• Review for unexpected:
  • Registry client modifications
  • Process group deployments
  • Controller service changes

• Using fine-grained PAT with minimal permissions
• PAT scoped to specific repository
• Secrets stored in repository/environment secrets
• Branch protection enabled on main
• Workflow permissions restricted
• SSL verification enabled in production
• NiFi service account with minimal permissions
• Regular credential rotation scheduled
• Audit logging reviewed periodically

• Setup Guide - Initial setup instructions
• How It Works - Architecture overview
• GitHub Actions Security Hardening