Creating Redis service containers

You can use service containers to create a Redis client in your workflow. This guide shows examples of creating a Redis service for jobs that run in containers or directly on the runner machine.

Dans cet article

Remarque

Les exécuteurs hébergés sur GitHub ne sont pas pris en charge sur GitHub Enterprise Server. Vous pouvez voir plus d’informations sur le support futur planifié dans la GitHub public roadmap.

Introduction

This guide shows you workflow examples that configure a service container using the Docker Hub redis image. The workflow runs a script to create a Redis client and populate the client with data. To test that the workflow creates and populates the Redis client, the script prints the client's data to the console.

Remarque

Si vos flux de travail utilisent des actions de conteneurs Docker, des conteneurs de tâches ou des conteneurs de services, vous devez utiliser un programme d'exécution Linux :

  • Si vous utilisez des exécuteurs hébergés sur GitHub, vous devez utiliser un exécuteur Ubuntu.
  • Si vous utilisez des exécuteurs autohébergés, vous devez utiliser une machine Linux en tant qu’exécuteur, et Docker doit être installé.

Prerequisites

Vous devez connaître le fonctionnement des conteneurs de service avec GitHub Actions et les différences de réseau entre une exécution directe des travaux sur l’exécuteur ou dans un conteneur. Pour plus d’informations, consultez « À propos des conteneurs de service ».

You may also find it helpful to have a basic understanding of YAML, the syntax for GitHub Actions, and Redis. For more information, see:

Running jobs in containers

La configuration de travaux à exécuter dans un conteneur simplifie la mise en réseau des configurations entre le travail et les conteneurs de service. Les conteneurs Docker d’un même réseau de pont défini par l’utilisateur exposent tous les ports les uns aux autres. Vous n’avez donc pas besoin de mapper les ports des conteneurs de service à l’hôte Docker. Vous pouvez accéder au conteneur de service à partir du conteneur de travaux à l’aide de l’étiquette que vous configurez dans le workflow.

Vous pouvez copier ce fichier de workflow dans le répertoire .github/workflows de votre dépôt et le modifier selon vos besoins.

YAML
name: Redis container example
on: push

jobs:
  # Label of the container job
  container-job:
    # Containers must run in Linux based operating systems
    runs-on: ubuntu-latest
    # Docker Hub image that `container-job` executes in
    container: node:20-bookworm-slim

    # Service containers to run with `container-job`
    services:
      # Label used to access the service container
      redis:
        # Docker Hub image
        image: redis
        # Set health checks to wait until redis has started
        options: >-
          --health-cmd "redis-cli ping"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    steps:
      # Downloads a copy of the code in your repository before running CI tests
      - name: Check out repository code
        uses: actions/checkout@v4

      # Performs a clean installation of all dependencies in the `package.json` file
      # For more information, see https://docs.npmjs.com/cli/ci.html
      - name: Install dependencies
        run: npm ci

      - name: Connect to Redis
        # Runs a script that creates a Redis client, populates
        # the client with data, and retrieves data
        run: node client.js
        # Environment variable used by the `client.js` script to create a new Redis client.
        env:
          # The hostname used to communicate with the Redis service container
          REDIS_HOST: redis
          # The default Redis port
          REDIS_PORT: 6379

Configuring the container job

Ce flux de travail configure un travail qui s'exécute dans le conteneur node:20-bookworm-slim et utilise l'exécuteur ubuntu-latest comme hôte Docker pour le conteneur. Pour plus d’informations sur le conteneur node:20-bookworm-slim, consultez l’image node sur Docker Hub.

Le workflow configure un conteneur de service avec l’étiquette redis. Tous les services devant s’exécuter dans un conteneur, chaque service exige que vous spécifiiez le conteneur image. Cet exemple utilise l’image conteneur redis et inclut des options de vérification de l’intégrité pour s’assurer que le service est en cours d’exécution. Ajoutez une étiquette au nom de l’image qui spécifie une version, par exemple redis:6. Pour plus d’informations, consultez image redis sur Docker Hub.

