Working With Git Submodules

This section shows how to add a git submodule to your FoundriesFactory™ Platform repository. This is used when you want an external Git repository, such as GitHub, connected to a Factory repository as a submodule.

Submodules can be used to isolate two different application teams, allowing work to take place in separate repositories. Each team works in their own repository and each repository is added as a submodule in the Factory repository.

Tip

The steps to add a submodule can be adapted for other git repository hosting services.

Create a GitHub Repository

Go to GitHub and create a new repo. You can choose to use a private or public repository, each involves separate steps:

PrivatePublic

Select Private and Create repository.

Fig. 27 New Private GitHub repository

The FoundriesFactory CI needs a GitHub personal access token to download the submodule content during the build. Many organizations require the recommended Fine-grained tokens be used. Follow GitHub’s instructions to generate the token. Copy the personal access token.

Now Configure your Factory with the personal access token. Use fioctl to configure the githubtok variable:

fioctl secrets update githubtok=<PERSONAL_TOKEN>

Preparing the GitHub Repository

For this guide, the GitHub repo will be used to specify a Docker Compose Application. The requirements for the FoundriesFactory CI to build this is to have a folder with a Dockerfile and a docker-compose.yml If you are not familiar with the containers.git file structure, see the section on File Structure.

Create a folder to initialize the repo.

mkdir myapp
cd myapp/
git init
git remote add origin [email protected]:munoz0raul/myapp.git

Add the shellhttpd files as reference:

git remote add fio https://github.com/foundriesio/extra-containers.git
git remote update
git checkout remotes/fio/tutorials -- shellhttpd

Your repository folder should be the folder containing the application files. Move it from the shellhttpd folder to the repo root directory:

git mv shellhttpd/Dockerfile shellhttpd/docker-compose.yml shellhttpd/httpd.sh .
git rm -r shellhttpd/

You have the files required for a Docker Compose Application:

tree ../myapp/

../myapp/
├── docker-compose.yml
├── Dockerfile
└── httpd.sh

Update the image url in docker-compose.yml with your repo’s name. This example uses myapp:

docker-compose.yml:

version: '3.2'

services:
  httpd:
    image: hub.foundries.io/${FACTORY}/myapp:latest
    build: .
    restart: always
    ports:
      - 8080:${PORT-8080}
    environment:
      MSG: "${MSG-Hello world}"

Add all new files, changes and commit and push:

git add docker-compose.yml Dockerfile httpd.sh
git commit -m "Adding App Structure"
git push

Adding the Submodule

Clone your containers.git repo and enter its directory:

git clone https://source.foundries.io/factories/<factory>/containers.git
cd containers

Tip

If you followed the tutorials, your containers.git might have the shellhttpd app already. If that is the case, to avoid conflict with the submodule example remove or move it to shellhttpd.disabled

Inside the containers directory, adapt the command below using your GitHub repo:

git submodule add [email protected]:<user>/<repository>.git

git submodule add -b devel [email protected]:munoz0raul/myapp.git
cd myapp
git add myapp/
git commit -m "Adding myapp submodule"
git push

Go to the web app, select your Factory and click on Targets. The latest Target should be the CI job you just created. Click anywhere on the Target’s line to see more details.

After the CI Job finishes, refresh the page and find your application in Apps:

Fig. 29 Submodule Application

In your Factory, click on Source and select the container.git repository:

Fig. 30 Containers Repository

Note the application submodule is available but it is not possible to inspect the application files.

Updating the Submodule Manually

The submodule inside containers.git is pinned to the latest GitHub repo commit. As new commits are added, containers.git must be updated with the latest submodule changes. It is possible to do it manually or using GitHub Actions.

To update it manually, go to your containers folder, inside the submodule and run:

cd containers/
git submodule update --remote ./myapp
git add myapp
git commit -m "Updating submodule hash"
git push

Updating the Submodule Automatically

To automate the previous steps, you have to allow GitHub to access your Factory repo. For that, you need to create a token.

Go to Tokens and create a new Api Token by clicking on + New Token.

Complete with a Description and the Expiration date and select next.

For GitHub, check the Use for source code access box and select your Factory.

Fig. 31 Token for source code access

Copy the token, go to the GitHub repo and find Settings.

Fig. 32 Repository Settings

Select Secrets in the left menu and New repository secret.

Name it with FOUNDRIES_API_TOKEN, paste your <Token> on Value and click on Add Secret:

Fig. 33 Action Token

Create .github/workflows/source-fio-update.yml inside your GitHub application repo. Follow the example below and make sure you update <FACTORY_NAME> with your Factory, and <SUBMODULE_FOLDER> with your submodule folder.

cd myapp/
mkdir -p .github/workflows/
vi .github/workflows/source-fio-update.yml

# .github/workflows/source-fio-update.yml

name: Update source.foundries.io

on:
  push:
    branches: [ devel ]

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
    # Checks-out your repository under $GITHUB_WORKSPACE
    - uses: actions/checkout@v2
    - uses: doanac/gh-action-update-submodule@master
      with:
        remote-repo: https://source.foundries.io/factories/<FACTORY_NAME>/containers.git
        api-token: ${{ secrets.FOUNDRIES_API_TOKEN }}
        submodule-path: "./<SUBMODULE_FOLDER>"
        remote-branch: ${{ github.ref }}

Add then commit your GitHub Action:

git add .github/workflows/source-fio-update.yml
git commit -m "Adding Action"
git push

After this commit, the submodule should be automatically updated inside the containers.git repo. As a result, it will automatically trigger a new CI Job to build your application.