# Using GitHub Actions

It is possible to build a Mapeo configuration file using GitHub Actions. This requires setting up your custom configuration directory as a repository on [Github.com](https://github.com/), adding a `/.github/workflows/build.yml` script to your repository, and committing changes to that repository.  

{% hint style="info" %}
If you haven't already used GitHub, you may want to study the [basics](https://docs.github.com/en/get-started/using-git/about-git) of how GitHub works before proceeding.
{% endhint %}

{% hint style="warning" %}
Note that since this process relies on using github.com, that you will need internet access to run the build action and download the `.mapeosettings` configuration file. Hence, unlike building a configuration [preparing-computer](https://docs.mapeo.app/espanol/guia-de-referencia-completa/customization-options/custom-configurations/creating-custom-configurations/codificar-la-configuracion/building-configuration-file/preparing-computer "mention"), this process will not work in an offline context.
{% endhint %}

## Setting up a configuration repository on GitHub

The first step will be to set up your configuration as a repository on github.com, with the requisite build script files that will trigger a GitHub Actions **Workflow** to generate your `.mapeosettings` file. There are a few ways to do this.

*If you do not have your own custom configuration already, and are starting from scratch:*

1. You can fork or upload either the [Mapeo Default Configuration](https://github.com/digidem/mapeo-default-config) or the [Empty Mapeo Configuration](https://github.com/digidem/empty-mapeo-config) template to your own GitHub account. The choice you make will depend on how you will go about creating your own configuration, as detailed in [planeando-la-configuracion-y-la-estructura-de-datos](https://docs.mapeo.app/espanol/guia-de-referencia-completa/customization-options/custom-configurations/creating-custom-configurations/planeando-la-configuracion-y-la-estructura-de-datos "mention").
2. Make sure that you have the `.github/workflows` directory in your configuration repository.

*If you already have your own custom configuration:*

1. Create a repository on GitHub for your custom configuration.
2. Commit your existing configuration content to the repository.
3. Download either the [Mapeo Default Configuration](https://github.com/digidem/mapeo-default-config) or the [Empty Mapeo Configuration](https://github.com/digidem/empty-mapeo-config), and copy over the `.github` directory to the root directory of your custom configuration. 
4. Commit these files to your repository on Github.com. (*Github may ask you for additional permissions to add these files, by confirming via the browser.)*

{% hint style="info" %}
**NOTE:** Depending on your operating system and setup, it is possible that you do not see a `.github/` directory anywhere. You may need to enable viewing hidden files in your system file manager.\
\
On MacOS, you can do so by pressing **Command + Shift + .** (period) in your Finder window.
{% endhint %}

## Getting ready to build

Navigate to the **Actions** screen, and Click "I understand my workflows, go ahead and enable them."

![](https://899367650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwQtYf2Of1RvO9LwnloQQ%2Fuploads%2FeVTMrmo6wn9Rmowv4Yda%2FGithub-Actions-1.JPG?alt=media\&token=77f8a354-d3ed-401d-8be2-8e8b07704882)

This will bring you to a view of your **Workflows**. You should see a message "There are no workflow runs yet" if you just enabled **Workflows** for the first time. You are now ready to start building `.mapeoconfig` files.

## How it works

Once you have enabled Action **Workflows** on your configuration repository, GitHub will generate a **Workflow** to build a new version of your configuration every single time that you commit a change to your repository.  

Once you have committed a change to your repository, and navigate to the **Actions** tab, you should see your commit message listed as a workflow.

![](https://899367650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwQtYf2Of1RvO9LwnloQQ%2Fuploads%2FOqCoeSjYSk0RD9kFDDNV%2FGithub-Actions-2.JPG?alt=media\&token=09f13c23-5613-487b-b8db-388e19ca99e5)

* :white\_check\_mark: a circular check indicates that the build has completed successfully.
* :yellow\_circle: a yellow circle indicates that the build is in process.
* :red\_circle: a red circle with an X indicates that the build has encountered an error.

You can click on your commit message to find out more about the status of your build. For example, if your build has encountered an error, there will be a log that can give you an idea of what went wrong. You can commit a change to fix the error, and return to the **Actions** screen to see if a new **Workflow** successfully bypasses the problem.

![](https://899367650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwQtYf2Of1RvO9LwnloQQ%2Fuploads%2FwoPtjSoeiBcrYkGq4G9k%2FGithub-Actions-3.JPG?alt=media\&token=c8236113-f0fe-4bea-ad7d-6631d3420574)

{% hint style="info" %}
This is the same log that you would see when building a configuration [preparing-computer](https://docs.mapeo.app/espanol/guia-de-referencia-completa/customization-options/custom-configurations/creating-custom-configurations/codificar-la-configuracion/building-configuration-file/preparing-computer "mention").
{% endhint %}

By opening the **Workflow** with your commit message, you can also download a `.zip` file of your configuration, which includes a temporary `.mapeosettings` file. This is helpful for testing out your configuration before building a versioned file to distribute to users, as described in [probando-e-iterando](https://docs.mapeo.app/espanol/guia-de-referencia-completa/customization-options/custom-configurations/creating-custom-configurations/probando-e-iterando "mention").

## Use conventional commit messages to increment your configuration version

The Mapeo GitHub Actions **Workflow** is set up to dynamically bump the version of your configuration per each workflow. It does so using [conventional commit messaging](https://www.conventionalcommits.org/en/v1.0.0-beta.2/) of adding `feat:`, `fix:`, or `chore:` before your commit message. For example, if you have a configuration with version **1.1.0**, the specific version bumps are as follows:

* `feat`: this will increase your version to **1.2.0**. This commit prefix could be used for major configuration updates.
* `fix`: this will increase your version to **1.1.1**. This commit prefix could be used for small updates like changing an icon, or adding a field to a category.
* `chore`: this will not increase your version. This commit prefix could be used for correcting typos or fixing errors.

{% hint style="info" %}
To see a few examples of configuration conventional commit messaging, see the screenshot above in [#how-it-works](#how-it-works "mention"), or check out the commit history on the [Mapeo Default Configuration](https://github.com/digidem/mapeo-default-config/commits/master) repository.
{% endhint %}

You can also manually update the first number in your **1.1.0** version in your `package.json` file, but Digital Democracy's convention is to only do so to indicate breaking changes. That said, you are free to choose a versioning convention that makes the most sense to you.

## Compile a final, versioned release of your configuration

Once you are done making changes, have tested your configuration using a temporary `.mapeosettings` file (as described in [#how-it-works](#how-it-works "mention")) and in accordance to the process described in [probando-e-iterando](https://docs.mapeo.app/espanol/guia-de-referencia-completa/customization-options/custom-configurations/creating-custom-configurations/probando-e-iterando "mention"), you can generate a versioned release of your configuration. The way to do so is as follows:

* Navigate to the **Actions** tab for your GitHub repository. You should see all of your **Workflows** again.
* On the left sidebar, click on the **Build & Release** link.
* You should now see a box with the text "This workflow has a `workflow_dispatch` event trigger" and a button **Run workflow**. Click the button, and then click **Run workflow** again in the popup that will appear.

![](https://899367650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwQtYf2Of1RvO9LwnloQQ%2Fuploads%2F9kYNzOjjbOJ9K9jl8Kqe%2FGithub-Actions-5.JPG?alt=media\&token=2bb29f2f-5543-459c-8e5a-197dc1849f7f)

* Doing so will trigger another **Workflow** titled "Build and Release."
* When that finished with a :white\_check\_mark: green check mark, your versioned build release will be ready. On the top navigation bar, click on **Code** and your release should appear under the **Releases** panel in the right sidebar.

![](https://899367650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwQtYf2Of1RvO9LwnloQQ%2Fuploads%2Fw44yHsUhF1cxDyPz798K%2FGithub-Actions-6.JPG?alt=media\&token=d9760743-c75c-44c4-8a45-77d55e7290e8)

* Click on the release to download the versioned `.mapeosettings` file.