YAML
jobs:
  # Label of the container job
  container-job:
    # Containers must run in Linux based operating systems
    runs-on: ubuntu-latest
    # Docker Hub image that `container-job` executes in
    container: node:20-bookworm-slim

    # Service containers to run with `container-job`
    services:
      # Label used to access the service container
      redis:
        # Docker Hub image
        image: redis
        # Set health checks to wait until redis has started
        options: >-
          --health-cmd "redis-cli ping"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

Configuring the steps for the container job

Le workflow effectue les étapes suivantes :

  1. Il extrait le dépôt sur l’exécuteur.
  2. Il installe des dépendances.
  3. Il exécute un script pour créer un client.
YAML
steps:
  # Downloads a copy of the code in your repository before running CI tests
  - name: Check out repository code
    uses: actions/checkout@v4

  # Performs a clean installation of all dependencies in the `package.json` file
  # For more information, see https://docs.npmjs.com/cli/ci.html
  - name: Install dependencies
    run: npm ci

  - name: Connect to Redis
    # Runs a script that creates a Redis client, populates
    # the client with data, and retrieves data
    run: node client.js
    # Environment variable used by the `client.js` script to create a new Redis client.
    env:
      # The hostname used to communicate with the Redis service container
      REDIS_HOST: redis
      # The default Redis port
      REDIS_PORT: 6379

Le script client.js recherche les variables d’environnement REDIS_HOST et REDIS_PORT pour créer le client. Le workflow définit ces deux variables d’environnement dans le cadre de l’étape « Se connecter à Redis » pour les rendre disponibles pour le script client.js. Pour plus d’informations sur le script, consultez Test du conteneur de service Redis.

The hostname of the Redis service is the label you configured in your workflow, in this case, redis. Because Docker containers on the same user-defined bridge network open all ports by default, you'll be able to access the service container on the default Redis port 6379.

Running jobs directly on the runner machine

When you run a job directly on the runner machine, you'll need to map the ports on the service container to ports on the Docker host. You can access service containers from the Docker host using localhost and the Docker host port number.

Vous pouvez copier ce fichier de workflow dans le répertoire .github/workflows de votre dépôt et le modifier selon vos besoins.

YAML
name: Redis runner example
on: push

jobs:
  # Label of the runner job
  runner-job:
    # You must use a Linux environment when using service containers or container jobs
    runs-on: ubuntu-latest

    # Service containers to run with `runner-job`
    services:
      # Label used to access the service container
      redis:
        # Docker Hub image
        image: redis
        # Set health checks to wait until redis has started
        options: >-
          --health-cmd "redis-cli ping"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          # Maps port 6379 on service container to the host
          - 6379:6379

    steps:
      # Downloads a copy of the code in your repository before running CI tests
      - name: Check out repository code
        uses: actions/checkout@v4

      # Performs a clean installation of all dependencies in the `package.json` file
      # For more information, see https://docs.npmjs.com/cli/ci.html
      - name: Install dependencies
        run: npm ci

      - name: Connect to Redis
        # Runs a script that creates a Redis client, populates
        # the client with data, and retrieves data
        run: node client.js
        # Environment variable used by the `client.js` script to create
        # a new Redis client.
        env:
          # The hostname used to communicate with the Redis service container
          REDIS_HOST: localhost
          # The default Redis port
          REDIS_PORT: 6379

Configuring the runner job

L'exemple s'appuie sur l'exécuteur ubuntu-latest en tant qu'hôte Docker.

Le workflow configure un conteneur de service avec l’étiquette redis. Tous les services devant s’exécuter dans un conteneur, chaque service exige que vous spécifiiez le conteneur image. Cet exemple utilise l’image conteneur redis et inclut des options de vérification de l’intégrité pour s’assurer que le service est en cours d’exécution. Ajoutez une étiquette au nom de l’image qui spécifie une version, par exemple redis:6. Pour plus d’informations, consultez image redis sur Docker Hub.

The workflow maps port 6379 on the Redis service container to the Docker host. For more information about the ports keyword, see À propos des conteneurs de service.

YAML
jobs:
  # Label of the runner job
  runner-job:
    # You must use a Linux environment when using service containers or container jobs
    runs-on: ubuntu-latest

    # Service containers to run with `runner-job`
    services:
      # Label used to access the service container
      redis:
        # Docker Hub image
        image: redis
        # Set health checks to wait until redis has started
        options: >-
          --health-cmd "redis-cli ping"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
        ports:
          # Maps port 6379 on service container to the host
          - 6379:6379

