GitHub Actions
Derafu Foundation includes pre-configured GitHub Actions workflows for continuous integration (CI) and continuous deployment (CD). This document explains how these workflows work and how to customize them.
- Overview
- Continuous Integration (CI)
- Continuous Deployment (CD)
- Workflow Badges
- Best Practices
- Troubleshooting
Overview
The .github/workflows/
directory contains two main workflow files:
ci.yml
: Continuous Integration workflow.cd.yml
: Continuous Deployment workflow.
Continuous Integration (CI)
The CI workflow runs automatically on each push and pull request to validate code quality and ensure tests pass.
What It Does
The CI workflow:
- Sets up multiple PHP versions for testing.
- Installs dependencies using Composer.
- Validates Composer configuration.
- Runs PHP CS Fixer to check code style.
- Runs PHPStan for static analysis.
- Runs PHPUnit tests.
- Generates test coverage reports.
Customization
To customize the CI workflow, edit the .github/workflows/ci.yml
file. Common customizations include:
- Changing PHP versions to test against.
- Adding or removing validation steps.
- Modifying test coverage thresholds.
- Changing notification settings.
Example of adding a new PHP version to test against:
# In .github/workflows/ci.yml
jobs:
tests:
strategy:
matrix:
php-version: ['8.3', '8.4'] # Add or remove versions as needed.
Continuous Deployment (CD)
The CD workflow automatically builds and deploys your project documentation to GitHub Pages when changes are pushed to the main branch.
Note: Deployment is disabled by default, just remove the false &&
in the file to enable it.
What It Does
The CD workflow:
- Checks out the repository.
- Sets up Node.js.
- Installs frontend dependencies.
- Builds assets using Vite.
- Sets up PHP.
- Installs Composer dependencies.
- Generates a static website from your project documentation.
- Deploys the static website to GitHub Pages.
GitHub Pages Setup
To use the CD workflow, you need to:
- Enable GitHub Pages in your repository settings.
- Set the source branch to
gh-pages
and the directory to/
(root). - Ensure the workflow has permission to write to the repository.
Customization
To customize the CD workflow, edit the .github/workflows/cd.yml
file. Common customizations include:
- Changing the deployment branch.
- Adding custom build steps.
- Configuring environment variables.
- Adding additional deployment targets.
Example of changing the deployment branch:
# In .github/workflows/cd.yml
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public
publish_branch: documentation # Change from gh-pages to another branch name.
Workflow Badges
You can add workflow status badges to your README.md to show the current status of your workflows:






Replace derafu/project
with your actual GitHub username and repository name.
Best Practices
- Keep workflows fast: Optimize workflows to complete quickly.
- Use caching: Cache dependencies to speed up builds.
- Secure secrets: Use GitHub Secrets for sensitive information.
- Test workflow changes: Test workflow changes on a feature branch before merging to main.
- Monitor workflow runs: Regularly check workflow runs for issues.
Troubleshooting
If a workflow fails:
- Check the workflow run logs in the GitHub Actions tab.
- Verify that all dependencies are correctly installed.
- Ensure environment variables are correctly set.
- Check if tests are failing locally as well.
- Look for GitHub Actions service status issues.
If needed, you can run the workflow manually from the Actions tab by selecting the workflow and clicking “Run workflow”.