CI with GitHub Actions

At long last, it's time to share our bundle with the world!

First though, we'll add the configuration needed for GitHub Actions to run our tests, static analysis, and verify our coding standards.

In our bundle root, add the following directory and subdirectory: .github/workflows. Copy the ci.yml file from the tutorial directory into workflows:

Or copy it from the script below if you can't find it.

Understanding the GitHub Actions Workflow

There's a lot to unpack here, so let's dive in! The on section defines the events that will trigger our workflow. We want it to run when code is pushed or a pull request is created or modified. Additionally, this cron schedule ensures the workflow runs twice a month, on the 1st and 16th. This is useful for ensuring it continues to work with the latest dependencies.

Next, we configure the jobs. Our first one, tests is what runs our test suite across multiple PHP and Symfony versions. It does this by using the matrix strategy to create combinations of jobs. We have it running on PHP 8.2, 8.3, and 8.4, and Symfony versions 6.4, 7.3, and 7.4. A job will be created for each permutation of these values. This include adds a special custom case to the matrix, one that runs on our lowest supported PHP version, 8.2 and with the prefer-lowest Composer option.

Next, the steps for this job. First, we're using the checkout action that pulls down the code.

This setup-php action, you guessed it, installs PHP. Notice this with: version: is set to a matrix.php variable. These variables are how you customize the job based on matrix values. We're also passing tools: flex - this installs Symfony Flex globally.

The composer-install action installs our bundle's dependencies. For dependency-versions, we're passing the matrix.deps variable. If we look back up at our matrix, we see this is always set to highest, except for our special case where it's lowest. We're passing the SYMFONY_REQUIRE environment variable as matrix.symfony to specify which Symfony version to install.

Finally, the last step runs our test suite with vendor/bin/phpunit.

PHPStan and PHP-CS-Fixer Jobs

Our next job is static-analysis, which runs PHPStan. This job is much simpler as it doesn't have a matrix. It's best to run static analysis on the latest version of PHP, 8.4 in our case, to catch the most issues.

For the php-cs-fixer job, we run it on our lowest supported PHP version, 8.2, to ensure it doesn't suggest fixes that aren't compatible with that version. I've also added the flags --dry-run and --diff to the command so it won't actually change any files, but will show a diff of what needs to be changed in the action output.

Creating the Repository

Now to create the GitHub repository! Head over to GitHub and create a new repository by clicking the plus icon in the top right and selecting New repository.

For the owner, I'm going to choose the SymfonyCasts organization, but you can select your personal account if you want to follow along. For the description, I'll just copy it from our composer.json file. Visibility? I'm going to make it public because I'll be publishing this to Packagist.

Don't change anything else here, we don't want any code generated by GitHub.

Hit Create repository! We're now on the empty repository page.

Initial Commit

Locally, we need to initialize a new git repository for our bundle. Our bundle lives within a Symfony app, which is its own git repository. A git repository inside another git repository can be annoying to deal with, so, let's pull it out.

At your terminal, navigate to a directory outside of your Symfony app and run:

cp -R path/to/your/symfony/project/object-translation-bundle ./

This recursively copies the bundle directory to your current location. Navigate to the new object-translation-bundle directory and run:

git init --initial-branch=1.x

By default, the initial branch is called main, using 1.x helps distinguish between different major version branches later on. A version 2 of our bundle would be developed on a 2.x branch.

Now run:

git add .

To stage all the files. Over on our empty GitHub repository page, copy the command to add the remote origin: git remote add origin... and paste into the terminal.

Then commit the files with:

git commit -m "Initial commit"

Now, copy the git push command from GitHub, paste it to your terminal, changing main to 1.x, and run it:

git push -u origin 1.x

Back on GitHub, refresh the page... Nice! Here's our bundle code! Our readme looks like it's rendered correctly, and we even have this nifty table of contents.

Our license was also detected.

If we click the Actions tab, we can see our workflow ran, and it looks like it was successful! Click into it to see the individual jobs.

These jobs that start with PHP are the different permutations created from our matrix. If we jump into one, we can see each step. Expanding the Test step shows the PHPUnit output.

We can also see the output from our PHPStan and PHP-CS-Fixer jobs.

Now that our bundle is hosted on GitHub, we can publish it to Packagist - that's next!