Configuring the steps for the runner job

Le workflow effectue les étapes suivantes :

  1. Il extrait le dépôt sur l’exécuteur.
  2. Il installe des dépendances.
  3. Il exécute un script pour créer un client.
YAML
steps:
  # Downloads a copy of the code in your repository before running CI tests
  - name: Check out repository code
    uses: actions/checkout@v4

  # Performs a clean installation of all dependencies in the `package.json` file
  # For more information, see https://docs.npmjs.com/cli/ci.html
  - name: Install dependencies
    run: npm ci

  - name: Connect to Redis
    # Runs a script that creates a Redis client, populates
    # the client with data, and retrieves data
    run: node client.js
    # Environment variable used by the `client.js` script to create
    # a new Redis client.
    env:
      # The hostname used to communicate with the Redis service container
      REDIS_HOST: localhost
      # The default Redis port
      REDIS_PORT: 6379

Le script client.js recherche les variables d’environnement REDIS_HOST et REDIS_PORT pour créer le client. Le workflow définit ces deux variables d’environnement dans le cadre de l’étape « Se connecter à Redis » pour les rendre disponibles pour le script client.js. Pour plus d’informations sur le script, consultez Test du conteneur de service Redis.

Le nom d’hôte est localhost ou 127.0.0.1.

Testing the Redis service container

You can test your workflow using the following script, which creates a Redis client and populates the client with some placeholder data. The script then prints the values stored in the Redis client to the terminal. Your script can use any language you'd like, but this example uses Node.js and the redis npm module. For more information, see the npm redis module.

You can modify client.js to include any Redis operations needed by your workflow. In this example, the script creates the Redis client instance, adds placeholder data, then retrieves the data.

Ajoutez un nouveau fichier appelé client.js à votre dépôt avec le code suivant.

JavaScript
const redis = require("redis");

// Creates a new Redis client
// If REDIS_HOST is not set, the default host is localhost
// If REDIS_PORT is not set, the default port is 6379
const redisClient = redis.createClient({
  url: `redis://${process.env.REDIS_HOST}:${process.env.REDIS_PORT}`
});

redisClient.on("error", (err) => console.log("Error", err));

(async () => {
  await redisClient.connect();

  // Sets the key "octocat" to a value of "Mona the octocat"
  const setKeyReply = await redisClient.set("octocat", "Mona the Octocat");
  console.log("Reply: " + setKeyReply);
  // Sets a key to "species", field to "octocat", and "value" to "Cat and Octopus"
  const SetFieldOctocatReply = await redisClient.hSet("species", "octocat", "Cat and Octopus");
  console.log("Reply: " + SetFieldOctocatReply);
  // Sets a key to "species", field to "dinotocat", and "value" to "Dinosaur and Octopus"
  const SetFieldDinotocatReply = await redisClient.hSet("species", "dinotocat", "Dinosaur and Octopus");
  console.log("Reply: " + SetFieldDinotocatReply);
  // Sets a key to "species", field to "robotocat", and "value" to "Cat and Robot"
  const SetFieldRobotocatReply = await redisClient.hSet("species", "robotocat", "Cat and Robot");
  console.log("Reply: " + SetFieldRobotocatReply);

  try {
    // Gets all fields in "species" key
    const replies = await redisClient.hKeys("species");
    console.log(replies.length + " replies:");
    replies.forEach((reply, i) => {
        console.log("    " + i + ": " + reply);
    });
    await redisClient.quit();
  }
  catch (err) {
    // statements to handle any exceptions
  }
})();

The script creates a new Redis client using the createClient method, which accepts a host and port parameter. The script uses the REDIS_HOST and REDIS_PORT environment variables to set the client's IP address and port. If host and port are not defined, the default host is localhost and the default port is 6379.

The script uses the set and hset methods to populate the database with some keys, fields, and values. To confirm that the Redis client contains the data, the script prints the contents of the database to the console log.

When you run this workflow, you should see the following output in the "Connect to Redis" step confirming you created the Redis client and added data:

Reply: OK
Reply: 1
Reply: 1
Reply: 1
3 replies:
    0: octocat
    1: dinotocat
    2: robotocat